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.t | 81 +++++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 55 insertions(+), 26 deletions(-)

(limited to 'toc/README.t')

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
-- 
cgit v1.2.3