Re: [Axiom-developer] Desired functionality from noweb

[Ralf Hemmecke]

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

See also
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

  \adname{-: % -> %}
  \adname{-: (%, %) -> %}

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

  \adname[AdditiveGroup]{-: (%, %) -> %}

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
> about this?

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