NOWEB

Section: User Commands (1)
Updated: local 4/19/93
Index Return to Main Contents

NAME

noweb - a simple literate-programming tool

SYNOPSIS

noweb [-t] [-o] [-Lformat] [-markup parser] [file] ...

DESCRIPTION

Noweb is a literate-programming tool like FunnelWEB nuweb, only simpler. noweb file contains program source code interleaved with documentation. When noweb is invoked, it writes the program source code to the output files mentioned in the noweb file, and it writes a TeX file for typeset documentation. For more flexibility, consider notangle(1) noweave(1).

FORMAT OF NOWEB FILES

noweb file is a sequence of chunks, which may appear in any order. A chunk may contain code or documentation. Documentation chunks begin with a line that starts with an at sign (@) followed by a space or newline. They have no names. Code chunks begin with <<chunk name>>= on a line by itself. The double left angle bracket (<<) must be in the first column. Chunks are terminated by the beginning of another chunk, or by end of file. If the first line in the file does not mark the beginning of a chunk, it is assumed to be the first line of a documentation chunk. Documentation chunks contain text that is copied verbatim to the TeX file (except for quoted code). noweb works with LaTeX; the first documentation chunk must contain LaTeX \\documentstyle command with the noweb document-style option. It must also contain a LaTeX \\begin{document} command. Code chunks contain program source code and references to other code chunks. Several code chunks may have the same name; noweb concatenates their definitions to produce a single chunk, just as other literate-programming tools do. noweb looks for chunks that are defined but not used in the source file. If the name of such a chunk contains no spaces, the chunk is an ``output file;'' noweb expands it and writes the result onto the file of the same name. A code-chunk definition is like a macro definition; it contains references to other chunks, which are themselves expanded, and so on. noweb's output is readable; it preserves the indentation of expanded chunks with respect to the chunks in which they appear. If a star (*) is appended to the name of an output file, noweb includes line-number information as specified by the -Lformat option (or for C if no -Lformat option is given). The name itself may not contain shell metacharacters. Code may be quoted within documentation chunks by placing double square brackets ([[...]]) around it. These double square brackets are used to give the code special typographic treatment in the TeX file. If quoted code ends with three or more square brackets, noweb chooses the rightmost pair, so that, for example, [[a[i]]] is parsed correctly. If double left and right angle brackets are not paired, they are treated as literal << and >>. Users can force any such brackets, even paired brackets, to be treated as literal by using a preceding at sign (e.g. @<<). Any line beginning with `@ ' terminates a code chunk, but if the line has the form @ %def identifiers it is taken to mean that the preceding chunk defines the identifiers listed identifiers. This list contains identifiers separated by whitespace; any sequence of nonwhite characters may be an identifier. noweb uses a simple heuristic to avoid recognizing identifiers that are substrings of other identifiers.

OPTIONS

-t Suppress generation of a TeX file. -o Suppress generation of output files. -Lformat format to format line-number information for starred output files. (If the option is omitted, a format suitable for C is used.) format is as defined by notangle(1); -markup parser parser to parse the input file. Enables use of noweb tools on files in other formats; for example, the numarkup parser understands nuweb(1) format. nowebfilters(1) for more information. For experts only.

BUGS

Ignoring unused chunks whose names contain spaces sometimes causes problems, especially in the case when a chunk has multiple definitions and one is misspelled; the misspelled definition will be silently ignored. noroots(1) can be used as a sanity checker to catch this sort of mistake. noweb requires the new version of awk, assumed to be called nawk. nawk has a bug in that that causes problems with braces in TeX output. gawk is reported to work. The default LaTeX pagestyles don't set the width of the boxes containing headers and footers. Since noweb code paragraphs are extra wide, this LaTeX bug sometimes results in extra-wide headers and footers. The remedy is to redefine the relevant ps@* commands; ps@noweb noweb.sty can be used as an example.

AUTHOR

Norman Ramsey, Bellcore. Internet address norman@bellcore.com. Noweb home page at ftp://bellcore.com/pub/norman/www/noweb/intro.html.

This document was created by man2html, using the manual pages.
Time: 00:09:42 GMT, September 01, 2024