diff options
authorJohn Ankarström <john@ankarstrom.se>2021-06-24 19:48:11 +0200
committerJohn Ankarström <john@ankarstrom.se>2021-06-24 19:48:11 +0200
commitd2335d060ffa1e8e2285bde265d71c1db703486b (patch)
parente6b0af9699dee016e273a69e82030a93b6d16e8d (diff)
Add toc.1
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
+.Nm toc
+.Nd run troff in multiple passes
+.Ar cmd ...
+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.
+As arguments, it takes a
+.Xr troff 1
+command line, which is evaluated as a shell command on each pass.
+.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.
+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.
+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
+Note that the pipeline
+.Ql refer | troff
+is handed to
+.Nm ,
+which runs it at every pass.
+is done, it prints the output on standard out.
+In this case, it is passed to
+.Xr dpost 1 ,
+which converts it to PostScript.
+is written by John Ankarström
+.Aq Mt "john (at) ankarstrom.se" .
+Whitespace in the arguments to
+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 @@
-.\" 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)\$*