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

[root]

> Up to now I thought the format is like the one in noweb, but already 
> with your patch to noweb, you modified that. Without a documented format 
> we end up like SPAD is now. A language without formal specification. 
> Good luck.

It seems that you've tripped across a noweb bug and called it a feature.
The noweb tool mangles files. We need to fix it.

The [[ form is valid axiom syntax and should not be wholly owned by noweb.
(e.g [[1,2],[3,4]]). We can step around the noweb bug by simply placing a
space between the [[ form (e.g [ [) in the Rosetta document. I did that 
in the Axiom book. Or we could outlaw the [[ noweb form, since it is
trivial to write the correct latex.

In all of axiom there are straight latex files and many that include
extensions for including code in a verbatim manner. These are the
only features in use that I'm aware of:

0) straight latex, the base case

1) Definition and use, hashing strings to text blocks

<<chunk>>=
@

<<chunk>>

2) Definition extension, adding to existing hash entries

<<chunk>>=
@
<<chunk>>=
@

3) special symbol quoting, latex synomym for \verb usage

[[thing]]


If we were to require that ALL files MUST be passed thru noweb then
there are more changes required to noweb.  In particular, noweb needs
to ensure that it produces a valid latex file from a latex file. It
can do this by inserting a \usepackage if it finds <<>>= or [[]] usage
and one is not provided. Or it should "inline" the noweb latex definitions.
Or if there is no \usepackage for noweb, then do nothing harmful.

Although noweb implements three of four features I don't see it as a
requirement. Indeed there has been discussion of other formats such as

* ALLPROSE, 
* "booklets", which are pamphlets where the chunk names optionally 
              contain URIs, see src/doc/booklet.c.pamphlet
* latex macro forms which replace the <<>> syntax with 
              \begin{chunk}{chunkname}, not yet public.

I agree that it is reasonable to try to define what a pamphlet file
format is and that we should create a DOCUMENT command and style files
that handles any valid pamphlet file correctly. Indeed, that was the
original motivation for the document command; to hide these details.

But we haven't even figured out how we plan to handle multiple
embedded \usepackage lines, hyperlinks, indexing, bibtex,
animated gifs, or video clips.

I think that we need to lift our eyes away from "what is" and focus
a bit on the future. It is too early to state that noweb is THE format 
that will carry us onward. Drag-and-drop allows dragged files to be
exported in more than one format which may require additional support
within the pamphlet file structure. Pamphlet files need to consider
cases of standalone, embedded (e.g. as book chapters), and 
conflated (collections of partial sections into "topical booklets"
that slice "across pamphlets" such as an ALL-MATRIX booklet")
files which the document command might produce.

The 30-year-horizon won't be reached by limiting our imagination
to our current tools. Research projects demand experimentation,
not standardization. The question of what is a valid pamphlet
file requires definition, not standardization. We need to be able
to expand, extend, and warp the definition as we learn, not fix
on a trivial preprocessing tool as "the standard". 

Think 30 year horizon.

t