axiom-developer
[Top][All Lists]

## Re: [Axiom-developer] Desired functionality from noweb

 From: Ralf Hemmecke Subject: Re: [Axiom-developer] Desired functionality from noweb Date: Tue, 08 May 2007 10:45:40 +0200 User-agent: Thunderbird 2.0.0.0 (X11/20070326)

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