aboutsummaryrefslogtreecommitdiff
path: root/toc/toc.1
blob: dbee298c099bec7f16c65ffd2fdef19c4f67c576 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
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 .