aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohn Ankarström <john@ankarstrom.se>2021-06-23 21:35:39 +0200
committerJohn Ankarström <john@ankarstrom.se>2021-06-23 21:35:39 +0200
commit909074e4fdf727f07556edc076f18c0fc86944d2 (patch)
treeeeea8eb0dc8db7c3a3cd77cfb16719ef772f0b15
parentbffbccd88aa57541bffca931c6a4c205773ad619 (diff)
downloadmk-909074e4fdf727f07556edc076f18c0fc86944d2.tar.gz
toc/README.t: Document new behavior
-rw-r--r--toc/README.pdfbin25615 -> 28728 bytes
-rw-r--r--toc/README.t81
-rwxr-xr-xtoc/toc30
3 files changed, 68 insertions, 43 deletions
diff --git a/toc/README.pdf b/toc/README.pdf
index 94b970f..cfa2f6d 100644
--- a/toc/README.pdf
+++ b/toc/README.pdf
Binary files 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