Re: [Axiom-developer] Desired functionality from noweb

[Ralf Hemmecke]

> I'm trying to reconcile that idea with an "Axiom Journal" style of
> writing where people may do shorter papers on a single topic.

Oh, I am fully aware of the Axiom Journal idea. And I completely support 
that. But besides the LaTeX issue, there is also the code issue. The 
Axiom Journal is basically Axiom itself (or rather the part that deals 
with Mathematics). In general there might be different "papers" that 
extend Axiom in different an incompatible ways. An "official" Axiom 
could then be seen as a compatible selection of the Journal papers. 
Though, of course, everyone is free to build is own Axiom. I guess, we 
will soon end up with different branches.

So the whole Journal idea needs a lot more of thought than just the 
LaTeX issue. For me the time is not yet ripe, but I am always thinking 
in the journal direction.

> I am thinking about build times for Axiom.  Tim has stated that the
> goal is to treat building documentation on an equal footing with
> building machine binaries, so build time is impacted by documentation
> decisions.  That's the whole reason Waldek proposed and implemented the
> finite-state approach to tangle, and when I asked the list if it was
> really necessary the consensus was yes.  

I am not building Axiom 10 times a day, but rather a (relatively small) 
library. If there is something faster available than noweb with the same 
functionality, I could probably switch easily.

> > > I tend to think of it as one pamphlet = 1 "concept", and then
> > > pamphlets would be bundled like conference proceedings to make
> > > larger volumes.

OK. For me then a "concept" is like a collection of files (call it 
pamphlet or not). I simply want to have reasonable file sizes and 
different languages in different files.

> > If everything is put into html form on a website what 
> > disadvantage would that have?
>
> Compared to LaTeX+pdf html is (at the moment) not as convenient for
> mathematical output.  Since Axiom is intended to support advanced
> mathematical research robust mathematical typesetting/output is a must.

OK. But there are also ways to link different .dvi and .pdf files 
together. (That was shown by Tim.) That still means one can keep the 
projects/libraries/concepts separate documents and still interlink.

> > > In essence, links that move the reader through the document in the
> > > order in which the machine would see the code?  That's not a bad
> > > idea.  Hmm...
> > But that is only for chunks that have the same name. They are
> > combined together in the order they apper in a .pamphlet. The rest
> > appears as a hierarchy.
>
> ?  I'm a bit confused.  I thought chunk names had to be unique within a
> pamphlet.

Try
%---BEGIN aaa.pamphlet
<<*>>=
<<X>>
A
@
<<X>>=
EFG
@
<<*>>=
B
@
<<C>>=
UVW
@
%---END aaa.pamphlet

notangle aaa.pamphlet
EFG
A
UVW
B

> > I don't use language awareness in ALLPROSE. Aldor is not build-in
> > into noweb anyway and I did not know how to write an appropriate
> > noweb filter to add language support for Aldor, so my filters start
> > before noweave sees the file. Anyway, if we start putting several
> > different languages into one pamphlet, it will be difficult to guess
> > the language if there is no explicit tag.
>
> Agreed - I think it would be a bad idea to have more than one language
> per pamphlet.  If we must do so an explicit tag for language is needed.

In fact, I am not 100% sure whether it is a bad idea to have several 
languages in one file. The reason is that sometimes one describes a 
target in a Makefile, for example, and that would use some perl script.
If the perl script is only used for that target then it might be a good 
idea to place the script+documentation right next to the description of 
the make target. I simply have not enough experience in LP to decide 
what is better. And there may be different tastes.

> > Very important for me is that the pamphlet -> latex routine respects
> > line numbers as noweave does. Every documentation chunk should be 
> > wrapped by something like \begin{docchunk} ... \end{docchunk} and
> > every code chunk by \begin{codechunk}{name} ... \end{codechunk} (or
> > something similar.
>
> Code chunks I've got wrapped in listing environments, but why do you
> want the documentation chunks identified?  I always viewed pamphlet
> files as a latex document with chunks embedded in it - what is the
> advantage of chunking up the documentation as well?

That line numbering in the .tex is *identical* to the .pamphlet file is 
needed for the inverse search feature.

What is the disadvantage of \begin{docchunk} ... \end{docchunk}? You can 
define it as

\newenvironment{docchunk}{}{}

but without any need to re-weave, you could also compile against another 
style file which has

\usepackage{verbatim}
\newenvironment{docchunk}{\comment}{\endcomment}

and you would only see code in the .dvi file. (It's just an example.)
Try to look at the output of

noweave aaa.pamphlet

it also produces something like

\documentclass{article}\usepackage{noweb}\pagestyle{noweb}\noweboptions{}\begin{document}\nwfilename{aaa.pamphlet}\nwbegindocs{0}%---BEGIN 
aaa.pamphlet% ===> this file was generated automatically by noweave --- 
better not edit it
\nwenddocs{}\nwbegincode{1}\moddef{*}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup
\LA{}X\RA{}
A
\nwendcode{}\nwbegindocs{2}\nwdocspar
\nwenddocs{}\nwbegincode{3}\moddef{X}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup
EFG
\nwendcode{}\nwbegindocs{4}\nwdocspar
\nwenddocs{}\nwbegincode{5}\moddef{*}\plusendmoddef\nwstartdeflinemarkup\nwenddeflinemarkup
\LA{}C\RA{}
B
\nwendcode{}\nwbegindocs{6}\nwdocspar
\nwenddocs{}\nwbegincode{7}\moddef{C}\endmoddef\nwstartdeflinemarkup\nwenddeflinemarkup
UVW
\nwendcode{}\nwbegindocs{8}\nwdocspar
%---END aaa.pamphlet
\nwenddocs{}\end{document}

So noweave even adds chunk numbers which one can ignore in the .sty file.

Ralf