From df9030831e294af0030d3c9df092a1ea910aa6df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Wed, 23 Jun 2021 12:21:41 +0200
Subject: toc: Use .so instead of .rd

---
 toc/README.t | 74 +++++++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 48 insertions(+), 26 deletions(-)

(limited to 'toc/README.t')

diff --git a/toc/README.t b/toc/README.t
index 10e0ee5..c326700 100644
--- a/toc/README.t
+++ b/toc/README.t
@@ -25,14 +25,15 @@ 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
+In every pass, it sets the values of a registers and a string named
 .i te
 and
-.i to .
+.i tf ,
+respectively.
 .p
 The
 .i toc.tmac
-package defines two macros, also named
+package defines two macros, named
 .c te
 and
 .c to .
@@ -42,14 +43,18 @@ register is non-zero, the
 .c te
 macro hands its argument to the
 .c tm
-request, which prints it on standard error.
+request, which prints it on standard error,
+prefixed by
+.q (toc) .
 If the
-.i to
-register is non-zero, the
+.i tf
+string is non-empty, the
 .c to
 macro invokes the
-.c rd
-request, reading and inserting lines from standard input
+.c so
+request, reading and inserting lines from the file
+specified by
+.i tf
 into the troff document.
 .
 .h
@@ -60,45 +65,57 @@ In the first pass, the
 script sets
 .i te
 = 1 and
-.i to
-= 0.
+.i tf
+= empty.
 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.
+The lines prefixed with
+.q (toc) ,
+printed on standard error,
+are written to the file
+.i $g
+with the
+.q (toc)
+prefix removed.
 .p
 In the second pass,
 .i toc
 sets
 .i te
 = 1 and
-.i to
-= 1.
+.i tf
+=
+.i $g .
 This enables the
 .c to
-macro as well, inserting the lines given on standard error
+macro as well, inserting the contents of
+.i $g
 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.
+The output is processed like earlier and written to the file
+.i $h .
 .p
 In the third and final pass,
 .i toc
 sets
 .i te
 = 0 and
-.i to
-= 1.
+.i tf
+=
+.i $h .
 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.
+inserting the contents of
+.i $h
+into the document.
 .p
 Three is the number of passes necessary \(en and sufficient \(en
 for generating forward references,
@@ -126,21 +143,26 @@ The
 macro prints its arguments on standard error verbatim.
 For example, the request
 .l
-\&.te .nr &a \\n%
+\&.te .nr &ref \\n%
 .p
 will print
 .l
-\&.nr &a \\n%
+\&(toc).nr &ref \\n%
 .p
 on standard error.
-Let us assume the page number is 3.
+The
+.q (toc)
+prefix is removed before the line is written to the temporary file.
+.p
 When
 .c to
 is invoked, it will literally insert
 .l
-\&.nr &a 3
+\&.nr &ref 3
 .p
-into the troff source.
+into the troff source, assuming
+.c te
+was invoked on the third page.
 .p
 As such,
 .i toc
@@ -162,14 +184,14 @@ are passed to troff
 .i TROFF
 environment variable).
 .p
-Pre- and post-processors can be added by setting
+Pre-processors can be added by setting
 .i TROFF
 to a custom shell script:
 .l
 .ne 3
 $ cat xroff
 #!/bin/sh
-\&... | groff "$@" | ...
+\&... | groff "$@"
 $ TROFF=./xroff toc document.t
 .
 .h
-- 
cgit v1.2.3