aboutsummaryrefslogtreecommitdiff
path: root/example.t
diff options
context:
space:
mode:
authorJohn Ankarström <john@ankarstrom.se>2021-06-22 21:58:25 +0200
committerJohn Ankarström <john@ankarstrom.se>2021-06-22 21:58:25 +0200
commit8db0a30e605d9473658b3eeda4626d3548abe872 (patch)
tree4c31bb6aac64ffc324773de68344eca686f8f540 /example.t
parent92ab79cc00be5fb01a07f3381efdc3fc9bdc2348 (diff)
downloadmk-8db0a30e605d9473658b3eeda4626d3548abe872.tar.gz
example.t: Document toc.tmac
Diffstat (limited to 'example.t')
-rw-r--r--example.t155
1 files changed, 117 insertions, 38 deletions
diff --git a/example.t b/example.t
index d2b9f1c..06fa21b 100644
--- a/example.t
+++ b/example.t
@@ -15,18 +15,6 @@
..
.ec
.
-.\" configure environments
-.@e p
-. nr sq \n(sp
-. nr sp 0
-.@e l
-. fam M
-. vs +1p
-.@e n
-. @c p
-. ta 3n +3n +3n +3n
-.@e
-.
.\" define macros
.eo
.de he
@@ -35,6 +23,12 @@
. tm .the \n% \$*
..
.
+.de se
+. s
+\$*
+. tm .the \n% \\h'18p'\$*
+..
+.
.de the
. nr _ \$1
. shift
@@ -61,6 +55,18 @@
..
.ec
.
+.\" configure environments
+.@e p
+. nr sq \n(sp
+. nr sp 0
+.@e l
+. fam M
+. vs +1p
+.@e n
+. @c p
+. ta 3n +3n +3n +3n
+.@e
+.
.\" start document
.t
.x Mg ,
@@ -203,8 +209,7 @@ prefix
and are going to be explored later.
For now, we will focus on the external macros provided by
.i mg .
-.s
-Inline macros
+.se Inline macros
.p
There is a group of macros that provide
convenient inline formatting.
@@ -238,8 +243,7 @@ uses the font family and point size
set in the
.c l
environment (see below).
-.s
-Block-level macros
+.se Block-level macros
.p
There is a large group of macros that provide
block-level formatting:
@@ -301,8 +305,7 @@ and
are provided by default,
but more may be added by the user.
.
-.s
-Other macros
+.se Other macros
.p
Finally, there are a few macros
that belong to neither category:
@@ -406,8 +409,7 @@ Documented in this section are the exceptions to this rule.
For examples of how these macros are used in practice,
see the FAQ section below.
.
-.s
-Margin macros
+.se Margin macros
.p
The
.c @h ,
@@ -446,8 +448,7 @@ and
.c @f
to change the content of the header and footer.
.
-.s
-Environment macros
+.se Environment macros
.p
The environment-related macros
.c (e ,
@@ -481,8 +482,7 @@ above).
.
.he Frequently anticipated questions
.
-.s
-How do I customize the default appearance of a document?
+.se How do I customize the default appearance of a document?
.p
All environment settings,
like point size, font family and indentation\c
@@ -519,8 +519,7 @@ macros):
\&.ps 9p
\&.vs 12p
.
-.s
-How do I customize the default appearance of a given environment?
+.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:
@@ -539,8 +538,7 @@ macro:
\&.ps +1p
.
.w s ll
-.s
-How do I customize the default appearance of the margin text?
+.se How do I customize the default appearance of the margin text?
.l
\&.(e @m \\" margin environment
\&.ps +1p
@@ -551,14 +549,12 @@ or
.c @f .
.
.w s ll
-.s
-How do I customize the default appearance of footnotes?
+.se How do I customize the default appearance of footnotes?
.l
\&.(e @f \\" footnote environment
\&.ps +1p
.
-.s
-How do I redefine the page header?
+.se How do I redefine the page header?
.l
\&.de @h
\&. \\" set position of header text
@@ -569,8 +565,7 @@ How do I redefine the page header?
\&. sp |1i
\&..
.
-.s
-How do I redefine the page footer?
+.se How do I redefine the page footer?
.l
\&.\\" set position of footer trap
\&.\\" (must be done before any macros have been called)
@@ -583,8 +578,7 @@ How do I redefine the page footer?
\&. tl 'left'center'right'
\&..
.
-.s
-How do I prevent a section from being broken up by a page break?
+.se How do I prevent a section from being broken up by a page break?
.p
Some macro packages have a concept of
.q keeps ,
@@ -619,8 +613,7 @@ For a more general solution, you can use a diversion:
\&.keep
..
.
-.s
-How do I define my own environments?
+.se How do I define my own environments?
.p
Environments are a feature built into troff,
accessed via the
@@ -663,3 +656,89 @@ and defines a corresponding macro:
\&. br \\" finish current environment
\&. @e n \\" activate new environment
\&..
+.
+.se How do I include a table of contents in my document?
+.p
+Included with the
+.i mg
+distribution is a package called
+.i toc ,
+which includes the following files:
+.n 1
+.i toc.tmac ,
+which provides the
+.c te
+and
+.c to
+macros
+.n
+.i troc ,
+a script that invokes troff in three passes
+in order to allow a table of contents to be generated
+.n
+.i groc ,
+an alias of
+.i troc
+that invokes groff instead of troff
+.p
+Use
+.c te
+to register a line to be inserted into the table of contents.
+Use
+.c to
+to insert the table of contents.
+Note that the argument given to
+.c te
+will be interpreted as a troff input line.
+.p
+The following definitions provide a good basis:
+.l
+\&.eo
+\&.de he
+\&. h
+\\$*
+\&. tm .the \\n% \\$*
+\&..
+\&.de the
+\&. nr _ \\$1
+\&. shift
+\&. ta 0 \\n(.luR
+\&. tc .
+\\$* \\n_
+\&. tc
+\&. br
+\&..
+\&.ec
+.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
+.p
+Just remember to invoke
+.c troc /\c
+.c groc
+instead of
+.c troff /\c
+.c groff :
+.l
+groc -Tps example.t > example.ps
+.p
+Thanks to the multiple passes performed by
+.i troc ,
+.c to
+can be invoked at any place in the document,
+including the beginning.
+The macros listed above are the ones used to generate
+the table of contents of this document.
+.p
+Note that you can invoke a custom program instead of troff
+by setting the
+.i TROFF
+environment variable.
+This may be useful if you need to combine
+.i troc
+with certain troff post-processors.