aboutsummaryrefslogtreecommitdiff
path: root/README.t
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 /README.t
parente8086631ecabb0018062c1b8a519a2fa265c92f9 (diff)
downloadmk-b23a1093b73e16f1b69e5d8d05c9e3dcf8ee5d65.tar.gz
Add 'list' utility
Diffstat (limited to 'README.t')
-rw-r--r--README.t299
1 files changed, 163 insertions, 136 deletions
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.)