Re: [Axiom-developer] Pamphlet files and Axiom

[Stephen Wilson]

Hi Cliff,

I think you are making some very important points.

C Y <address@hidden> writes:
[...]
> My preference would be to use the following convention, retaining the
> weave step:
> 
> <<chunkname>>[options]=
> 
> @

I myself think that noweb made a mistake in choosing the <<chunkname>>
syntax.  It stands out well but it introduces another character
sequence `<<' which needs to be escaped.  I really prefer the syntax
used in CWEB, so we could write:

    @<chunkname@>[options]=

Or some such.  @ signs are a very rare candidate for collision in both
written text and program code.  Plus, we can boil down the rules for
when such characters are `active'.  For example, the rules could be:

     - @< is active everywhere, in code and text.

     - A single @ is active when it appears in the first column
       position.

The reason `@<' is active everywhere is that you can reference a code
chunk in program code and text in a uniform way, by simply typing
@<chunkname@>.

I have been using these rules with very good success in the initial
pamphletization of my noweb-like tool.  Considering the code and
documentation is full of @ signs, its is only in a handfull of cases I
have need to escape.


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

Absolutely.  We could also reserve one or two more `magic' sequences,
like @[, and @(.  In fact, the occurence of such `at sign + delimiter
collision' is so rare that we might even be able to reserve a full set
of escapes based on the common opening delimiters without it impacting
on the user, thus allowing a fairly rich name space with which to work.

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

Practically speaking, the weave step can also help immensely when
typesetting the document too.

For example, I am using the `fancyvrb' package as the verbatim
environment in which code chunks are output.  That package allows you
to escape to latex from within the environment.  I use that to embed
hyperlinks to code chunk references (cl-web does this too, I think,
but uses the listings package, right?).

In this environment, to escape to latex, one needs to define three
character escapes.  For example, you could use !, [, and ].  Which
means that the latex command \texttt{foo} could be embedded directly
into your verbatim environment by writing !texttt[foo].  

You know this, I am sure, but I do have a point, and here it is :)

I am using the standard three characters \, {, and } currently as
escapes, which means that anywhere these characters occur in your
program weave needs to replace them with something else.  I do this my
simply defining a few macros which expand into the respective
charcodes.

Thus, the Lisp string:
   "\\usepackage{fancyvrb}"

gets translated into the latex

   "\axBS{}\axBS{}usepackage\axLB{}fancyvrb\axRB{}"

Which I am very happy I did not need to type directly.

A weave tool can also support several kinds of verbatim environments,
without the author of a pamphlet worrying that there programs might
contain active characters which will collide.



Take care,
Steve