Re: [Axiom-developer] Pamphlet files and Axiom

[C Y]

--- Stephen Wilson <address@hidden> wrote:

> Hi Cliff,
> 
> I think you are making some very important points.

Thanks.  I'm trying my best to keep the "big picture" in mind here,
despite my burning desire to move on to things other than pamphlet
format ;-).

> 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 think an important question to ask here is which is more critical -
the delimiters standing out to the human eye or minimizing the
character sequences that need to be escaped?

My thought (and this is JUST my thought) is that most of the time spent
with pamphlets will be human beings editing them.  In that context, the
most important thing is for the human being to be able to easily read
and edit the pamphlet.  If we must escape the << sequence it is a pain,
but how often does << appear in Lisp or Spad code?  Or, put another
way, is the number of cases where << must be escaped sufficiently high
that the inconvenience of doing it offsets the reading advantage of the
<< >> form? 

I don't know how you're doing your code, but cl-web will pass by <<
except in two cases - one is where << is part of a << >>= structure and
the other is inside a chunk when it is part of a << >> structure.  I
actually didn't need to escape (even when cl-web was tangling and
weaving itself!) except for the case of defining the escape delimiters
for the listings package in code, and for that I cheated and used
(char-code) to specify what characters to put rather than including the
literal character.

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

Hmm.  I'll need to think about this, and more specifically what it
means to be "active".
 
> 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@>.

Oh, OK.  I've been using the chunk structures only for identifying the
chunks - for any kind of reference work I would have the weave step
generate a LaTeX label and reference that using normal procedures in
LaTeX.  How were you planning to use this feature?

> 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.
 
That will be very interesting to see!  I sidestepped the escape problem
the one time it came up, so it's not really a problem cl-web addresses
at all.  The idea was to use the rigid structure of the chunk
definition to make sure escape wouldn't be necessary.
 
> 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.

Again, the problem there is the visual difference between 

@address@hidden and @(chunkname@) 

is rather slight, as compared to

<<chunkname>>[lisp] and <<chunkname>>[spad]

To my eye at least the latter makes for much easier reading.  Whether
this is important enough to warrant consideration should probably be a
matter for discussion - in my opinion the readability of code intended
for humans to read and edit is very important.

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

Yes.  In the case of cl-web the hyperlinks are automatically generated
as part of the weave process itself - the code author should never need
to directly escape to LaTeX.
 
> 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.

Yes.  cl-web also makes use of the automatic substitution of the weave
step.  If I follow you, the point you are making is that the weave step
outside of LaTeX makes for much simpler creation hyperlinking within
the code chunks.  I whole-heartedly agree with that.  To be fair,
whether it is possible to do that with a LaTeX style file as well is
something I am not sure about.  I had assumed when Tim said he was
working on the LaTeX only solution he would include abilities such as
this in the style file.

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

Um.  Can you give an example of what you mean here?

Cheers,
CY


       
____________________________________________________________________________________
Choose the right car based on your needs.  Check out Yahoo! Autos new Car 
Finder tool.
http://autos.yahoo.com/carfinder/