From b23a1093b73e16f1b69e5d8d05c9e3dcf8ee5d65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Sun, 27 Jun 2021 18:37:36 +0200
Subject: Add 'list' utility

---
 README.t | 299 ++++++++++++++++++++++++++++++++++-----------------------------
 1 file changed, 163 insertions(+), 136 deletions(-)

(limited to 'README.t')

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