diff options
Diffstat (limited to 'toc')
| -rw-r--r-- | toc/README.pdf | bin | 25615 -> 28728 bytes | |||
| -rw-r--r-- | toc/README.t | 81 | ||||
| -rwxr-xr-x | toc/toc | 30 |
3 files changed, 68 insertions, 43 deletions
diff --git a/toc/README.pdf b/toc/README.pdf Binary files differindex 94b970f..cfa2f6d 100644 --- a/toc/README.pdf +++ b/toc/README.pdf 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 @@ -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 |