aboutsummaryrefslogtreecommitdiff
path: root/toc/README.t
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 /toc/README.t
parentbffbccd88aa57541bffca931c6a4c205773ad619 (diff)
downloadmk-909074e4fdf727f07556edc076f18c0fc86944d2.tar.gz
toc/README.t: Document new behavior
Diffstat (limited to 'toc/README.t')
-rw-r--r--toc/README.t81
1 files changed, 55 insertions, 26 deletions
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