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

[Page, Bill]

On Wednesday, November 08, 2006 5:18 PM Ralf Hemmecke wrote:
> ... 
> 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. ;-)
> ... 
> 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.
> 

Ok, thank you! I finally understand what you are saying. :-)

  axiom.sty.pamphlet.tex

is never processed by

  latex axiom.sty.pamphlet.tex

Maybe it would be much less confusing if these files did not have
the extension .tex. Why not something like

  axiom.sty.pamphlet.inc

to make it clear that we will not be directly apply latex to this
file?

> 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 shortened 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.

Ok, so this is a file that we do not currently have in any of the
Axiom directories, right? We would have to create at least one for
each src directory.

> 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.
>

Ok.
 
> 
> There is another point that speaks against the current practice
> 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.

I agree.

> 
> 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).

Yes, I like your approach much more than Tim's book volumes even
though the end result for the user is nearly the same. Nice.

> 
> 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.
> 

Ok.

> ... 
> > 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.
>

Yes certainly. I don't think the problem is your English. It
just takes time to say the critical things so that someone
else can appreciate a beautiful idea.
 
> ...

But now I understand, I do feel like I have to take a step back
and because this is an even bigger change then what I incorrectly
thought you were suggesting - instead of changing nearly 1000 files
we would probably be reducing the number of dvi files to less than
100. I think that might take some planning - as you originally
suggested - but I am starting to agree that the result would be
worth it.

Thanks again for your patience.

Regards,
Bill Page.