.TH NUWEB 1 "local 2/26/93"
.SH NAME
Nuweb, a literate programming tool
.SH SYNOPSIS
.B nuweb
.br
\fBnuweb\fP [\fB-t\fP|\fB-c\fP|\fB-o\fP] [file] ...
.SH DESCRIPTION
.I Nuweb
is a literate programming tool like Knuth's
.I WEB,
only simpler.
A 
.I nuweb
file contains program source code interleaved with documentation.
When 
.I nuweb
is given a 
.I nuweb
file, it writes the program file(s),
and also 
produces,
.I LaTeX
source for typeset documentation.
.SH COMMAND LINE OPTIONS
.br
\fB-t\fP	Suppress generation of the \fB.tex\fP file.
.br
\fB-o\fP	Suppress generation of the output file(s).
.br
\fB-c\fP	Avoid testing output files for change before updating them.
.br
.SH FORMAT OF NUWEB FILES
A 
.I nuweb 
file contains mostly ordinary
.I LaTeX.
The file is read and copied to output (.tex file) unless a
.I nuweb
command is encountered. All 
.I nuweb
commands start with an ``at-sign'' (@). 
Files and macros are defined with the following commands:
.PP
@o \fIfile-name flags  scrap\fP  where scrap is smaller than one page.
.br
@O \fIfile-name flags  scrap\fP  where scrap is bigger than one page.
.br
@d \fImacro-name scrap\fP. Where scrap is smallar than one page.
.br
@D \fImacro-name scrap\fP. Where scrap is bigger than one page.
.PP
Scraps have specific begin and end 
markers: \fB@{\fP and \fB@}\fP.
Any amount of whitespace
(including carriage returns) may appear between a name and the
begining of a scrap.
.PP
Several code/file scraps may have the same name;
.I nuweb
concatenates their definitions to produce a single scrap.
Code scrap definitions are like macro definitions;
.I nuweb
extracts a program by expanding one scrap.
The definition of that scrap contains references to other scraps, which are 
themselves expanded, and so on.
\fINuweb\fP's output is readable; it preserves the indentation of expanded
scraps with respect to the scraps in which they appear.
.PP
.SH PER FILE OPTIONS
When defining an output file, the programmer has the option of using flags
to control the output.
.PP
\fB-d\fR option, 
.I Nuweb
will emit line number indications at scrap boundaries.
.br
\fB-i\fR option, 
.I Nuweb
supresses the indentation of macros (useful for \fBFortran\fR).
.br
\fB-t\fP option makes \fInuweb\fP 
copy tabs untouched from input to output.
.PP
.SH MINOR COMMANDS
.br
@@ 	Causes a single ``at-sign'' to be copied into the output.
.br
@i 	\fBfilename\fR causes the file named to be included.
.br
@f 	Creates an index of output files.
.br
@m 	Creates an index of macros.
.br
@u 	Creates an index of user-specified identifiers.
.PP
To mark an identifier for inclusion in the index, it must be mentioned
at the end of the scrap it was defined in. The line starts
with @| and ends with the \fBend of scrap\fP mark \fB@}\fP.
.PP
.SH ERROR MESSAGES
.PP
.SH BUGS
.PP
.SH AUTHOR
Preston Briggs.
Internet address \fBpreston@cs.rice.edu\fP.