A One-Page Guide to Using noweb with L^{A}TEX

Norman Ramsey after Lee Wittenberg and Carl Gregory

The noweb file foo.nw

Documentation

@ in column 1 of a line by itself starts a documentation chunk.

Text is in L^{A}TEX; use [[…]] for embedded code fragments.

noweave automatically wraps file in

      \documentclass{article}
      \usepackage{noweb}
      \begin{document}

⋮

      \end{document}

To avoid wrapper, put \documentclass and

\usepackage in your source and use noweave -delay.

Code

<<… name of chunk… >>= in column 1 of a line by itself starts a code chunk.

Code is in any language; use <<… >> to include other code chunks by reference.

You can write multiple code chunks with the same name; they are concatenated.

Name chunks inside functions with verbs, e.g., ⟨copy all lines from in to out, adding markup⟩.

Name chunks holding declarations with nouns, e.g., ⟨private function prototypes⟩ or ⟨definitions of exported functions⟩.

Name top-level “root” chunks after the files they are to

                                                 represent, e.g., <<foo.c>>= or <<foo.h>>=.

For emacs users: A first line of % -*- mode: Noweb; noweb-code-mode: c-mode -*- is useful (to set editing mode for code chunks). The Unix teTeX distribution comes with helpful Info files that cover L^{A}TEX and dvips.

Typical Commands

notangle -L -Rfoo.c foo.nw > foo.c  Extract file foo.c, with #line
notangle -Rfoo.h foo.nw | cpif foo.h  Extract file foo.h if it has changed (without #line).

noweave -filter l2h -index -html foo.nw > foo.html Create HTML, converting documentation from L^{A}TEX.
noweave -x foo.nw > foo.tex  Create L^{A}TEX document with cross-reference, no index.
latex foo; latex foo  Process L^{A}TEX into “device-independent” (dvi) file.
latex '\scrollmode \input foo'  Alternate L^{A}TEX command for use in Makefile.

dvips -o foo.ps foo  Convert foo.dvi into PostScript.

Minimal L^{A}TEX

Special characters Not to be typed in text; OK in code

    % \ { } $ & # ^_~

Escapes for specials

    \% $\backslash$ \{ \} \$ \& \# \_

Blank line is new paragraph.

Write ``quotes'' to get “quotes.” Never "quotes".

Titles \title{...}

       \author{...}
       \maketitle

Sectioning \section{...}

           \subsection{...}
           \subsubsection{...}

Fonts \emph{emphasis}

                                                        \textbf{bold}
                                                        \texttt{typewriter}
                                                        \textit{italics}
                                                        \textsf{sans serif}
                                                        \textsc{small caps}
                                                 Lists List of items
                                                        \begin{itemize}
                                                        \item one
                                                        \item two
                                                        \item three
                                                        \end{itemize}

List of items ; • one ; • two ; • three

Also \begin{enumerate} for numbered lists.

Get the right version; you want L^{A}TEX2ε, not L^{A}TEX 2.09.