aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohn Ankarström <john@ankarstrom.se>2021-06-27 18:37:36 +0200
committerJohn Ankarström <john@ankarstrom.se>2021-06-27 18:37:36 +0200
commitb23a1093b73e16f1b69e5d8d05c9e3dcf8ee5d65 (patch)
tree7561a64156f244bda61c14a1b673c028e3f27d74
parente8086631ecabb0018062c1b8a519a2fa265c92f9 (diff)
downloadmk-b23a1093b73e16f1b69e5d8d05c9e3dcf8ee5d65.tar.gz
Add 'list' utility
-rw-r--r--Makefile5
-rw-r--r--README.pdfbin62089 -> 62043 bytes
-rw-r--r--README.t299
-rwxr-xr-xlist/list17
-rw-r--r--list/list.143
-rw-r--r--toc/README.pdfbin28728 -> 28572 bytes
-rw-r--r--toc/README.t2
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
Binary files differ
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
Binary files differ
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 ,