axiom-developer
[Top][All Lists]

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

 From: Ralf Hemmecke Subject: Re: [Axiom-developer] Desired functionality from noweb Date: Fri, 04 May 2007 10:11:22 +0200 User-agent: Thunderbird 2.0.0.0 (X11/20070326)

Hi Cliff,

On 05/04/2007 02:48 AM, C Y wrote:
As I'm getting deeper into learning what noweb is capable of, I would
like to ask the list if anyone is familiar with the various options
noweb provides on the LaTeX side of the equation and how many of them
people like to use.

First, here look at
http://www.hemmecke.de/aldor/
or
http://www.hemmecke.de/aldor/allprose/
for some features I use in ALLPROSE.

At
http://www.hemmecke.de/aldor/allprose/myalpssu54.html#x104-12000028.1
you find that I my basic command is

noweave -n -index

-n      does not produce a latex wrapper (ALLPROSE provides a wrapper.)
-index  produces index information of identifiers

Although deprecated by Norman Ramsey, I use the

<<chunkname>>=
...
@ %def Identifier1 Identifier2 ...

a lot to get hyperlinks inside code chunks. (For .as files, this %def
information is autogenerated by ALLPROSE scripts.)

You also see

NOTANGLE, used in chunks 362, 363, 376, 435, 437, 468b, and 548.

I find this information sometimes quite useful to find out where some
identifiers are used. And look a bit closer at the last link (548).
NOTANGLE is defined in Makefile.nw. The link leads to a place that is in
test/Makefile.nw (see top of .html page).

My way to use noweave is:

1. concatenate all .nw files
2. run noweave -n -index on the concatenated file
3. split the output into .tex files corresponding to the
original .nw files
4. Use a wrapper (which looks approximately like)
\documentclass{article}
\usepackage{allprose}
\begin{document}
\inputAllTexFiles
\end{document}
5. latex/pdflatex/htlatex that wrapper.

You find the full story on the website
http://www.hemmecke.de/aldor/allprose/myalpssu62.html#noweb.NWGFlOZ-RntG3-1

Note that I don't think that everything should go into one big pamphlet file. I rather like to edit several files which finally produce ONE document. Using "inverse search" (http://en.wikipedia.org/wiki/Inverse_search), the file boundaries are pretty much blurred. I never type filenames for loading files. I simply click into the .dvi file.

Of course, I have added a number of TeX commands to make use of
identifiers defined via the %def syntax. They can be used via

\useterm{identifier}

inside ordinary non-chunk text and link to the defining code chunk.

I don't use the [[..]] syntax at all and would actually suggest not to
use it. [[...]] is no proper tagging, but rather like \verb.
Inside my text I rather use something like

\usemaketarget{...}
\definetexcommand
\usetexcommand
\defineterm
\useterm
...

http://www.hemmecke.de/aldor/allprose/myalpsse11.html

I think also the little arrows at the top of each code junk are nice, in
particular if a code junk continues at some other place. You then see a

+\equiv

at the top of the code junk and can click through the code chunks that belong together.

And if you look at the index you will find red and blue entries. I have
added a TeX command to modify the noweb.sty so that definitions are
shown in red in the index. (Style of course adjustable)

What I don't like at all with noweb is that one gets a \par after the
end of a code chunk if the @ is not followed by a space and %. In noweb
the Text can be continued immediately after the ending @\space, but for me that looks terrible. I want to see in the latex source were a code junk ends. A single @ doesn't catch the eye so quickly.

The noweb style file defines many elaborate output options, but coming
at it from a "need to generate LaTeX" standpoint I can't help wondering
if something a little less elaborate would meet our needs

Don't worry too much about the .sty file. If you generate LaTeX by a program, you can pretty much rewrite the text into simple TeX commands so that .sty file programming would be an easy task. I have chosen that option for \adname (http://www.hemmecke.de/aldor/allprose/myalpssu33.html#x78-8400025.2.8). It is translates into \adinternalusename (http://www.hemmecke.de/aldor/allprose/myalpssu35.html#x82-9200025.4) by the script tools/aldordoc2tex.pl.nw (http://www.hemmecke.de/aldor/allprose/myalpsse26.html). Otherwise I would have had hard times to deal with \catcode and such to allow % and friend to appear inside the argument of \adname. That command would be used as

and lead to different hyperlinks. And if such a function is also defined in another type than the current one, it is also possible to say

in order to specify exactly where the link should point to. (OK, but that is something not really connected to noweb.

dhmatrix
doesn't appear to use too many of the fancier noweb options and with
hyperlinking to link chunks together I'm not sure if some of the
features (e.g. the labels identifying page number and a,b,c etc.) add
enough to be worth supporting them.  Does anyone have any opinions

dhmatrix is a paper in traditional form. Nowadays, I would additionally like to see hyperlinks. Time is a precious thing so help the reader to quickly find the thing s/he is looking for. Going back and forth to the index manually (like in printed form) is old technology.

My thought at this time is with hyperref to link chunks to their
definitions (e.g. treat them like normal LaTeX hyperrefs) and perhaps
automatically generating index entries for chunks that should be enough
to cover what we would require.  (perhaps an automatically inserted
"used by" note would be handy to identify the higher level chunk into
which a sub-chunk is inserted.)

Eventually, (in particular for the Algebra) I would like to see links to where an identifier is exactly used. In order to generated the correct hyperlink, it would be necessary to actually compile the spad/aldor program so that it becomes clear what an identifier like "foo" actually means in a certain context. Note that I could locally have defined

macro foo(x, y) == a + b;

so "foo" should better point to the corresponding + in the source (or at least to its macro definition.

> I am not particularly concerned about
having the web routine try to deduce from the code in the chunk what
other chunks have code that uses the functionality defined there -
indeed with Lisp macros any such listing would almost have to be
incomplete if generated automatically.  In my opinion the surrounding
text should describe such relationships if they are non-obvious (e.g.
something a utility like xref couldn't deduce.)

As I said a big wish is semantic hyperlinks. (As I understood correctly, Tim already referred to that option when he said that in lisp all the information about symbols is available.)

My impulse is to see how much functionality can be achieved by
straightforward, standard LaTeX generation, but that may be a waste of
time if the features provided by noweb.sty are essential.

I don't think that anything from noweb.sty is essential. You simply have to put the logic into cl-web, then you don't need a style file at all.

Ralf