Re: [Axiom-developer] Re: Pamphlets and LaTex

[Stephen Wilson]

C Y <address@hidden> writes:

> I'll confess I'm a bit confused, but that may be my fault.  Questions:
> 
> 1)  How does going from noweb to LaTeX syntax change anything, besides
> what needs to be typed to ID a chunk? 

The critical and (as I am now seeing) subtle point is that latex only
sees the markup as a typesetting construct, where in fact the
construct means a completely different thing to the absolutely
necessary tools like weave and tangle.

So when you write \chunk{foo}, you dont mean "LaTeX, please typeset
this reference to foo".  You mean "Pamphlet, this is a chunk named
foo, as you can see by the executable code to which it points, it
connects with the domain Foo, please update the runtime representation
of the domain Foo with a link to the surrounding context. Please
inform hyperdoc of the connection. Please ...".

And since LaTeX is a language designed with the express purpose of
writing documents, not pamphlets, it does not mesh well with our
needs.

What if \chunk{foo} resulted in referencing the Foo domain defined in
another file?  For a competent weave tool which understands the
problem domain, this is not an issue, it can look up the reference.
Now what does latex think about this \chunk{foo} construct?  Will it
typeset "cannot find chunk foo", will it bail out in error?  The
answer is that there is no sensible solution, but to do what the
construct is asking, and weave it properly and into a form which LaTeX
can digest.


> I don't know about noweb, but the whole point of wrapping the cl-web
> state machine in macros was to be able to handle arbitrary
> delimiters.  If everything works as expected, the options should be:

Right.  But you dont need a state machine to do that. You just need a
variable holding a string, cl:string=, and cl:subsequence. 

Its much harder to transform that state machine into one which can
deal with the reorganization of chunk structure.  For example, noweb
markup like:

    @
      Introduction.
    <<chunk1>>=
        (code here)
    <<chunk2>>=
        (more code)
    @
       Some documentation
    <<chunk3>>=
         (etc...)
     EOF

The state machine hard wires code blocks:

      <<chunk>>=
          (code)
      @

State machines are fine if your modeling transistor networks.  Not
when parsing dirt simple noweb-like markup, IMHO.

[...]
> 2.  Y'all ARE aware that cl-web already has a very basic weave
> functionality, correct?  The cl-web pdf file was built from a TeX file
> generated by cl-web itself, without noweb.  It's nothing spectacular
> but I am using it to work on asdf-literate.  Extending it shouldn't be
> too difficult, except for the whole source-code-reference bit (which to
> do correctly will require cooperation from the Lisp compiler.)

Yes.  I am aware for that.  Note that you need cooperation from the
Lisp compiler.  Again, another non-latex component to the process.
Another reason not to have pamphlet markup masquerade as latex.

> 3.  Is the intent still to move to the cl-web code once we get to ANSI,
> or is gclweb the direction of the future?  If the latter I need to take
> a closer look at that codebase.

I have some issues with the code in cl-web, as noted above,
unfortunately. (again, please dont take this personally!  These are
just dry technical observations!)

> 4.  Do I understand correctly that a design goal here is to add
> commands to the pamphlet files that will not be tangled but instead
> executed in an Axiom environment?  There are two ways to interpret
> that:
> 
>    a.  Provide a special LaTeX style that is aware of SPAD/interpreter
> language syntax and typesets, but don't execute the code unless the
> file is specifically processed with that intent (tangle, weave, and
> run-spad?)

The correct solution is to have a pamphlet command which can either:
   - executes the code and generates the appropriate latex as output
   - or replace the command with a simple latex expression without
     doing any on-the fly evaluation.

Either behavior, and perhaps others, can be specified to weave the
document.

>    b.  Process the commands during the LaTeX process and incorporate
> the results of Axiom's evaluation automatically into the document. 
> This is a bit more like the EMaxima functionality.  This is useful in
> some situations but I am not sure we need to be worrying about it at
> this stage.

This is not enough.  Axiom should be able to read pamphlets, and have
them exist as live objects in the system.  Should we actually require
that axiom write a file and call LaTeX to call itself in order to
weave a document?

LaTeX processes latex files, not pamphlets.

> Can someone provide me with some usage scenarios here?  What are the
> goals?

The Crystal, where we can view an object through a multitude of
facets.  We can see the API, the theorems and proofs, the category
hierarchy, the dependents and dependees, etc, etc...  All these things
have been discussed before, there are many other options.  I mention
these in particular because they are all candidates for generating
LaTeX output, but would ultimately be inferred from a set of
pamphlets.  You cant just run LaTeX on a pamphlet and obtain that
result, because pamphlets are not LaTeX.

> 5.  I'm a bit dubious about the possibility of treating documentation
> as chunks - I tend to view documentation of .spad.pamphlet files as
> indivisible conceptually (not just technically.)  To me the best bet is
> to go with what is already done in the academic world - combine papers
> into volumes in the "conference proceeding" fashion.  There will be
> many different writing styles at work in the Axiom system, and it's
> almost certain they won't "flow" in such a fashion as to lend
> themselves to having pieces mixed and matched.

Whats wrong with associating a documentation chunk as the formal proof
of a particular code chunks correctness?  Or as the API doc which gets
displayed when you pass the wrong type to factorGroebnerBasis?

> Am I missing something here?  Help!

I hope that helps clarify my position a bit.  Lets keep discussing
this as I think it is of hugely important for Axiom!



Thanks,
Steve