Add 'list' utility

7 files changed, 227 insertions, 139 deletions

diff --git a/Makefile b/Makefile
index 6aa8fa8..36299f0 100644
--- a/Makefile
+++ b/Makefile
@@ -9,7 +9,8 @@ all: README.pdf HACKING.pdf
 
 install:
 	install -m 644 u.tmac t/toc.tmac $(TMACDIR)
-	install t/toc $(BINDIR)
+	install -m 644 toc/toc.1 list/list.1 $(MANDIR)/man1
+	install toc/toc list/list $(BINDIR)
 
 HACKING.pdf: HACKING.t u.tmac
 	perl -pe '$$_=`$$_` if s/^\!//' HACKING.t |\
@@ -17,4 +18,4 @@ HACKING.pdf: HACKING.t u.tmac
 
 README.pdf: README.t u.tmac
 	TROFFONTS=/usr/pkg/share/fonts/X11/TTF/ \
-	<README.t toc/toc $(PDFROFF) > README.pdf
+	<README.t toc/toc list/list -p=.l \| $(PDFROFF) > README.pdf
diff --git a/README.pdf b/README.pdf
index 3db0084..94d4dfa 100644
--- a/README.pdf
+++ b/README.pdf
diff --git a/README.t b/README.t
index c62be75..f49637a 100644
--- a/README.t
+++ b/README.t
@@ -3,6 +3,7 @@
 .so toc/toc.tmac
 .mediasize letter
 .fp 0 M DejaVuSansMono ttf
+.hw Eng-lish
 .
 .\" configure table of contents
 .eo
@@ -150,11 +151,12 @@ If the user wishes to modify the default font size,
 he or she can simply switch to the relevant environment
 and set the font size as desired
 using regular troff requests:
-.l
-\&.\\" set heading font
-\&.h
-\&.fam H
-\&.ps +1p
+.l(
+.\" set heading font
+.h
+.fam H
+.ps +1p
+.l)
 .p
 Troff saves the font settings in the environment,
 so that the next time the environment is invoked,
@@ -173,12 +175,13 @@ are applied to all
 environments.
 It is thus remarkably simple and intuitive to set,
 for example, the default font of a document:
-.l
-\&.fam N
-\&.t
+.l(
+.fam N
+.t
 Document title
-\&.p
+.p
 First paragraph.
+.l)
 .p
 In addition to the normal environment-relevant settings,
 .i µ
