Re: [Axiom-developer] Pamphlet files and Axiom

[Stephen Wilson]

C Y <address@hidden> writes:
> 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? 

It appears quite often in Aldor, where it is an operator.  There is no
reason to expect that it will not become one in Spad too.  It is also
very common in C and C++, for example, among other languages.  I like
nowebs `language neutral' approach, but I think `<<' was a mistake for
such a general purpose tool.

> 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 find, personally, @<chunk@> fairly pleasent.  Emacs can be taught to
highlight such sequences, giving them a more pronounced, or a softer
appearance, according to ones taste.

I think that the rarity of collision using the `@' based form as
opposed to `<<' is quite an important property.

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

In my version, the detailed (preliminary) rules are:
   
   1) An at sign in the first column is `active'.  This is to allow for
      future extensions.  If the resulting line does not parse
      according to the following rules, it is an error.

   2) An at sign in the first column followed by a space, newline, or
      EOF, introduce a document chunk.

   3) An `@<' sequence anywhere introduces either a code chunk
      definition or a code chunk reference.  A chunk definition starts
      on the first coloumn and has the full form @<chunkname@>=, a
      chunk reference is just @<chunkname@>.

So, if you need an at sign in the first column position, type `@@', if
you need the sequence `@<', type `@@<'.

I am also considering reserving at-sign/delimiter sequences in general
for future use by the tool, in the same spirit as rule 1.

[...]
> 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 just expand chunk references into an appropriate hyperlink using the
hyperref package.  You have clickable links in both code and
documentation chunks.

Currently, they expand into the chunk name in both text and code as
"<chunkname>", but it would be nice in the doc chunks to specify some
arbitrary latex string into which they expand serving as the clickable
region.  I might experiment with @<chunkname@>[lable=\someTeX{}] or
somesuch.

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

The code I am working on fully supports the ability to have active
escape characters in the latex environment which is used to typeset
your code, without one needing to even think about it.

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

I personally dont find them too hard to distinguish, but I would like
a good pamphlet.el mode to highlight them differently. 

The idea is to allow different concepts to be associated with the
sequences.  For example, @[some address@hidden when appearing in a code chunk
could escape into raw LaTeX.

We could overload a single escape sequence to accomplish that, but
then readability I think is hindered more.  For example

    <<chunkname>>[lang=lisp]   vs  <<chunkname>>[latex=true]

Where the interpretation of "chunkname" is different in the two
contexts.

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


Sure.  Take the listings package vs. fancyvrb.  They have different
policies about how to escape into raw latex.  In the listings package
an active character is used to delimit the expression you want LaTeX
to see. So you can say the `!' character escapes, and write
`!\LaTeX\!'.  Compare to the three characters needed with fancyvrb.

This means that only one character needs to be expanded specially --
all `!' characters when they appear in code chunks.

I experimented with both packages while writing the code, and I could
tell the tool how to transform the running text as appropriate by
changing a few definitions here and there.  It is quite possible to
design a general mechanism which would allow the user to configure the
system concisely to use various environments and escape policies (this
would go under the section titled `Advanced Usage' in the pamphlet).


Steve