axiom-developer
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Axiom-developer] Pamphlet files and Axiom


From: Stephen Wilson
Subject: Re: [Axiom-developer] Pamphlet files and Axiom
Date: 21 Jul 2007 13:57:03 -0400
User-agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.4

C Y <address@hidden> writes:

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

Yes.  Particularly in C and C++ where these sequences are used for
logical shifts.

I considered the `full form' parsing rule, requiring that both paired
delimiters are required to activate the sequence.  But I rejected it
because it was not very consistent.  I prefer simple rules which would
treat both this line containing the << and >> pair as being active,
as opposed to this line with just one <<.

Its easier the type without needing to think about what is active and
what is not.

[...]
> > 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 havent tried to break cl-web in this case.  If you want me to I can
give it a go :)

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

No.  In my code the `mode' is a documentation chunk at the start.
However, if you do not start your document with an @ sign, then the
first chunk is interpreted as a prelude, which is to contain latex
commands to appear before \begin{document} is (automatically)
inserted.

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

Im not sure I understand your question.  Could you elaborate?

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

Correct.


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

I considered that but the weave stage generates the label references
automatically for you, so unless you have a sixth sense about such
things, you cannot predict what the tag might be.

Note that one of the main reasons of automatically defining the labels
is to enable chunk names to contain LaTeX, which cannot be used as the
label used to target the hyperlinks.   I like being able to say:

   @<The \texttt{WEAVE} command@>= ....

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

Sure, give the following code a try:

  <<chunk>>=
    (defun hello-world () (format t "Hello World!")
  @

You wont get the `!' typeset, as its active.  Try replacing the string
with "!\LaTeX!" and see what happens.

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

Hey, you already have that feature in cl-web :)

Seriously though, I would use the feature to typeset comments without
needing to teach the tool what characters introduce comments and have
it do the escape to latex for me.


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

I dont follow.  I meant that <<chunkname>>[latex=true] would be an
escape to latex.  Note the ambiguity.  I used the string "chunkname"
to indicate that in the two contexts it has a different
interpretation, not quite what you would expect.

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

Well, I have played with @( to be an mechanism to escape into lisp.
So if I write:

             "@((format t "HI!~%")@) 

Then when tangle or weave is called, and the form exists in a chunk
they process, the programs will print "HI!".

But thats just a fun thing.  It would take a lot of thought as to how
one can make it useful (but there are certainly a lot of
possibilities there).


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

Im not sure.  I know you can pick any three characters, but I have not
read about an option to define an outfix style delimitation.

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

I always prefer `sensible defaults' with the power to override,
customize, and extend.  If the tool does not allow me to do that (like
noweb), I tend to seek out better ones or write them myself.


Cheers,
Steve





reply via email to

[Prev in Thread] Current Thread [Next in Thread]