Re: [Axiom-developer] Pamphlet files and Axiom

[Stephen Wilson]

C Y <address@hidden> writes:

> --- Stephen Wilson <address@hidden> wrote:
> > > 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.
> 
> And you think such events would be sufficiently common to merit going
> away from them as tags for references?

Absolutely.  If I design a piece of software I consider its
`philosophy', the why of its approach to the problem.

I want a tool which can be tailored to axioms needs.  But at the same
time, I do not want to say that you can only write spad, boot, and
lisp code with this tool.

C and C++ are sufficiently popular for them to be considered when
writing a program which manipulates source code.

[...]
> > I havent tried to break cl-web in this case.  If you want me to I can
> > give it a go :)
> 
> Don't worry about it if it would distract you from your tool.  I just
> want us to decide on how to write pamphlets so we can start writing
> said pamphlets.

Me too. Absolutely.

[...]
> > > 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?
> 
> In cl-web, the only time the << >> combination has significance to the
> scanner is inside a code chunk.  In documentation, it has no unusual
> significant at all.

OK.  My tool gives significance to @< currently in documentation,
which introduces a chunk reference.


> > > 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.
> 
> I'm curious when you plan to refer to code chunks in documentation. 
> Thus far most of the references I've made are from chunk to chunk. 

Really?  I always cite other code when describing a function which
supports or uses it.

[...]
> > 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@>= ....
> 
> Erm.  That didn't occur to me.  I always viewed simple non-LaTeX chunk
> names as sufficient.

For me it is not sufficient.


> > > 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.
> 
> In cl-web, they both come out literally as they went in.  Isn't that
> desired behavior?

latex the file and look at the dvi.

[...]
> > 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.
> 
> So you want LaTeX typset comments inside the source code chunks? 

Sure, why not?  Sometimes the explanation of an algorithm falls
naturally in that context.  We could number each line in a source code
context automatically, but I dont like that approach exclusively.  Its
a pain to always say "at line 34 we ....".  Its also a drag to have to
ensure that line 34 isnt typeset as line 33 or somesuch.  Little
creeping errors like that bug me, and I can avoid them completely by
placing simple explanations in comments (and I would like to have
TeXs math available to make the comments even more concise).

[...]
> I may be missing something.  From my standpoint, the user will never
> expect to have anything inside a source chunk typeset except what the
> weave command itself automatically generates by redoing weave
> references.  The author escaping to LaTeX themselves is a non-issue -
> it would never be done.

I will do it.  Just because you wont doesnt mean its not possible or
desirable.  We need tools which are accommodating to needs different
to our own.


Take care,
Steve