From 5369e3972cd18e8e97d35b4ead7a0fc67ff66658 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Tue, 22 Jun 2021 22:18:02 +0200
Subject: example.t: Add FAQ on forward references using toc.tmac

---
 example.pdf | Bin 89797 -> 90832 bytes
 example.t   |  49 +++++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 41 insertions(+), 8 deletions(-)

diff --git a/example.pdf b/example.pdf
index dfbad23..c4f6516 100644
Binary files a/example.pdf and b/example.pdf differ
diff --git a/example.t b/example.t
index 06fa21b..ba8871f 100644
--- a/example.t
+++ b/example.t
@@ -20,13 +20,13 @@
 .de he
 . h
 \$*
-. tm .the \n% \$*
+. te .the \n% \$*
 ..
 .
 .de se
 . s
 \$*
-. tm .the \n% \\h'18p'\$*
+. te .the \n% \\h'18p'\$*
 ..
 .
 .de the
@@ -118,11 +118,17 @@ it is the ideal macro package for learning troff.
 In this document, the fundamental concepts of
 .i mg
 are explained.
+The document itself also serves as a demonstration of
+.i mg .
+With a couple of exceptions, it uses
+.i mg 's
+default settings.
 The reader is encouraged to inspect the document's source code
 in order to see how the macro package is used in practice.
 .
 .
 .he Environments
+.te .nr &env \n%
 .p
 .i Mg
 makes heavy use of named environments,
@@ -407,7 +413,7 @@ internal macros are generally not meant to be used outside of
 .i g.tmac .
 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.
+see the FAQ section on page \n[&faq].
 .
 .se Margin macros
 .p
@@ -476,11 +482,12 @@ but perform some extra work to keep track of
 .i mg 's
 special environment variables
 (see
-.i Environments
-above).
+.i Environments ,
+p. \n[&env]).
 .
 .
 .he Frequently anticipated questions
+.te .nr &faq \n%
 .
 .se How do I customize the default appearance of a document?
 .p
@@ -641,8 +648,8 @@ macro
 can be used to activate any environment that supports
 .i mg 's
 extensions (see
-.i Environments
-above).
+.i Environments ,
+p. \n[&env]).
 The following code configures an environment called
 .c n
 and defines a corresponding macro:
@@ -718,7 +725,11 @@ to create a heading to be included in the table of contents:
 .l
 \&.he A heading
 .p
-Just remember to invoke
+Wherever you want the table of contents to be inserted,
+you may simply invoke
+.c to .
+.p
+Just remember to run
 .c troc /\c
 .c groc
 instead of
@@ -742,3 +753,25 @@ environment variable.
 This may be useful if you need to combine
 .i troc
 with certain troff post-processors.
+.
+.se How do I create a reference to a later page?
+.p
+Use the macros provided by
+.i toc.tmac
+in combination with the
+.i troc
+program.
+Near the beginning of your document, invoke
+.c to .
+Then, at each position you want to reference,
+invoke
+.c .te
+like this:
+.l
+\&.te .nr &refname \n%
+.p
+To refer to that position, interpolate the register:
+.l
+See page \\n[&refname].
+.p
+(I prefer prefixing my references with an ampersand.)
-- 
cgit v1.2.3