Re: [Axiom-developer] Desired functionality from noweb

[Ralf Hemmecke]

> 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
> already defined.

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