#

# About noweb and Leo

The following noweb man page is used by permission of the author, Norman Ramsey.

### The noweb man page

Noweb is a literate-programming tool like Knuth's WEB, only simpler. A noweb file contains program source code interleaved with documentation.

Body text is a sequence of chunks (also known as sections), which may appear in any order. A chunk may contain code or documentation. Doc 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 the body text. If the first line of body text does not mark the beginning of a chunk, it is assumed to be the first line of a documentation chunk.

Doc chunks contain text that is ignored by the Tangle command and copied verbatim to standard output by the Print (Weave) command (except for quoted code).

Code chunks contain program source code and references to other code chunks. Several code chunks may have the same name; the Tangle command concatenates their definitions to produce a single chunk. Code chunk definitions are like macro definitions; The Tangle command extracts a file by expanding the chunk following the @root directive. (See below). The definition of that chunk contains references to other chunks, which are themselves expanded, and so on.

The output of the Tangle command is readable; it preserves the indentation of expanded chunks with respect to the chunks in which they appear.

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

Some programming or formatting languages may require a single @ sign in the first column. Noweb users may achieve this effect by putting a doubled @@ in the first column; in this position only, it stands for a single @ sign.

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 in identifiers. This list contains identifiers separated by whitespace; any sequence of non white characters may be an identifier.

### Addendum to the noweb man page

Here are some details of how Leo handles noweb:

- Leo ignores case leading and trailing whitespace in chunk names, and converts whitespace within chunk names to a single blank. For example, the following chunk names are equivalent:

>     	<< goto done if x < y >>
>     	<<GOTO done if x  <  y>>

- Chunk names may not contain newlines.
- The only Leo directives that terminate chunks are @code and @doc. For historical reasons, Leo's @doc directive is equivalent to @ on a line by itself.
- Leo syntax colors everything << as a section name, even if there is no following >> on the same line.
- The definition of the chunk consists of the concatenation all the code and documentation chunks in the order they appear in the body text. If the chunks are found in more than one node, the order used is outline order. Outline order is the order the nodes would appear on the screen if all nodes were expanded. It is bad programming style to have the meaning of a chunk depend on the order in which the parts of its definition appear.
- Leo associates doc chunks with the immediately following code chunk, if any. The Preferences panel allows the user to choose whether to output such documentation chunks. Leo uses the current comment delimiters (see below) to output such documentation chunks.
- The Tangle command uses the @root directive (see below) as the starting point for expanding chunks.
- The Tangle command ignores body text if it contains no code chunk and no @doc directive.

Windows versions of Leo prior to version 2.0 are different in from leo.py and Windows version 2.x.

allow @<< instead of << .

The @code directive is an abbreviation for << chunk name >>=, provided that the headline text of the node containing the @code directive starts with a valid chunk name. See below for more details.

Leo does not presently support the <<*>> syntax.