From 909074e4fdf727f07556edc076f18c0fc86944d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= 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(-) (limited to 'toc') 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 +$ &2 echo "usage: $0 [cmd ... \|] [arg ...]" -1>&2 echo "(input should be given on stdin)" + echo "usage: $0 [cmd ... \|] [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