Re: [Axiom-developer] build-improvements and latex

[Ralf Hemmecke]

> > > 3) Files with unnecessarily long names are more awkward to use.
> > > Ok I admit that reasons 2) and 3) are not very strong reasons...
> > Not even 1) is a reason. Why do you believe one can say
> >
> > make dvi
> >
> > in ALLPROSE and then say
> >
> > xdvi myalps.dvi
> >
> > to get the whole documentation although I have the convention
> > notangle removes .nw
> > noweave adds .tex  (result is .nw.tex)
> > ?
>
> Good question. If the rule is "add .tex" then the result is
>
>   latex myalps.nw.tex --> myalps.nw.dvi
>
> not myalps.dvi. You must be doing something more to hide the .nw.
>
> Your suggestion would require that we use awkwqard names like
>
>   xdvi axiom.sty.pamphlet.dvi
>
> No?

Wow. I must be doing something wrong. I already question whether I 
should use German to get my idea through. English doesn't seem to work. ;-)

OK. Let me repeat. In ALLPROSE and any project that is built with 
ALLPROSE there are many files. All of them have the extension .nw 
(forget about README, GPL and that). Actually all have a second 
extension. So the general form is file.ext.nw. Now my Makefile basically 
have the rule that notangle removes .nw and noweave adds .tex.

There is only *one* dvi file that will be produced and *not* one for 
every .nw file. So "xdvi axiom.sty.pamphlet.dvi" is absolutely no 
argument. One should not even look at something like 
axiom.sty.pamphlet.tex, because that is generated and could look like a 
big mess --- if you have really looked at files that come out of noweave 
you will know that theses files are not for humans even if they are .tex 
files.

So now the trick why I don't have myalps.nw.dvi.

The top-level project file is called myalps.tex.nw. Applying my rules 
gives myalps.tex and myalps.tex.nw.tex. The first one is just a wrapper 
that in shortended form looks like

\documentclass{article}
\usepackage{allprose}
\begin{document}
\author{Ralf Hemmecke}
  \title{\xProject{} \LIBRARYVERSION}}
  \maketitle
  \begin{abstract}
  ...
  \end{abstract}
\hypertarget{sec:Contents}{}\tableofcontents
\input{\projectname.tex.nw}
\end{document}

and that will be latex'ed. As you can see, it's some kind of template.
And my Makefiles make sure that the setup will be such that all other 
.nw.tex files will be included into the documentation.


There is another point that speaks against the current practise of 
translating each .pamphlet file into one .dvi, namely "literate 
programming". Ideas don't just live in one file. That completely misses 
the point that there are relations from one part of the system to 
another. For example, there should not be 5 Makefile.dvi files lying 
around in different directories. Since the build procedure should be 
described as a whole.

It would better to describe the interpreter as a whole rather than 
producing a .dvi file for each of the 187 files in src/interp.
Tim's approach (if I understood that correctly) is to make *one* huge 
.pamphlet file.
My approach is to have as many pamphlet file as you like but produce 
*one* human readable document from all of them to describe a _unit_ 
(i.e. the interpreter).

Eventually, we perhaps want just one document (a web-site, for example) 
that describe all of axiom (including the source code). For a web site 
the size doesn't matter. But still, there should be some backlinks from 
the human-readable format (.dvi) to the actual .pamphlets.


> > There will never be generated anything else than one dvi file.
> > And I don't understand, why people care so much about the names
> > of intermediate files. You can remove .nw.tex files and no harm 
> > is done. If make would already remove them, one would not even
> > see what strange things are done under the hat.
>
> I don't think anyone is that worried about internal file names,
> but this discussion is about making the makefiles "simpler" and
> more obvious, so we do care what goes on under the hat, right?

Of course, we care about Makefiles and conventions and such but as long 
as that becomes simple, generated file names can be complicated.

> Using a file name for dvi files that retains the original
> .pamphlet extension is not so obvious to me.

I hope, this time my English is understandable.

> > But that naming scheme simplifies the understanding of the 
> > system (only in my opinion, of course). One doesn't have to
> > rename axiom.sty.pamphlet to axiom-sty.pamphlet.
>
> In my opinion it is only an accident that axiom.sty.pamphlet
> has this name and contains only one root chunk. In general this
> is not the case.
>
> > So the only reason I see not to just add ".tex" would be portability. 
> > But which are systems we want to build Axiom on that cannot 
> > handle two dots?

> I would guess: none.

I agree. Other opinions concerning filename portability?

Ralf