noindex(1) [debian man page]
NOWEB(1) General Commands Manual NOWEB(1) NAME
noindex - build external index for noweb document SYNOPSIS
noindex basename[.tex] DESCRIPTION
noindex looks through LaTeX .aux files for identifiers that should go in a noweb external index. It sorts all identifiers and writes the results on basename.nwi. NOWEB INDEXING STRATEGIES
A noweb program consists of one or more files. In the simple case, these files are run through noweave together, to produce a single LaTeX file. noweave -index suffices to produce an index and cross-referencing information; neither nodefs nor noindex is required. When a noweb program consists of several source files, it is often better to run each source file through noweave to produce its own LaTeX file, then use noindex to produce an external index. This technique has several advantages: The line numbers in the LaTeX files correspond to the line numbers in the source files, so it is easier to diagnose LaTeX errors. The LaTeX includeonly feature can be used, making it possible to format parts of large programs while retaining complete cross-ref- erence information. When used with make(1), the technique avoids running noweave over source files that have not changed. Using the external index places fewer demands on LaTeX's memory, making it read its .aux files much more quickly. The disadvantages are that nodefs and noindex are needed for full cross-referencing and a properly sorted index. EXAMPLE
This example assumes a noweb program of three source files: a.nw , b.nw , and c.nw. The file doc.tex is assumed to contain LaTeX boiler- plate, including the commands oweboptions{externalindex} include{a} include{b} include{c} The first sequence of steps is to create a file listing all the identifiers defined anywhere in a, b, or c. nodefs a.nw > a.defs nodefs b.nw > b.defs nodefs c.nw > c.defs sort -u a.defs b.defs c.defs | cpif all.defs Using sort -u and cpif(1) avoids changing all.defs unless the set of identifiers changes. This technique, used in a Makefile, avoids unnecessary rebuilding. The next series of steps is to create LaTeX files with full cross-reference information for all identifiers. noweave -n -indexfrom all.defs a.nw > a.tex noweave -n -indexfrom all.defs b.nw > b.tex noweave -n -indexfrom all.defs c.nw > c.tex The final steps run LaTeX once to create .aux files, then noindex to create the index, then LaTeX again to format the complete document. latex doc noindex doc latex doc In a Makefile, noindex can be run before every invocation of LaTeX. BUGS
noindex is distributed in awk and Icon versions. The awk version is slow and does a poorer job sorting. There is no comparable machinery to make it possible to use multiple files with the HTML back end. SEE ALSO
noweave(1), nodefs(1), cpif(1) VERSION
This man page is from noweb version 2.11b. AUTHOR
Norman Ramsey, Harvard University. Internet address nr@eecs.harvard.edu. Noweb home page at http://www.eecs.harvard.edu/~nr/noweb. local 3/28/2001 NOWEB(1)
Check Out this Related Man Page
pretzel-it(1) General Commands Manual pretzel-it(1) NAME
pretzel-it - use Pretzel to build a prettyprinter SYNOPSIS
pretzel-it [-iqvdnh] language ppname DESCRIPTION
Pretzel-it is a shell script that uses pretzel(1) to build a simple prettyprinter executable. It minimizes building a Pretzel prettyprinter to just one shell command. See pretzel(1) for a general overview and a description of the input files. You have to provide the same two input files to pretzel-it as to pretzel. These two files are called the formatted token file (suffix .ft) and the formatted grammar file (suffix .fg). Both files need to have the same prefix language. From this input, pretzel-it generates an executable prettyprinter called ppname. Example Say, you have written two files foo.ft and foo.fg that contain the prettyprinting information for your favourite programming language foo. To get an executable prettyprinter foopp for it, simply type: pretzel-it foo foopp OPTIONS
Pretzel-it has the following options: -i Don't remove intermediate products of pretzeling. -q Run quietly. -v Verbose mode, print shell commands before invoking (for debugging). -d Turn prettyprinter debugging features on by default; also produce a detailed diagnosis file (suffix .output) that contains a detailed analysis of the grammar and possible problems with it (to ease debugging the prettyprinting grammar). -h Print full usage message. -n Noweb mode. See section Interfacing with noweb(1) below. THE GENERATED PRETTYPRINTER
The generated executable will be a program that reads source code from the standard input and will write prettyprinted code to the standard output. The prettyprinted code can be typeset using latex together with the pretzel-latex document style. Example Say, you have built foopp already and have a scrap of source code in a file bar.foo. Type foopp <bar.foo >bar.tex and the prettyprinter will prettyprint the code and write LaTeX code to bar.tex. To use this code in your documents, simple include the pretzel-latex document style and include the file inside the new ppcode LaTeX environment. Here's a minimal LaTeX file to look at the pret- typrinted code: documenstyle[pretzel-latex]{article} egin{document} egin{ppcode} input{foo.tex} end{ppcode} end{document} INTERFACING WITH NOWEB
Using the -n option will produce a prettyprinting filter ppname compatible to Norman Ramsey's noweb(1) literate programming system. The filter can be inserted into the noweb pipeline using noweave's -filter option. For example, you can build a noweb prettyprinting filter for Pascal by issuing pretzel-it -n pascal prettypascal inside the languages/pascal directory, you'll get a prettyprinting filter prettypascal . This filter then can be used within noweave(1) by saying: noweave -filter prettypascal foo.nw > foo.tex This will prettyprint all code chunks using the Pascal prettyprinter. You will need to include the pretzel-noweb.sty LaTeX document style after including the noweb.sty ( see nowebstyle(1) ) to get the output typeset correctly by LaTeX. You can get debugging output from the prettyprinting filter by setting the environment variable PRETZEL_NOWEB_DEBUG to a non-null value, e.g. in the bash(1) shell by saying: export PRETZEL_NOWEB_DEBUG=on Debug output stops only when the value is explicitly unset (in bash(1) this is the unset builtin command. The noweb option at present works only for LaTeX as target typesetter. If the prettyprinter experiences problems when prettyprinting a certain code chunk, it automatically switches to standard verbatim output of noweb. Through the inclusion of code within rules of the for- matted grammar file it is possible to automate indexing. For more information see chapters 3 and 4 of the Pretzelbook, contained in the Pretzel distribution. CAVEATS
The pretzel-it shell script can only be run if the environment variables PRETZEL_LIBDIR and PRETZEL_INCLUDE are set to the Pretzel library directory (/usr/lib/pretzel on Debian systems) and the Pretzel include directory (/usr/include/pretzel on Debian systems). During execu- tion, pretzel-it might issue warnings that are due to the programs it invokes (pretzel-it invokes pretzel(1), flex(1), bison(1) and the GNU C++ compiler). The -n (noweb) option works only for LaTeX as target typesetter and is still very much experimental. FILES
/usr/lib/pretzel/libpretzel.a pretzel runtime library. /usr/include/pretzel directory for runtime library include files. /usr/include/pretzel/pscan.h /usr/include/pretzel/pparse.h template headers for the generated functions. /usr/lib/texmf/tex/latex/pretzel/pretzel-latex.sty LaTeX style to typeset Pretzel output. /usr/lib/pretzel/plainpp.o simple main program linked to the prettyprinter object generated by Pretzel. /usr/lib/pretzel/plaindpp.o simple main program linked to the prettyprinter object generated by Pretzel with debug features. /usr/lib/pretzel/nowebpretzelpp.o main program the interfaces the Preztel prettyprinter with noweb. SEE ALSO
pretzel(1), noweb(1) The Pretzelbook by Felix Gaertner, included in the Pretzel distribution. The Pretzel homepage on the WWW at http://www.iti.informatik.tu-darmstadt.de/~gaertner/pretzel AUTHOR
Felix Gaertner, email: fcg@acm.org June 11, 1998 pretzel-it(1)