Re: [Axiom-developer] Pamphlet files and Axiom

[C Y]

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

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

But do the sequences << followed by >> occur on the same line in source
code often?  That is the only possibility that would require an escape.

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

Possibly.  Has Norman Ramsey documented the reason for that particular
choice anywhere?

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

Hmm.  Matters of personal preference are where this gets tricky, as I
have the opposite reaction to that syntax :-/.  I don't suppose there
is research anywhere on readability of different syntax constructs to
the human eye?

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

Out of curosity, can you think of an example use of << in Spad or Aldor
that would cause cl-web in its current form to make a mistake? 

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

OK.

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

Does this mean the document must begin with an @ symbol?

>    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 `@@<'.

OK.  Does this mean you are working only off of these rules and not
altering your parsing rules inside a chunk body?

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

OK.  I think I understand what you are doing.  You are deliberately
making chunk references the same in both document and code, and only
treating them differently based on environment in the tangle step?

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

OK.  My design approach would have been to keep references in
documentation chunks in LaTeX and source code, but I'll wait and see
what your approach is.

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

Again out of curiosity, can you propose a scenario in the cl-web
context that would require any character escaping?
 
> I personally dont find them too hard to distinguish, but I would like
> a good pamphlet.el mode to highlight them differently. 

Can we get some more opinions on this point?
 
> 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.

Oh, I understand the idea.  It's not a bad one, it's just rather
different from how I had envisioned working.  What is a use case where
you would want to escape into raw LaTeX inside a code chunk?  (As
opposed to the weave step doing it to create references?)

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

Ah, but the idea in that case would be that the source code and latex
were different sides of the "chunkname" crystal.  In other words, the
intent is that the latex and the lisp code in those cases both be
associated with the chunk chunkname.  Or, put another way, a query for
latex associated with the lisp code in chunkname should lead directly
and inevitably to the latex associated with chunkname.

Also, in those cases the syntax itself conveys in english what type of
content is supposed to be in these chunks.  I find that to be an
advantage, particularly in the case where an occasional Axiom author
who is primarily a mathematician is looking to edit a pamphlet file. 
@( and @{ convey no inherent information about what they define, but
<<chunkname>>[lisp] does.

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

Oh, got it.  Not verbatim environments so much, but different options
for src environments.  My approach to the escape issue was to just pick
a longer sequence of characters that was so astronomically unlikely to
appear anywhere that collisions with source code weren't a factor. 
Since the weave step generates them anyway, it doesn't really make too
much difference.  Does fancyvrb insisted on the same three escape
characters and/or only let you use three?
 
> 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).

I never considered wanting to let different LaTeX environments act as
the "container" for the source code, although I guess that's possible. 
 I guess I always thought it would just make more sense to identify the
best features in the various options and incorporate them into a
unified environment, rather than complicate the tools.  The
proliferation of multiple incompatible LaTeX packages for the same jobs
has been somewhat unfortunate - I keep hoping there will be a trend
towards consolidation at some stage.

Cheers,
CY


      
____________________________________________________________________________________
Park yourself in front of a world of choices in alternative vehicles. Visit the 
Yahoo! Auto Green Center.
http://autos.yahoo.com/green_center/