[Axiom-developer] Pamphlet files and Axiom

[C Y]

As near as I can tell, the question about tools used is not really the
important one for Axiom at this time.  Choosing tools to use is easily
handled at build time.  Of more importance is the details of how to
specify a chunk.

Axiom+Noweb currently uses the syntax 

<<chunkname>>=

@

This has the merit of being quickly typed, and simple to see and
understand.  Noweb also seems to permit variations on this theme.

When noweb performs its weave step, it substitutes the delimiters in
the chunk structure with more elaborate LaTeX commands.

Axiom's current default weave usage does not make use of the full power
of noweb's weave logic.  Ralf's ALLPROSE (demonstrated in his
experiments on cl-web a while back) makes much fuller use of this logic
and at this time constitutes the most advanced weave output yet
demonstrated for an Axiom pamphlet file.

Tim's new proposal, as I understand it (please correct me if I'm wrong)
is to use 

\begin{chunk}{chunkname}

\end{chunk}

or something close to that instead of noweb's syntax.  Then, instead of
using weave to translate the delimiters into LaTeX, he will provide in
a LaTeX sty file the necessary logic - I assume similar backend logic
to that triggered by the noweb auto-generated commands themselves?

This means that instead of going from
 "<<" -> *noweb autogenerated* -> *internal TeX logic*
the process is
 "\begin{chunk}{" -> *internal TeX logic*.

This would in fact fully support the weave functionality being used in
the Axiom Silver tree and other branches as it currently stands, unless
there are new features being used I am not aware of.

However, if we go straight from "\begin{chunk}{" -> *internal TeX
logic* there is no opportunity to operate on the chunk structure
outside of the TeX environment itself.  Currently, we are not doing
anything that couldn't be done by LaTeX/TeX itself, if I understand
TeX's abilities correctly.  The concern is, if we we eliminate the
possibility of doing something before reaching TeX, we constrain
ourselves for minimal benefit.

The syntax questions are actually minor - \begin{chunk}{ vs. << is just
a matter of preference for string identification, except that the
former makes the direct to TeX parsing process easier.  The major issue
is the consequences that follow from assuming no weave step.  A first
example would be the source code introspection demonstrated by Ralf's
demo with cl-web - I doubt that functionality can be produced
reasonably inside LaTeX and for that job even noweb's abilities fall
short of what would be required for a really proper job of
introspection - i.e. cooperation with the compiler itself.  It is not a
feature we currently use (nor, admittedly, is it one the lisp tools
support as yet) but certainly it looks to be a very useful feature we
would want to consider using and one that cannot be reasonably
duplicated inside LaTeX.  There are undoubtedly other scenarios we
haven't gotten to yet.

My preference would be to use the following convention, retaining the
weave step:

<<chunkname>>[options]=

@

options would not have to be present, but would be checked for.  I
think this syntax would give us full control as far as non-standard
tangle/weave behaviors are concerned - a chunk could be designated as
being lisp, boot, spad, api, or anything else we wanted it to be.  I
don't know about noweb, but inside Lisp awareness of these options
shouldn't be hard to achieve.  We could do things like extract all lisp
chunks from a pamphlet or build an api document from the api chunks.

>From my standpoint, the only processing logic we should put in LaTeX is
the logic that pertains to actually typesetting the document.  A weave
step, potentially, can do a lot more than just typesetting the
document.  Currently, only noweb's weave functionality practically
demonstrates this ability but that doesn't have to remain true
indefinitely.

In any case, what the tools are capable of is less critical to me than
agreement on a syntax we can use to create the pamphlets in the first
place.  Which tool to use can be specified with a configure flag at
build time, so long as all the tools know what it is they are supposed
to be processing.  If we incorporate Ralf's example of an advanced
weave process as the default, we can most likely spruce up the weave
output of pamphlets immediately.  (Assuming noweb's introspection
routines can understand SPAD...)  If someone wants to work just in
Lisp, they can specify the lisp web and live with the (currently) more
limited output.  Given a consistent syntax, that is a developer's
choice at compile time.

So let's put the tool discussion aside for the moment, and think JUST
syntax and weave step.

I think Steve is right, and we don't want to ditch the weave step. 
Earlier I thought this might be a good idea but upon reflection I agree
with him.  What I wasn't aware of before is that a weave step is
potentially more than just translation for typesetting.  And if we
don't abandon the weave step, the << >> syntax serves just as well.

Cheers,
CY


       
____________________________________________________________________________________
Got a little couch potato? 
Check out fun summer activities for kids.
http://search.yahoo.com/search?fr=oni_on_mail&p=summer+activities+for+kids&cs=bz