From 909074e4fdf727f07556edc076f18c0fc86944d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Wed, 23 Jun 2021 21:35:39 +0200
Subject: toc/README.t: Document new behavior

---
 toc/README.pdf | Bin 25615 -> 28728 bytes
 toc/README.t   |  81 +++++++++++++++++++++++++++++++++++++++------------------
 toc/toc        |  30 +++++++++------------
 3 files changed, 68 insertions(+), 43 deletions(-)

diff --git a/toc/README.pdf b/toc/README.pdf
index 94b970f..cfa2f6d 100644
Binary files a/toc/README.pdf and b/toc/README.pdf differ
diff --git a/toc/README.t b/toc/README.t
index c326700..b561486 100644
--- a/toc/README.t
+++ b/toc/README.t
@@ -1,4 +1,6 @@
 .so ../g.tmac
+.so ../gx.tmac
+.so toc.tmac
 .
 .t
 .x Toc ,
@@ -7,8 +9,13 @@ a multipass framework for troff
 John Ankarstr\(:om
 .d e
 .
-.h
-Introduction
+.s
+.ce
+.i "TABLE OF CONTENTS"
+.@e 0
+.to
+.sp 0.5i
+.he Introduction
 .p
 .i Toc
 is a very simple solution
@@ -57,8 +64,7 @@ specified by
 .i tf
 into the troff document.
 .
-.h
-Operation
+.he Operation
 .p
 In the first pass, the
 .i toc
@@ -117,7 +123,8 @@ inserting the contents of
 .i $h
 into the document.
 .p
-Three is the number of passes necessary \(en and sufficient \(en
+Theoretically, three is the number of passes that are necessary
+\(en and sufficient \(en
 for generating forward references,
 such as tables of contents.
 Two passes are not enough,
@@ -126,9 +133,13 @@ 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.
+.p
+In practice, however,
+.i toc
+has the ability to detect how many passes are needed
+and will never do more work than what is necessary.
 .
-.h
-Usage
+.he Usage
 .s
 Macro package
 .p
@@ -175,27 +186,45 @@ 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-processors can be added by setting
-.i TROFF
-to a custom shell script:
+script is a wrapper around troff
+and any potential troff pre- or post-processors.
+On standard input, it expects the troff source to be processed.
+As arguments, it takes a shell command line to be evaluated on every pass.
+For example, the invocation
 .l
-.ne 3
-$ cat xroff
-#!/bin/sh
-\&... | groff "$@"
-$ TROFF=./xroff toc document.t
+$ <example.t toc refer -prefs \\| groff -C
+.p
+passes the contents of
+.i example.t
+through the
+.i refer
+preprocessor and the
+.i groff
+implementation of troff.
+Note the escaped pipe character;
+because
+.i toc
+passes its arguments directly to
+.i /bin/sh 's
+.i eval ,
+arbitrary shell syntax is supported,
+as long as it is escaped.\c
+.(
+This also means that whitespace in arguments is not properly preserved.
+If you need to include whitespace in the arguments to troff or
+a troff preprocessor, create a separate shell script
+and invoke
+.i toc
+on that.
+.)
+.p
+Note that input must be given on standard in;
+it cannot be provided as a filename to, for example,
+.i refer
+or
+.i groff .
 .
-.h
-Examples
+.he Examples
 .
 .s
 Table of contents
diff --git a/toc/toc b/toc/toc
index 4e1f298..f6c2501 100755
--- a/toc/toc
+++ b/toc/toc
@@ -2,15 +2,9 @@
 
 # toc -- run troff in three passes
 
-RM=rm
-AWK='
-	/^\(toc\)/ { print substr($0, 6); next }
-	{ print > "/dev/stderr" }
-'
-
 usage() {
-1>&2	echo "usage: $0 [cmd ... \|] <troff> [arg ...]"
-1>&2	echo "(input should be given on stdin)"
+	echo "usage: $0 [cmd ... \|] <troff> [arg ...]" 1>&2
+	echo "(input should be given on stdin)" 1>&2
 	exit 1
 }
 
@@ -25,27 +19,29 @@ end() {
 	exit $s
 }
 
+RM=rm
+AWK='
+	/^\(toc\)/ { print substr($0, 6); next }
+	{ print > "/dev/stderr" }
+'
+
 [ $# -eq 0 ] && usage
 trap '$RM; RM=; exit 130' INT
 trap '$RM' EXIT
-
-tmp f
->$f cat
-
-tmp g
-tmp h
-tmp i
-tmp j
+for t in f g h i j; do tmp $t; done
 
 echo $0: first pass 1>&2
-{ eval "$@" -rte=1 -dtf=; s=$?; } <$f 2>&1 1>$i | awk "$AWK" >$g
+
+tee $f | { eval "$@" -rte=1 -dtf=; s=$?; } 2>&1 1>$i | awk "$AWK" >$g
 [ -s $g ] || end $i
 
 echo $0: second pass 1>&2
+
 { eval "$@" -rte=1 -dtf=$g; s=$?; } <$f 2>&1 1>$j | awk "$AWK" >$h
 diff -q $g $h >/dev/null && end $j
 
 echo $0: third pass 1>&2
+
 { eval "$@" -rte=0 -dtf=$h; s=$?; } <$f | grep -v '^(toc)'
 
 exit $s
-- 
cgit v1.2.3