From db0af0983ae6aacd495c389015c9df5f48e2092a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Wed, 23 Jun 2021 02:23:34 +0200
Subject: Add toc/README.t

---
 toc/README.pdf | Bin 0 -> 24496 bytes
 toc/README.t   | 205 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 205 insertions(+)
 create mode 100644 toc/README.pdf
 create mode 100644 toc/README.t

diff --git a/toc/README.pdf b/toc/README.pdf
new file mode 100644
index 0000000..dfbb33b
Binary files /dev/null and b/toc/README.pdf differ
diff --git a/toc/README.t b/toc/README.t
new file mode 100644
index 0000000..71e3f93
--- /dev/null
+++ b/toc/README.t
@@ -0,0 +1,205 @@
+.so ../g.tmac
+.
+.t
+.x toc ,
+a multipass framework for troff
+.d
+John Ankarstr\(:om
+.d e
+.
+.h
+Introduction
+.p
+.i Toc
+is a very simple solution
+\(en in 50 or so lines \(en
+to the problem of generating tables of contents
+and other forms of forward references
+in troff documents.
+It consists of a shell script called
+.i toc
+and a macro package called
+.i toc.tmac .
+.p
+The
+.i toc
+script is a wrapper around troff,
+passing the document through the typesetter three times.
+In every pass, it sets the values of two registers named
+.i te
+and
+.i to .
+.p
+The
+.i toc.tmac
+package defines two macros, also named
+.c te
+and
+.c to .
+If the
+.i te
+register is non-zero, the
+.c te
+macro hands its argument to the
+.c tm
+request, which prints it on standard error.
+If the
+.i to
+register is non-zero, the
+.c to
+macro invokes the
+.c rd
+request, reading and inserting lines from standard input
+into the troff document.
+.
+.h
+Operation
+.p
+In the first pass, the
+.i toc
+script sets
+.i te
+= 1 and
+.i to
+= 0.
+This enables the
+.c te
+macro, printing its arguments on standard error.
+The lines printed on standard error
+are piped to the second invocation of troff.
+.p
+In the second pass,
+.i toc
+sets
+.i te
+= 1 and
+.i to
+= 1.
+This enables the
+.c to
+macro as well, inserting the lines given on standard error
+into the troff source.
+The
+.c te
+macro is still activated and accordingly
+prints its arguments on standard error yet another time.
+Like before, the output is piped to the third invocation of troff.
+.p
+In the third and final pass,
+.i toc
+sets
+.i te
+= 0 and
+.i to
+= 1.
+This disables
+.c te ,
+which means that nothing is printed on standard error,
+but
+.c to
+is still enabled,
+once again inserting the input on standard error into the document.
+.p
+Three is the number of passes necessary \(en and sufficient \(en
+for generating forward references,
+such as tables of contents.
+Two passes are not enough,
+as the generated references may push
+a referent to the next page,
+rendering the generated references incorrect.
+To account for the addition of the generated references,
+a third pass is needed.
+.
+.h
+Usage
+.s
+Macro package
+.p
+The
+.c te
+and
+.c to
+macros do not apply any formatting to
+or perform any processing of their input.
+The
+.c te
+macro prints its arguments on standard error verbatim.
+For example, the request
+.l
+\&.te .nr &a \\n%
+.p
+will print
+.l
+\&.nr &a \\n%
+.p
+on standard error.
+Let us assume the page number is 3.
+When
+.c to
+is invoked, it will literally insert
+.l
+\&.nr &a 3
+.p
+into the troff source.
+.p
+As such,
+.i toc
+provides the tools needed to create forward references,
+including tables of contents,
+but the exact formatting must be programmed by the user himself.
+.
+.s
+Script
+.p
+The
+.i toc
+script is designed to be called instead of troff.
+It is not a troff preprocessor, but a wrapper around it.
+Any arguments given to
+.i toc
+are passed to troff
+(or whichever program specified in the
+.i TROFF
+environment variable).
+.p
+Pre- and post-processors can be added by setting
+.i TROFF
+to a custom shell script:
+.l
+.ne 3
+$ cat xroff
+#!/bin/sh
+\&... | groff "$@" | ...
+$ TROFF=./xroff toc document.t
+.
+.h
+Examples
+.
+.s
+Table of contents
+.p
+.l
+\&.so toc.tmac
+\&.de he
+\&. ft B
+\&. sp 1v
+\\$*
+\&. br
+\&. ft
+\&. te .the \\n% \\$*
+\&..
+\&.de the
+\&. nr _ \\$1
+\&. shift
+\&. ta 0 \\n(.luR
+\&. tc .
+\\$*     \\n_
+\&. tc
+\&. br
+\&..
+\&.sp |1i
+\&.to
+\&.\\" ...
+\&.he First heading
+\&.\\" ...
+\&.he Second heading
-- 
cgit v1.2.3