diff options
| -rw-r--r-- | toc/toc.1 | 77 | ||||
| -rw-r--r-- | toc/toc.tmac | 4 |
2 files changed, 79 insertions, 2 deletions
diff --git a/toc/toc.1 b/toc/toc.1 new file mode 100644 index 0000000..dbee298 --- /dev/null +++ b/toc/toc.1 @@ -0,0 +1,77 @@ +.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. +.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 . diff --git a/toc/toc.tmac b/toc/toc.tmac index b97aaf9..f885f91 100644 --- a/toc/toc.tmac +++ b/toc/toc.tmac @@ -8,12 +8,12 @@ . .eo . -.\" to -- evaluate collected lines +.\" to -- gather and evaluate lines .de to . if !'\*(tf'' .so \*(tf .. . -.\" te -- collect line +.\" te -- emit line .de te . if \n(te=1 .tm (toc)\$* .. |