From d2335d060ffa1e8e2285bde265d71c1db703486b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Thu, 24 Jun 2021 19:48:11 +0200
Subject: Add toc.1

---
 toc/toc.1    | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 toc/toc.tmac |  4 ++--
 2 files changed, 79 insertions(+), 2 deletions(-)
 create mode 100644 toc/toc.1

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)\$*
 ..
-- 
cgit v1.2.3