axiom-developer
[Top][All Lists]

## Re: [Axiom-developer] Desired functionality from noweb

 From: Ralf Hemmecke Subject: Re: [Axiom-developer] Desired functionality from noweb Date: Tue, 08 May 2007 15:51:31 +0200 User-agent: Thunderbird 2.0.0.0 (X11/20070326)

I still think the most promising direction for the "read the source
code and find definitions and where they are used" is to use the
compiler to find that information - anything else just seems too
fragile.



Of course. But starting the compiler to get hyperlinks in the documentation should be optional, because it would basically mean to compile the code and add the symbol information to the documentation to get nice hyperlinks. The bad thing is if you want to document what you currently have, but the code does not yet compile.


OK. But there are also ways to link different .dvi and .pdf files together. (That was shown by Tim.) That still means one can keep the projects/libraries/concepts separate documents and still interlink.

Yes.  I guess my next question is do you want to be able to have the
def feature work across multiple files?



Hmm, in ALLPROSE a file is not the same as a "concept". But this %def stuff works across file bounderies. The trick is that noweave basically sees only one file. I split noweave's output later into separate files again. That is easy, because each file begins with something like

\nwfilename{Makefile.nw}\nwbegindocs{0}


The only problem is that with %def one can only do identifiers, but not semantic links. So I restrict that %def thing to type names. They are more or less unique in a project.


Try
%---BEGIN aaa.pamphlet
<<*>>=
<<X>>
A
@
<<X>>=
EFG
@
<<*>>=
B
@
<<C>>=
UVW
@
%---END aaa.pamphlet

notangle aaa.pamphlet
EFG
A
UVW
B


Ugh.  I don't think this is a style of LP we should use.



Why not? Well, it was just an example, but I don't think that a continued code junk is a terribly bad idea. I would only require that braces are paired within each chunk.


You don't need to use this option of noweb. And again. I have not enough experience that I could already suggest a good LP style.

> My preference

in the above situation would be to throw an error that chunk "X" is


What? There is only one definition of X.


For multiple "root" nodes in a file tangle the
requested node but print a note that chunks "foo" and "bar" in this
file are also root nodes.



There is always only one "root" node. And that is started by the first <<*>>= in a file.


I suppose a tangle with no specified root
node could untangle all root nodes but I don't really regard that as a
good way to work - at least the way I write if a chunk isn't inside a
root node it's a mistake and what I want is a message warning me, not
an unwanted file (or sometimes several of them) dumped into the source

dire


Hmm, seems that you confuse the way noweb (the program) treats a file with the way notangle/noweave treats the same file when giving no additional command line switches.


Probably.  I personally prefer not to have "hidden" root nodes in files
that the pamphlet name doesn't suggest,


I don't understand, what i "hidden root node" is.

Personally I sometimes use

<<OLD: foo>>=
some code
@

<<foo>>=
same code with a little modification
@


I particularly find that useful to test some slight variations of the code I have without the need to remove the old code. Maybe that I will finally remove <<OLD: foo>>, since it is never used, but think about

<<ALTERNATIVE: foo>>=
...
@


and a corresponding description when that should be used or what idea behind that alternative is.


That line numbering in the .tex is *identical* to the .pamphlet file
is needed for the inverse search feature.



LaTeX (or better srcltx.sty) only sees the .tex file. So it can only write line numbers of the .tex file as \special into the .dvi file. If the line numbers differ from the .pamplet source, inverse search would jump to the wrong place.


What is the disadvantage of \begin{docchunk} ... \end{docchunk}? You
can define it as

\newenvironment{docchunk}{}{}

but without any need to re-weave, you could also compile against
another style file which has

\usepackage{verbatim}
\newenvironment{docchunk}{\comment}{\endcomment}

and you would only see code in the .dvi file. (It's just an example.)


I guess my instinct was to add only what was absolutely necessary to
the TeX file for simplicity, but I guess I have to admit it wouldn't
make too much difference.  I didn't want to require any style files not
already in teTeX but I guess that's unrealistic.



So you don't want to require something like axiom.sty? But then you put all the style information into your weave program. That doesn't sound like the right way to do.

Ralf