example.t: Document toc.tmac

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.