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

[Stephen Wilson]

Cliff,

In some ways the discussion has strayed from the original question "is
latex the best vehicle for describing pamphlets?".  Thanks OK though.


C Y <address@hidden> writes:
[...]
> > Look at the algebra, for example.  Look at the interrelationships.  Do
> > you want to write your algebra for Boolean in the _same_ pamphlet for
> > the rest of the system which depends on it?  Do ( untested :)
> > 
> >      cd ./src/algebra && cat *.pamphlet > algebra.pamphlet
> > 
> > I expect that is the situation we would have.
> 
> No.  What I would do is have Boolean defined where it logically makes sense,
> and then have Axiom itself determine inter-relatedness if I were interested
> in it.  I might also include a bibtex reference to the pamphlet containing
> Boolean if it were of immediate interest to the concept I happened to be
> working on at the time.  Chunk level references shouldn't be necessary.

OK.  The inter-file \chunk{foo} reference was a bad example of
something a weave tool could understand but latex could not, for most
practical purposes.  Im reaching for simple examples here.


[...]
> I would find either:
> 
>            <<add>>=
>                (defun add (x y) (+ x y))
>            @
> 
>            <<subtract>>=
>                (defun subtract (x y) (- x y))
>            @
> 
> or
> 
>            <<add and substract>>=
>                (defun add (x y) (+ x y))
>                (defun subtract (x y) (- x y))
>            @
> 
> preferable in such a case, personally - the legality of other options
> just invites code that is more difficult to parse.  Just MHO of course.
>  As the tool complexity required to handle the alternatives increases,
> and/or the speed of processing decreases.  Is it worth the extra complexity?

I dont think there is anything difficult or complex about it, this is
pretty simple syntax.

[...]
> You are proposing to include all forms of documentation associated with
> a particular "chunk" of code in a single pamphlet, and depending on the
> type of chunk do different processing steps to obtain different output
> documents.  This is a departure from the model I was using, which was
> one document for research paper, another for API only (no embedded code
> chunks, just a general reference to the research paper containing the code.)

I dont think anything I have been saying says "put all your
documentation here".  Im not really advocating any kind of structure
at all.  Im just looking at the problem space and seeing something
which is not LaTeX.

However, we need tools which would support your particular needs as an
author and programmer.

> Is there a particular reason why we can't simply do something like:
<snip>

Something along those lines is possible, absolutely.

[...]
> > No, you are not missing anything.  Hence the idea of a documentation
> > `chunk'.  You will want to specify the API somewhere.  It could appear
> > in a research paper as an appendix or nowhere at all.  The very fact
> > that it is an option suggests to me that LaTeX is not the proper
> > primitive to encapsulate all that data.
> 
> Assuming you want all information pertaining to a particular code chunk
> in the same pamphlet and in the same location.

I am not sure why it needs to be in the same pamphlet?

> > For example, assume we can assign a type to a chunk, as I mentioned
> > above.  Then if the chunk type is Spad, feed it to the parser and ask
> > not for the AST, but for a list of export/documentation pairs,
> > extracted from the traditional +++ notation used in spad.  The +++
> > construct can be viewed as a special case of a "documentation chunk".
> 
> An interesting possibility.  My only request in that respect would be to
> select and stick with a single consistent method for such documentation
> per-language.

Lets use +++ comments for spad, docstrings for lisp.  I am not aware
of a convention for boot, probably just preceding a function with --
comments would be enough for now. 



Take care,
Steve