Re: [Axiom-developer] Re: literate programming pamphlet files for MathAction

[Ralf HEMMECKE]

Dear Martin,

>  > Personally, I would very much like to get the functionality of JavaDoc, but
>  > unfortunately ++ comments might become unreadable in the .pamphlet file
>  > (which is undesirable).
>
> why do you think that they might become unreadable?

In ++ comments one might wish to include some mathematical formulae. 
Writing them in MathML makes the ++ comments unreadable. Many 
mathematicians can read LaTeX these days, so I would prefer LaTeX here.
However, even the LaTeX style will not be there forever.

I would agree on some XML like style, but this should come with an 
editor that hides the tags and presents the things inside nicely. (I 
know it is not well thought of.)

Personally, I became familiar with noweb only recently, and it works 
great. The \usepackage{srcltx} facility together with some newer dvi 
viewers like kdvi or xdvi, let you 'inverse search' in the dvi file. 
When you click at some place in the .dvi file, your editor opens and 
points directly to the place in the .tex file. I have a modified version 
of srcltx that jumps to the place in the corresponding .nw file instead 
of the generated .tex file. I have simply replaced

\def\src@@include#1#2{%
    address@hidden@address@hidden
    address@hidden
    address@hidden@address@hidden
}

in srcltx 2004/05/15 v1.4

by

\def\src@@include#1#2{%
    address@hidden@address@hidden: removed '.tex' extension
    address@hidden
    address@hidden@address@hidden
}

In connection to the extension rule of just adding .tex to the noweb file

   noweave FILE.nw > FILE.nw.tex

this works quite nicely for me.

But maybe this inverse-search facility is not necessary if pamphlet 
files are edited via MathAction or LaTeXWiki. (Unfortunately, I have no 
experiences with the latter.)

But still, the ++ code would remain untouched (and unformated) even in 
the .dvi file (and thus maybe unreadable). So I have not quite made up 
my mind of how to document in a structured way by using the ++ comments.

Ralf