# An Example of noweb

## Contents

- Introduction
- Counting words
- Index

## Introduction

The following short program illustrates the use of `noweb`, a low-tech tool for literate programming. The purpose of the program is to provide a basis for comparing `WEB` and `noweb`, so I have used a program that has been published before; the text, code, and presentation are taken from Chapter 12 of D. E. Knuth, Literate Programming (volume 27 of Center for the Study of Language and Information Lecture Notes, Stanford Univ., 1992).

The notable differences are:

- When displaying source code, `noweb` uses different typography. In particular, `WEB` makes good use of multiple fonts and the ablity to typeset mathematics, and it may use mathematical symbols in place of C symbols (e.g. a logical ``and'' symbol for ``[[&&]]''). `noweb` uses a single fixed-width font for code.
- `noweb` can work with HTML, and I have used HTML in this example.
- `noweb` has no numbered ``sections.'' When cross-referencing is needed, `noweb` uses hypertext links or page numbers.
- `noweb` has no special support for macros. In the sample program, I have used a ``Definitions'' chunk to hold macro definitions.
- `noweb`'s index of identifiers is less accurate than `WEB`'s, because it uses a language-independent heuristic to find identifiers. This heuristic may erroneously find ``uses'' of identifiers in string literals or comments. Although `noweb` does have a language-dependent algorithm for finding definitions of identifiers, that algorithm is less reliable than `CWEB`'s, because `noweb` does not really parse C code.
- The `CWEB` version of this program has semicolons following most uses of <...>. `WEB` needs the semicolon or its equivalent to make its prettyprinting come out right. Because it does not attempt prettyprinting, `noweb` needs no semicolons.

## Counting words

This example, based on a program by Klaus Guntermann and Joachim Schrod (``WEB` adapted to C.' TUGboat 7(3):134-7, Oct. 1986) and a program by Silvio Levy and D. E. Knuth (Ch. 12 of Literate Programming), presents the ``word count'' program from Unix, rewritten in `noweb` to demonstrate literate programming using `noweb`. The level of detail in this document is intentionally high, for didactic purposes; many of the things spelled out here don't need to be explained in other programs.

The purpose of `wc` is to count lines, words, and/or characters in a list of files. The number of lines in a file is the number of newline characters it contains. The number of characters is the file length in bytes. A ``word'' is a maximal sequence of consecutive characters other than newline, space, or tab, containing at least one visible ASCII code. (We assume that the standard ASCII code is in use.)

Most literate C programs share a common structure. It's probably a good idea to state the overall structure explicitly at the outset, even though the various parts could all be introduced in chunks named <*> if we wanted to add them piecemeal.

Here, then, is an overview of the file `wc.c` that is defined by the `noweb` program `wc.nw`: <<*>>= <

> <<Definitions>> <<Global variables>> <<Functions>> <<The main program>> @ We must include the standard I/O definitions, since we want to send formatted output to [[stdout]] and [[stderr]]. <