RE: [Axiom-developer] Re: literate programming pamphlet filesforMathAction

[Bill Page]

On Friday, October 01, 2004 9:31 AM Martin Rubey
address@hidden wrote:
> ... 
> I think that both ++ and -- *could* serve one purpose as
> follows: as a said before, -- comments often contain old
> code. I think it is not wise to ban this code into the
> archives too early, since it often explains why the new
> code looks as it looks like. Clearly, such -- comments need 
> to be rendered just as the rest of the code, it might be
> nice if they were a little "lighter".

I am not sure what you mean by "ban this code into the
archives". If one is working in a system like Zope that
retains a history, then nothing is banned. All you need
to do is take a look at the "diffs". For example look at

  http://page.axiom-developer.org/zope/mathaction/dhmatrix

Then click on 'diff' on the top right-hand side of the
page. You can click on 'previous edit' to see the entire
history of the contents of this page.

That said, you are right that some code highlight might
(if artfully done) might make Axiom code a little easier
to read. Shading in-line comments is one such simple thing.
Other examples are variable names in bold and/or maybe
different color depending on type etc. It is possible but
would require more syntax analysis - probably almost as
much work as the compilation itself. It is technically
possible but probably not really worth the effort.

But I think you are missing the point of Tim Daly's remarks.
Really, what is desired is that Axiom developers (and Knuth
and the 'literate programming movement' would claim that
programmers in general should do this) consider that what
they should be doing is creating a document, like writing a
scientific paper - one that is first of all intended to be
read and understood by other people (or oneself many years
later). The content of this document will also include
programming code, or in Axiom's case Axiom commands, which
is intended to be processed by the system in order to provide
proofs and/or demonstrations of mathematical concepts or to
extend the system in some way (e.g. define new categories
and domains).

>From this point of view, 'commented out' old programming
code is no different than other text in the document. The
point of that text would be to describe the development
of the content of document itself, for example like a diary
or 'blog'. But usually it is better to let the system track
this instead of letting it 'clutter up' the document itself. 

> 
> ++ comments currently contain a *short* explanation of what 
> the function does. Appendix E of Jenks Sutor (which is missing
> from the electronic version) seems to be a compilation of this. 
> 
> I am absolutely certain that this kind of documentation will 
> be necessary in future to. )show Integer does not suffice,
> since it contains only the modelines. For example:
> 
> prefixRagits :
>    [1] RadixExpansion D2 -> List Integer from RadixExpansion 
> D2 if D2: 
>             INT
> 
>       ++ prefixRagits(rx) returns the non-cyclic part of the ragits
>       ++ of the fractional part of a radix expansion.
>       ++ For example, if \spad{x = 3/28 = 0.10 714285 714285 ...},
>       ++ then \spad{prefixRagits(x)=[1,0]}.
> 
> In some way or the other, we will need such short "abstracts"
> of each function. Many of them are present currently, their style
> is very close to StructuredText, so I'd suggest to use them!

Yes, of course. They become part of the literate document that
we are creating. Part of that document can be extracted and
organized automatically as needed.

> And yes, even to compile them in. It will be a lot easier to
> extract them from a database then to extract them from the
> pamphlet files.

No. This does not make sense. What you call 'pamphlet files'
are in fact already stored in a database - the Zope database.
That is what allows them to be manipulated in more complex
ways than just plain text files.

> 
> If you propose to have some other command in the pamphlet 
> file that creates such a database, be it.

No, it becomes part of the function of the online system
like on MathAction.

> ...
>  [Bill Page wrote:] 
> > At this time I am still uncertain as to whether to include
> > the nontangle+Axiom output in the same page as the
> > documentation, as shown on the current dhmatrix page
> > above, or whether to present this in a separate page.
> 
> I vote for a separate page.

Ok. Yes, the more I think about this, I agree. It should be
a separate but hyperlinked page.

> However, there seems to be quite a bit missing from the
> pamphlet file. I copy it here so you can verify. (note: 
> directly copied from the dvi file, so some characters are
> wrong.)

I don't understand from what you include below what you
think is "missing". You said: "missing from the pamphlet
file" but everything is generated from the file. Can you
give me an explicit example of something?

> The dvi output ends with:
> 
> 
> Denavit-Hartenberg Matrices 
> hdomain DHMATRIX DenavitHartenbergMatrixi 
> ? 
> --Copyright The Numerical Algorithms Group Limited 1991. 
> ++ 4x4 Matrices for coordinate transformations 
> ++ Author: Timothy Daly 
> ++ Date Created: June 26, 1991 
> ++ Date Last Updated: 26 June 1991 
> ++ Description: 
> ++ This package contains functions to create 4x4 matrices 
> ++ useful for rotating and transforming coordinate systems. 
> ++ These matrices are useful for graphics and robotics. 
> ++ (Reference: Robot Manipulators Richard Paul MIT Press 1981) 
> )abbrev domain DHMATRIX DenavitHartenbergMatrix 
> --% DHMatrix 
> DenavitHartenbergMatrix(R): Exports == Implementation where 
> ...