@@ -246,8 +249,9 @@ bold italic font
 .p
 For example, the following request outputs
 .i µ .\(rq: \(lq
-.l
-\&.i µ .
+.l(
+.i µ .
+.l)
 .
 .p
 Note that
@@ -288,14 +292,15 @@ and
 .c d
 macros can be used at the beginning of a document
 to create a centered header:
-.l
-\&.t
+.l(
+.t
 Document title
-\&.d
+.d
 First author
-\&.br
+.br
 Second author
-\&.d i \\" current date formatted as YYYY-MM-DD
+.d i \" current date formatted as YYYY-MM-DD
+.l)
 .p
 In the example above, you can see that the
 .c d
@@ -350,13 +355,14 @@ take an optional argument,
 which is output either immediately before or immediately after
 the inline reference.
 For example, the code
-.l
-\&.q
-This is a quotation\\c
-\&.(
-.ne 1
+.l(
+.q
+This is a quotation\c
+.(
+\!.ne 1
 This is a footnote.
-\&.) .
+.)
+.l)
 .p
 generates the following output:
 .q
@@ -391,11 +397,12 @@ in terms of
 .i µ
 environments.
 For example:
-.l
-\&.\\" want space for...
-\&.w s p \\" a subheading of one line + a paragraph of one line
-\&.w s pp \\" a subheading of one line + a paragraph of two lines
-\&.w ss p \\" a subheading of two lines + a paragraph of one line
+.l(
+.\" want space for...
+.w s p \" a subheading of one line + a paragraph of one line
+.w s pp \" a subheading of one line + a paragraph of two lines
+.w ss p \" a subheading of two lines + a paragraph of one line
+.l)
 .
 .
 .he Internal macros
@@ -513,33 +520,37 @@ you would start the document like this
 (before you call any
 .i µ
 macros):
-.l
-\&.fam N
-\&.ps 9p
-\&.vs 12p
+.l(
+.fam N
+.ps 9p
+.vs 12p
+.l)
 .
 .se How do I customize the default appearance of a given environment?
 .p
 To configure the layout and font settings of a specific environment,
 you can switch to that environment and use the relevant troff requests:
-.l
-.ne 1
-\&."
-\&.ps +1p
+.l(
+\!.ne 1
+.q
+.ps +1p
+.l)
 .p
 If you are merely configuring the environment
 without printing anything in it,
 you can also use
 .c @e :
-.l
-\&.@e q
-\&.ps +1p
+.l(
+.@e q
+.ps +1p
+.l)
 .
 .w s ll
 .se How do I customize the default appearance of the margin text?
-.l
-\&.(e @m \\" margin environment
-\&.ps +1p
+.l(
+.(e @m \" margin environment
+.ps +1p
+.l)
 .p
 You can also set such settings in your redefinition of
 .c @h
@@ -548,42 +559,46 @@ or
 .
 .w s ll
 .se How do I customize the default appearance of footnotes?
-.l
-\&.(e @f \\" footnote environment
-\&.ps +1p
+.l(
+.(e @f \" footnote environment
+.ps +1p
+.l)
 .
 .w s ll
 .se How do I redefine the page header?
-.l
-\&.de @h
-\&. \\" set position of header text
-\&. sp |36p
-\&. \\" set header text
-\&. tl 'left'center'right'
-\&. \\" set position of page text
-.ne 1
-\&. sp |1i
-\&..
+.l(
+.de @h
+. \" set position of header text
+. sp |36p
+. \" set header text
+. tl 'left'center'right'
+. \" set position of page text
+\!.ne 1
+. sp |1i
+..
+.l)
 .
 .w s ll
 .se How do I redefine the page footer?
 .p
 To change the position of the footer:
-.l
-\&.\\" set position of footer trap
-\&.\\" (must be done before any macros have been called)
-\&.wh -1i @tf
-\&.
+.l(
+.\" set position of footer trap
+.\" (must be done before any macros have been called)
+.wh -1i @tf
+.
+.l)
 .p
 To change the contents of the footer:
-.l
-\&.de @f
-\&. \\" set position of footer text
-\&. \\" (must be below the footer trap)
-\&. sp |\\\\n(.pu-48p
-\&. \\" set footer text
-\&. tl 'left'center'right'
-\&..
+.l(
+.de @f
+. \" set position of footer text
+. \" (must be below the footer trap)
+. sp |\\n(.pu-48p
+. \" set footer text
+. tl 'left'center'right'
+..
+.l)
 .
 .se How do I define my own environments?
 .p
@@ -618,17 +633,18 @@ p. \n[&env]).
 The following code configures an environment called
 .c n
 and defines a corresponding macro:
-.l
-\&.@e n
-\&. @c 0 \\" copy default environment
-\&. ps -1p
-\&.@e
-\&.
-\&.de n
-\&. br \\" finish current environment
-.ne 1
-\&. @e n \\" activate new environment
-\&..
+.l(
+.@e n
+. @c 0 \" copy default environment
+. ps -1p
+.@e
+.
+.de n
+. br \" finish current environment
+\!.ne 1
+. @e n \" activate new environment
+..
+.l)
 .
 .se How do I prevent a section from being broken up by a page break?
 .p
@@ -640,9 +656,10 @@ does not (at least yet) define any such macros by default.
 The simplest solution is to use troff's
 .c ne
 request:
-.l
-\&.ne 7 \\" break page if seven lines won't fit on this page
-\&.\\" ... some text ...
+.l(
+.ne 7 \" break page if seven lines won't fit on this page
+.\" ... some text ...
+.l)
 .p
 If you want to keep text of various styles together,
 you can use
@@ -650,19 +667,21 @@ you can use
 own
 .c w
 macro:
-.l
-\&.w s qq \\" break page if a subheading and two lines of a quotation won't fit
-\&.\\" ... some text ...
+.l(
+.w s qq \" break page if a subheading and two lines of a quotation won't fit
+.\" ... some text ...
+.l)
 .ig
 .p
 For a more general solution, you can use a diversion:
-.l
-\&.di keep
-\&.\\" ... some text ...
-\&.br
-\&.di
-\&.ne \\n(dnu
-\&.keep
+.l(
+.di keep
+.\" ... some text ...
+.br
+.di
+.ne \n(dnu
+.keep
+.l)
 ..
 .
 .se How do I use alternative quotation marks?
@@ -670,20 +689,22 @@ For a more general solution, you can use a diversion:
 Redefine
 .c \(dq .
 The following code defines a Swedish quotation style:
-.l
-\&.de "
-\\\\&\\\\$3”\\\\$1”\\\\$2
-\&..
+.l(
+.de "
+\\&\\$3”\\$1”\\$2
+..
+.l)
 .p
 Another option is to create new macros for alternative quotation styles:
-.l
-\&.\\" alternative swedish quotation styles
-\&.de ><
-\\\\&\\\\$3»\\\\$1«\\\\$2
-\&..
-\&.de >>
-\\\\&\\\\$3»\\\\$1»\\\\$2
-\&..
+.l(
+.\" alternative swedish quotation styles
+.de ><
+\\&\\$3»\\$1«\\$2
+..
+.de >>
+\\&\\$3»\\$1»\\$2
+..
+.l)
 .
 .se How do I create nested inline quotations?
 .p
@@ -699,16 +720,17 @@ for example when converting a document from US to British English,
 you can redefine
 .c "
 to translate backticks and apostrophes accordingly:
-.l
-\&.eo
-\&.de "
-\&. char ` \\(lq
-\&. char ' \\(rq
-\\&\\$3\\(oq\\$1\\(cq\\$2
-\&. char ` \\(oq
-\&. char ' \\(cq
-\&..
-\&.ec
+.l(
+.eo
+.de "
+. char ` \(lq
+. char ' \(rq
+\&\$3\(oq\$1\(cq\$2
+. char ` \\(oq
+. char ' \\(cq
+..
+.ec
+.l)
 .
 .se How do I include a table of contents in my document?
 .te .nr &toc \n%
@@ -743,29 +765,31 @@ Note that the argument given to
 will be interpreted as a troff input line.
 .p
 The following definitions provide a good starting point:
-.l
-\&.eo
-\&.de he
-\&. h
-\\$*
-\&. tm .the \\$*\\t\\n%
-\&..
-\&.de the
-\&. ta 0 \\n(.luR
-\&. tc .
-\\$*
-\&. tc
-\&. br
-\&..
-\&.ec
+.l(
+.eo
+.de he
+. h
+\$*
+. tm .the \$*\t\n%
+..
+.de the
+. ta 0 \n(.luR
+. tc .
+\$*
+. tc
+. br
+..
+.ec
+.l)
 .p
 Now, instead of
 .c h ,
 you may use
 .c he
 to create a heading to be included in the table of contents:
-.l
-\&.he A heading
+.l(
+.he A heading
+.l)
 .p
 Wherever you want the table of contents to be inserted,
 you may simply invoke
@@ -774,8 +798,9 @@ you may simply invoke
 Just remember to use
 .c toc
 to run your processing pipeline:
-.l
-<example.t toc refer \\| troff -Tps >example.ps
+.l(
+<example.t toc refer \| troff -Tps >example.ps
+.l)
 .p
 Thanks to the multiple passes performed by
 .i toc ,
@@ -799,11 +824,13 @@ Then, at each position you want to reference,
 invoke
 .c .te
 like this:
-.l
-\&.te .nr &refname \\n%
+.l(
+.te .nr &refname \n%
+.l)
 .p
 To refer to that position, interpolate the register:
-.l
-See page \\n[&refname].
+.l(
+See page \n[&refname].
+.l)
 .p
 (I prefer prefixing my references with an ampersand.)
diff --git a/list/list b/list/list
new file mode 100755
index 0000000..64ec8ac
--- /dev/null
+++ b/list/list
@@ -0,0 +1,17 @@
+#!/usr/bin/perl -ps
+
+# list -- escape code listing for troff
+
+if (/^\.\s*l\(\s*$/ .. /^\.\s*l\)\s*$/) {
+	not $E and s/^\\!// and next;
+	if (/^\.\s*l\(\s*$/) {
+		print "$p\n" if $p;
+	} elsif (/^\.\s*l\)\s*$/) {
+		print "$s\n" if $s;
+	} else {
+		s/\\/\\$&/g;
+		s/^/\\&/g;
+		s/'/\\(aq/g;
+		s/\`/\\(ga/g;
+	}
+}
diff --git a/list/list.1 b/list/list.1
new file mode 100644
index 0000000..085bb20
--- /dev/null
+++ b/list/list.1
@@ -0,0 +1,43 @@
+.Dd $Mdocdate$
+.Dt list 1
+.Os
+.Sh NAME
+.Nm list
+.Nd escape code listings for troff
+.
+.Sh SYNOPSIS
+.Nm
+.Op Fl p=prefix
+.Op Fl s=suffix
+.Op Fl E
+.Op Ar file
+.Sh DESCRIPTION
+.Pp
+.Nm
+escapes text between
+.Ql .l(
+and
+.Ql .l)
+lines for
+.Xr troff 1 .
+.Pp
+Lines beginning with
+.Ql \\\\!
+are copied verbatim, unless the
+.Fl E
+flag is given.
+.Pp
+Text given to
+.Fl p
+and
+.Fl s
+is inserted on a new line before and after each code block.
+This text is not escaped and can contain arbitrary
+.Xr troff 1
+requests.
+.
+.Sh AUTHORS
+.Pp
+.Nm
+is written by John Ankarström
+.Aq Mt "john (at) ankarstrom.se" .
diff --git a/toc/README.pdf b/toc/README.pdf
index cfa2f6d..317cbc4 100644
--- a/toc/README.pdf
+++ b/toc/README.pdf
diff --git a/toc/README.t b/toc/README.t
index 318adf3..f4d9687 100644
--- a/toc/README.t
+++ b/toc/README.t
@@ -32,7 +32,7 @@ The
 .i toc
 script is a wrapper around troff,
 passing the document through the typesetter three times.
-In every pass, it sets the values of a registers and a string named
+In every pass, it sets the values of a register and a string named
 .i te
 and
 .i tf ,