.Dd $Mdocdate$
.Dt toc 1
.Os
.Sh NAME
.Nm toc
.Nd run troff in multiple passes
.
.Sh SYNOPSIS
.Nm
.Ar cmd ...
.Sh DESCRIPTION
.Pp
.Nm
in multiple passes in order to pass information
.Xr troff 1
in multiple passes in order to pass information
from the end of the document to the beginning.
.Pp
As arguments, it takes a
.Xr troff 1
command line, which is evaluated as a shell command on each pass.
If the command line is a pipeline,
.Xr troff 1
must be the final command.
.Pp
.Nm
runs
.Xr troff 1
as many times as are needed,
with a minimum of one and a maximum of three.
The typical usage is for creating tables of contents,
but it can be used to pass arbitrary
.Xr troff 1
code to a given document location.
.Pp
.Nm
is designed to be used in combination with the
.Em toc.tmac
package, which defines the macros
.Em te ,
for emitting code from later parts of the document, and
.Em to ,
for gathering and evaluating emitted code in an earlier part.
.
.Sh EXAMPLES
.Pp
The following invocation generates the PostScript file
example.ps from the troff source file example.t with
.Nm :
.Bd -literal -offset indent
$ <example.t toc refer \\| troff | dpost >example.ps
.Ed
.Pp
Note that the pipeline
.Ql refer | troff
is handed to
.Nm ,
which runs it at every pass.
When
.Nm
is done, it prints the output on standard out.
In this case, it is passed to
.Xr dpost 1 ,
which converts it to PostScript.
.
.Sh AUTHORS
.Pp
.Nm
is written by John Ankarström
.Aq Mt "john (at) ankarstrom.se" .
.Sh BUGS
.Pp
Whitespace in the arguments to
.Nm
is not preserved.
If this is a problem, the
.Xr troff 1
pipeline should be written to a shell script,
which can be safely used with
.Nm .