From 8db0a30e605d9473658b3eeda4626d3548abe872 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= Date: Tue, 22 Jun 2021 21:58:25 +0200 Subject: example.t: Document toc.tmac --- example.pdf | Bin 85294 -> 89797 bytes example.t | 155 +++++++++++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 117 insertions(+), 38 deletions(-) diff --git a/example.pdf b/example.pdf index 95c2bb4..dfbad23 100644 Binary files a/example.pdf and b/example.pdf differ 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. -- cgit v1.2.3