From 790c9a5630256078d9c58b7313986723a70edb8d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Wed, 23 Jun 2021 02:24:30 +0200
Subject: Rename example.t to README.t

---
 Makefile    |   6 +-
 README.pdf  | Bin 0 -> 91606 bytes
 README.t    | 786 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 example.pdf | Bin 91606 -> 0 bytes
 example.t   | 786 ------------------------------------------------------------
 5 files changed, 789 insertions(+), 789 deletions(-)
 create mode 100644 README.pdf
 create mode 100644 README.t
 delete mode 100644 example.pdf
 delete mode 100644 example.t

diff --git a/Makefile b/Makefile
index f2ee1ae..b3686c0 100644
--- a/Makefile
+++ b/Makefile
@@ -1,8 +1,8 @@
-all: example.pdf hacking.pdf
+all: README.pdf hacking.pdf
 
 hacking.pdf: hacking.t g.tmac
 	perl -pe '$$_=`$$_` if s/^\!//' hacking.t |\
 	groff -Tps | ps2pdf - > hacking.pdf
 
-example.pdf: example.t g.tmac
-	toc/gtoc -Tps example.t | ps2pdf - > example.pdf
+README.pdf: README.t g.tmac
+	toc/gtoc -Tps README.t | ps2pdf - > README.pdf
diff --git a/README.pdf b/README.pdf
new file mode 100644
index 0000000..9f07118
Binary files /dev/null and b/README.pdf differ
diff --git a/README.t b/README.t
new file mode 100644
index 0000000..7e6e6f9
--- /dev/null
+++ b/README.t
@@ -0,0 +1,786 @@
+.so g.tmac
+.so toc/toc.tmac
+.
+.\" configure header and footer
+.eo
+.de @h
+. sp |36p
+. if \n%>1 .tl ''-%-''
+. sp |1i
+..
+.
+.de @f
+. sp |\n(.pu-48p
+. tl ''\*(#e''
+.. 
+.ec
+.
+.\" define macros
+.eo
+.de he
+. h
+\$*
+. te .the \n% \$*
+..
+.
+.de se
+. s
+\$*
+. te .the \n% \\h'18p'\$*
+..
+.
+.de the
+. nr _ \$1
+. shift
+. ta 0 \n(.luR
+. tc .
+\$*	\n_
+. tc
+. br
+..
+.
+.de n
+. if !'\$1'' \{\
+.  nr ni \$1-1
+.  af ni 0
+.  if !'\$2'' .af ni \$2
+.  ds n. .
+.  if !'\$3'' .ds n. \$3
+. \}
+. nr ni +1
+. br
+. @e n
+. ti \n(tiu
+\n(ni\*(n.	\c
+..
+.ec
+.
+.\" configure environments
+.@e l
+. fam M
+. vs +1p
+.@e n
+. @c p
+. nr sq \n(sp
+. nr sp 0
+. ta 3n +3n +3n +3n
+.@e
+.
+.\" start document
+.t
+.x Mg ,
+a simple macro package for troff
+.d
+John Ankarstr\(:om
+.d e
+.
+.s
+.ft I
+.tl ''TABLE OF CONTENTS''
+.ft
+.sp 4p
+.@e
+.to
+.sp 0.5i
+.ns
+.
+.he Introduction
+.p
+.i Mg
+is a simple macro package for troff with the following features:
+.n 1
+It is designed to be easy to understand and to customize
+by editing the source code.
+.n
+It makes use of the extended support for environments
+offered by many modern troff implementations.
+.n
+It is designed to be practically easy to use.
+Macros are consistently one letter long and written in lowercase.
+.p
+While
+.i mg
+does provide macros for many common tasks,
+including footnotes,
+it is at the end of the day an idiosyncratic macro package,
+written to serve the author's personal needs.
+Users of
+.i mg
+are encouraged to
+.n 1 a )
+modify the source code
+according to their own needs, as well as
+.n
+use built-in troff requests for some things
+that other packages might provide custom macros for.
+.p
+All in all,
+.i mg
+aspires to abstract as little as possible
+from the underlying troff requests and registers.
+In its author's humble opinion,
+it is the ideal macro package for learning troff.
+.p
+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,
+supported by implementations such as GNU troff and Neatroff.
+Environments obliviate the need for many special registers
+that a macro package (and its user) would otherwise need to keep track of.
+For example,
+.i ms
+keeps track of the document's font size in the
+.c PS
+register.
+For the font size of headings,
+it has yet another register.
+.i Mg
+has no such registers.
+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
+.p
+Troff saves the font settings in the environment,
+so that the next time the environment is invoked,
+the desired font family and point size are automatically restored.
+.p
+The environments are initialized
+as soon as the first
+.q block-level
+macro is called.
+At the initialization of each environment,
+the default environment (0) is copied,
+meaning that all environment-relevant settings
+defined before the first macro call
+are applied to all
+.i mg
+environments.
+It is thus remarkably simple and intuitive to set,
+for example, the default font of a document:
+.l
+\&.fam N
+\&.t
+Document title
+\&.p
+First paragraph.
+.p
+In addition to the normal environment-relevant settings,
+.i mg
+manually associates a few special registers with the current environment:
+.n 1
+.c sp ,
+the amount of vertical space to add before an environment
+.n
+.c sq ,
+the amount of vertical space to add before a different type of environment
+.n
+.c ti ,
+the indentation of the first line in some environments
+(currently only
+.c p )
+.p
+These can be set inside a given environment
+to control its behavior when invoked.
+The only exception are the margin and footnote environments
+.c @m , (
+.c @f ),
+which are treated specially
+and do not support these registers.
+.
+.
+.he External macros
+.p
+.i Mg
+defines a number of macros.
+Some of them are used internally by
+.i mg
+itself;
+these carry an at
+.c @ ) (
+prefix
+and are going to be explored later.
+For now, we will focus on the external macros provided by
+.i mg .
+.se Inline macros
+.p
+There is a group of macros that provide
+convenient inline formatting.
+All take three arguments:
+the text to be formatted,
+the text to be placed immediately after
+and the text to be placed immediately before.
+The inline macros are the following:
+.n 1
+.c b ,
+bold font
+.n
+.c c ,
+constant-width font
+.n
+.c i ,
+italic font
+.n
+.c i ,
+bold italic font
+.p
+For example, the following request outputs
+.i mg .\(rq: \(lq
+.l
+\&.i mg .
+.
+.p
+Note that
+.c c
+uses the font family and point size
+set in the
+.c l
+environment (see below).
+.se Block-level macros
+.p
+There is a large group of macros that provide
+block-level formatting:
+.n 1
+.c d ,
+centered date or text
+.n
+.c h ,
+heading
+.n
+.c l ,
+literal display (for source code)
+.n
+.c p ,
+paragraph
+.n
+.c s ,
+subheading
+.n
+.c t ,
+centered title
+.p
+The
+.c t
+and
+.c d
+macros can be used at the beginning of a document
+to create a centered header:
+.l
+\&.t
+Document title
+\&.d
+First author
+\&.br
+Second author
+\&.d i \\" current date formatted as YYYY-MM-DD
+.p
+In the example above, you can see that the
+.c d
+macro may be used for other things than just dates.
+This works because
+.c d
+displays the date only if given
+an argument describing the desired date format:
+.n 1 a )
+.c i :
+international date, like
+.q 2021-06-21
+.n
+.c e :
+English date, like
+.q "21 June 2021"
+.p
+The formatted dates are defined in strings prefixed with a hash symbol
+.c # ): (
+.c #i
+and
+.c #e
+are provided by default,
+but more may be added by the user.
+.
+.se Other macros
+.p
+Finally, there are a few macros
+that belong to neither category:
+.n 1
+.ne 2
+.c ( ,
+begin footnote
+.n
+.c ) ,
+end footnote
+.n
+.ne 2
+.c q ,
+quotation
+.n
+.c w ,
+want space
+.p
+The macros
+.c (
+and
+.c )
+create footnotes,
+placing a numerical reference at the place of their invocation.
+Both
+.c (
+and
+.c )
+take an optional argument,
+which is output either immediately before or immediately after
+the inline reference.
+For example, the following code
+.l
+\&.q
+This is a quotation\\c
+\&.(
+.ne 1
+This is a footnote.
+\&.) .
+.p
+creates the following reference:
+.q
+This is a quotation\c
+.(
+This is a footnote.
+.) .
+.p
+If
+.c (
+and
+.c )
+are called at such a position that the collected footnotes
+cannot fit on the current page,
+.i mg
+will print the footnotes on the next page instead.
+.p
+The
+.c q
+behaves like an inline macro by default,
+surrounding text in quotation marks,
+but if no arguments are given to it,
+it starts an indented block quotation instead:
+.l
+.ne 2
+\&.q
+This is an indented quotation.
+\&.p
+This is an inline
+\&.q quotation .
+.p
+The
+.c w
+macro is an alternative to troff's
+.c ne
+request,
+which ensures that a given amount of space is available on the page
+\(en otherwise, a line break is issued \(en
+but unlike
+.c ne ,
+which takes an exact amount of space as its argument,
+.c w
+takes a declarative specification
+describing the amount of desired space
+in terms of
+.i mg
+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
+.
+.
+.he Internal macros
+.p
+.i Mg 's
+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 on page \n[&faq].
+.
+.se Page header and footer
+.p
+The
+.c @h ,
+.c @f ,
+.c @th
+and
+.c @tf
+macros control the page header and footer.
+.p
+At document initialization,
+.i mg
+automatically creates traps for
+.c @th
+and
+.c @tf .
+When sprung,
+.c @th
+and
+.c @tf
+call
+.c @h
+and
+.c @t ,
+which control the text and spacing of the header and footer.
+.p
+.i Mg
+will avoid creating a trap for
+.c @tf
+if any trap has already been set before document initialization.
+This means that users can override the position of the
+.c @tf
+trap by setting it themselves.
+Likewise, users can redefine
+.c @h
+and
+.c @f
+to change the content of the header and footer.
+.
+.se Environments
+.p
+The environment-related macros
+.c (e ,
+.c @e
+and
+.c @c
+may be used in advanced documents to define custom environments.
+.p
+At the present,
+.c (e
+is nothing more than a wrapper around troff's built-in
+.c ev ,
+but it may eventually be redefined in order to offer
+compatibility with implementations of troff
+without support for named environments.
+.p
+.c @e
+and
+.c @c
+are equivalent to troff's
+.c ev
+and
+.c evc ,
+but perform some extra work to keep track of
+.i mg 's
+special environment variables
+(see
+.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
+All environment settings,
+like point size, font family and indentation\c
+.(
+For a complete list of settings that are associated with the environment,
+see 5.26\~\c
+.i Environments
+in the full GNU troff manual
+.nh
+.c "info '(groff.\:info)Environments'" ). (
+.hy
+.) ,
+are configured with the standard troff requests.
+If you set the point size at the beginning of the document,
+before any
+.i mg
+macros have been called,
+it will be correctly set for the entire document.
+This works because
+.i mg 's
+environments initially copy all their settings from 0,
+the default environment.
+.p
+For example, if you wanted to write a document
+with the New Century Schoolbook font
+at 9 points
+and a vertical spacing of 12 points,
+you would start the document like this
+(before you call any
+.i mg
+macros):
+.l
+\&.fam N
+\&.ps 9p
+\&.vs 12p
+.
+.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
+\&.q
+\&.ps +1p
+.p
+If you are merely configuring the environment
+without printing anything in it,
+you can also use the
+.c @e
+macro:
+.l
+\&.@e q
+\&.ps +1p
+.
+.w s ll
+.se How do I customize the default appearance of the margin text?
+.l
+\&.(e @m \\" margin environment
+\&.ps +1p
+.p
+You can also set such settings in your redefinition of
+.c @h
+or
+.c @f .
+.
+.w s ll
+.se How do I customize the default appearance of footnotes?
+.l
+\&.(e @f \\" footnote environment
+\&.ps +1p
+.
+.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
+\&. sp |1i
+\&..
+.
+.w s ll
+.se How do I redefine the page footer?
+.l
+\&.\\" set position of footer trap
+\&.\\" (must be done before any macros have been called)
+\&.wh -1i @tf
+\&.
+\&.de @f
+\&. \\" set position of footer text
+\&. \\" (must be below the footer trap)
+\&. sp |\\\\n(.pu-48p
+\&. tl 'left'center'right'
+\&..
+.
+.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 ,
+sections that are kept together across page breaks.
+.i Mg
+does not define any such macros by default.
+The simplest way to achieve the same is to use troff's
+.c ne
+request:
+.l
+\&.ne 7 \\" break page if seven lines won't fit on this page
+\&.\\" ... some text ...
+.p
+If you want to keep text of various styles together,
+you can use
+.i mg 's
+own
+.c w
+macro:
+.l
+\&.w s qq \\" break page if a subheading and two lines of a quotation won't fit
+\&.\\" ... some text ...
+.ig
+.p
+For a more general solution, you can use a diversion:
+.l
+\&.di keep
+\&.\\" ... some text ...
+\&.br
+\&.di
+\&.ne \\n(dnu
+\&.keep
+..
+.
+.se How do I define my own environments?
+.p
+Environments are a feature built into troff,
+accessed via the
+.c ev
+request, but because
+.i mg
+extends environments with additional functionality,
+it provides special macros to be used instead of
+.c ev :
+.n 1
+.c (e ,
+set environment (same as
+.c ev )
+.n
+.c @e ,
+set extended environment
+.n
+.c @c ,
+copy environment (same as
+.c evc )
+.p
+The
+.c @e
+macro
+can be used to activate any environment that supports
+.i mg 's
+extensions (see
+.i Environments ,
+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
+\&..
+.
+.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 toc ,
+a script that invokes troff in three passes
+in order to allow a table of contents to be generated
+.n
+.i gtoc ,
+an alias of
+.i toc
+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
+Wherever you want the table of contents to be inserted,
+you may simply invoke
+.c to .
+.p
+Just remember to run
+.c toc /\c
+.c gtoc
+instead of
+.c troff /\c
+.c groff :
+.l
+gtoc -Tps example.t > example.ps
+.p
+Thanks to the multiple passes performed by
+.i toc ,
+.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 toc
+with certain troff post-pocessors.
+.
+.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 toc
+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.)
diff --git a/example.pdf b/example.pdf
deleted file mode 100644
index 9f07118..0000000
Binary files a/example.pdf and /dev/null differ
diff --git a/example.t b/example.t
deleted file mode 100644
index 7e6e6f9..0000000
--- a/example.t
+++ /dev/null
@@ -1,786 +0,0 @@
-.so g.tmac
-.so toc/toc.tmac
-.
-.\" configure header and footer
-.eo
-.de @h
-. sp |36p
-. if \n%>1 .tl ''-%-''
-. sp |1i
-..
-.
-.de @f
-. sp |\n(.pu-48p
-. tl ''\*(#e''
-.. 
-.ec
-.
-.\" define macros
-.eo
-.de he
-. h
-\$*
-. te .the \n% \$*
-..
-.
-.de se
-. s
-\$*
-. te .the \n% \\h'18p'\$*
-..
-.
-.de the
-. nr _ \$1
-. shift
-. ta 0 \n(.luR
-. tc .
-\$*	\n_
-. tc
-. br
-..
-.
-.de n
-. if !'\$1'' \{\
-.  nr ni \$1-1
-.  af ni 0
-.  if !'\$2'' .af ni \$2
-.  ds n. .
-.  if !'\$3'' .ds n. \$3
-. \}
-. nr ni +1
-. br
-. @e n
-. ti \n(tiu
-\n(ni\*(n.	\c
-..
-.ec
-.
-.\" configure environments
-.@e l
-. fam M
-. vs +1p
-.@e n
-. @c p
-. nr sq \n(sp
-. nr sp 0
-. ta 3n +3n +3n +3n
-.@e
-.
-.\" start document
-.t
-.x Mg ,
-a simple macro package for troff
-.d
-John Ankarstr\(:om
-.d e
-.
-.s
-.ft I
-.tl ''TABLE OF CONTENTS''
-.ft
-.sp 4p
-.@e
-.to
-.sp 0.5i
-.ns
-.
-.he Introduction
-.p
-.i Mg
-is a simple macro package for troff with the following features:
-.n 1
-It is designed to be easy to understand and to customize
-by editing the source code.
-.n
-It makes use of the extended support for environments
-offered by many modern troff implementations.
-.n
-It is designed to be practically easy to use.
-Macros are consistently one letter long and written in lowercase.
-.p
-While
-.i mg
-does provide macros for many common tasks,
-including footnotes,
-it is at the end of the day an idiosyncratic macro package,
-written to serve the author's personal needs.
-Users of
-.i mg
-are encouraged to
-.n 1 a )
-modify the source code
-according to their own needs, as well as
-.n
-use built-in troff requests for some things
-that other packages might provide custom macros for.
-.p
-All in all,
-.i mg
-aspires to abstract as little as possible
-from the underlying troff requests and registers.
-In its author's humble opinion,
-it is the ideal macro package for learning troff.
-.p
-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,
-supported by implementations such as GNU troff and Neatroff.
-Environments obliviate the need for many special registers
-that a macro package (and its user) would otherwise need to keep track of.
-For example,
-.i ms
-keeps track of the document's font size in the
-.c PS
-register.
-For the font size of headings,
-it has yet another register.
-.i Mg
-has no such registers.
-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
-.p
-Troff saves the font settings in the environment,
-so that the next time the environment is invoked,
-the desired font family and point size are automatically restored.
-.p
-The environments are initialized
-as soon as the first
-.q block-level
-macro is called.
-At the initialization of each environment,
-the default environment (0) is copied,
-meaning that all environment-relevant settings
-defined before the first macro call
-are applied to all
-.i mg
-environments.
-It is thus remarkably simple and intuitive to set,
-for example, the default font of a document:
-.l
-\&.fam N
-\&.t
-Document title
-\&.p
-First paragraph.
-.p
-In addition to the normal environment-relevant settings,
-.i mg
-manually associates a few special registers with the current environment:
-.n 1
-.c sp ,
-the amount of vertical space to add before an environment
-.n
-.c sq ,
-the amount of vertical space to add before a different type of environment
-.n
-.c ti ,
-the indentation of the first line in some environments
-(currently only
-.c p )
-.p
-These can be set inside a given environment
-to control its behavior when invoked.
-The only exception are the margin and footnote environments
-.c @m , (
-.c @f ),
-which are treated specially
-and do not support these registers.
-.
-.
-.he External macros
-.p
-.i Mg
-defines a number of macros.
-Some of them are used internally by
-.i mg
-itself;
-these carry an at
-.c @ ) (
-prefix
-and are going to be explored later.
-For now, we will focus on the external macros provided by
-.i mg .
-.se Inline macros
-.p
-There is a group of macros that provide
-convenient inline formatting.
-All take three arguments:
-the text to be formatted,
-the text to be placed immediately after
-and the text to be placed immediately before.
-The inline macros are the following:
-.n 1
-.c b ,
-bold font
-.n
-.c c ,
-constant-width font
-.n
-.c i ,
-italic font
-.n
-.c i ,
-bold italic font
-.p
-For example, the following request outputs
-.i mg .\(rq: \(lq
-.l
-\&.i mg .
-.
-.p
-Note that
-.c c
-uses the font family and point size
-set in the
-.c l
-environment (see below).
-.se Block-level macros
-.p
-There is a large group of macros that provide
-block-level formatting:
-.n 1
-.c d ,
-centered date or text
-.n
-.c h ,
-heading
-.n
-.c l ,
-literal display (for source code)
-.n
-.c p ,
-paragraph
-.n
-.c s ,
-subheading
-.n
-.c t ,
-centered title
-.p
-The
-.c t
-and
-.c d
-macros can be used at the beginning of a document
-to create a centered header:
-.l
-\&.t
-Document title
-\&.d
-First author
-\&.br
-Second author
-\&.d i \\" current date formatted as YYYY-MM-DD
-.p
-In the example above, you can see that the
-.c d
-macro may be used for other things than just dates.
-This works because
-.c d
-displays the date only if given
-an argument describing the desired date format:
-.n 1 a )
-.c i :
-international date, like
-.q 2021-06-21
-.n
-.c e :
-English date, like
-.q "21 June 2021"
-.p
-The formatted dates are defined in strings prefixed with a hash symbol
-.c # ): (
-.c #i
-and
-.c #e
-are provided by default,
-but more may be added by the user.
-.
-.se Other macros
-.p
-Finally, there are a few macros
-that belong to neither category:
-.n 1
-.ne 2
-.c ( ,
-begin footnote
-.n
-.c ) ,
-end footnote
-.n
-.ne 2
-.c q ,
-quotation
-.n
-.c w ,
-want space
-.p
-The macros
-.c (
-and
-.c )
-create footnotes,
-placing a numerical reference at the place of their invocation.
-Both
-.c (
-and
-.c )
-take an optional argument,
-which is output either immediately before or immediately after
-the inline reference.
-For example, the following code
-.l
-\&.q
-This is a quotation\\c
-\&.(
-.ne 1
-This is a footnote.
-\&.) .
-.p
-creates the following reference:
-.q
-This is a quotation\c
-.(
-This is a footnote.
-.) .
-.p
-If
-.c (
-and
-.c )
-are called at such a position that the collected footnotes
-cannot fit on the current page,
-.i mg
-will print the footnotes on the next page instead.
-.p
-The
-.c q
-behaves like an inline macro by default,
-surrounding text in quotation marks,
-but if no arguments are given to it,
-it starts an indented block quotation instead:
-.l
-.ne 2
-\&.q
-This is an indented quotation.
-\&.p
-This is an inline
-\&.q quotation .
-.p
-The
-.c w
-macro is an alternative to troff's
-.c ne
-request,
-which ensures that a given amount of space is available on the page
-\(en otherwise, a line break is issued \(en
-but unlike
-.c ne ,
-which takes an exact amount of space as its argument,
-.c w
-takes a declarative specification
-describing the amount of desired space
-in terms of
-.i mg
-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
-.
-.
-.he Internal macros
-.p
-.i Mg 's
-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 on page \n[&faq].
-.
-.se Page header and footer
-.p
-The
-.c @h ,
-.c @f ,
-.c @th
-and
-.c @tf
-macros control the page header and footer.
-.p
-At document initialization,
-.i mg
-automatically creates traps for
-.c @th
-and
-.c @tf .
-When sprung,
-.c @th
-and
-.c @tf
-call
-.c @h
-and
-.c @t ,
-which control the text and spacing of the header and footer.
-.p
-.i Mg
-will avoid creating a trap for
-.c @tf
-if any trap has already been set before document initialization.
-This means that users can override the position of the
-.c @tf
-trap by setting it themselves.
-Likewise, users can redefine
-.c @h
-and
-.c @f
-to change the content of the header and footer.
-.
-.se Environments
-.p
-The environment-related macros
-.c (e ,
-.c @e
-and
-.c @c
-may be used in advanced documents to define custom environments.
-.p
-At the present,
-.c (e
-is nothing more than a wrapper around troff's built-in
-.c ev ,
-but it may eventually be redefined in order to offer
-compatibility with implementations of troff
-without support for named environments.
-.p
-.c @e
-and
-.c @c
-are equivalent to troff's
-.c ev
-and
-.c evc ,
-but perform some extra work to keep track of
-.i mg 's
-special environment variables
-(see
-.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
-All environment settings,
-like point size, font family and indentation\c
-.(
-For a complete list of settings that are associated with the environment,
-see 5.26\~\c
-.i Environments
-in the full GNU troff manual
-.nh
-.c "info '(groff.\:info)Environments'" ). (
-.hy
-.) ,
-are configured with the standard troff requests.
-If you set the point size at the beginning of the document,
-before any
-.i mg
-macros have been called,
-it will be correctly set for the entire document.
-This works because
-.i mg 's
-environments initially copy all their settings from 0,
-the default environment.
-.p
-For example, if you wanted to write a document
-with the New Century Schoolbook font
-at 9 points
-and a vertical spacing of 12 points,
-you would start the document like this
-(before you call any
-.i mg
-macros):
-.l
-\&.fam N
-\&.ps 9p
-\&.vs 12p
-.
-.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
-\&.q
-\&.ps +1p
-.p
-If you are merely configuring the environment
-without printing anything in it,
-you can also use the
-.c @e
-macro:
-.l
-\&.@e q
-\&.ps +1p
-.
-.w s ll
-.se How do I customize the default appearance of the margin text?
-.l
-\&.(e @m \\" margin environment
-\&.ps +1p
-.p
-You can also set such settings in your redefinition of
-.c @h
-or
-.c @f .
-.
-.w s ll
-.se How do I customize the default appearance of footnotes?
-.l
-\&.(e @f \\" footnote environment
-\&.ps +1p
-.
-.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
-\&. sp |1i
-\&..
-.
-.w s ll
-.se How do I redefine the page footer?
-.l
-\&.\\" set position of footer trap
-\&.\\" (must be done before any macros have been called)
-\&.wh -1i @tf
-\&.
-\&.de @f
-\&. \\" set position of footer text
-\&. \\" (must be below the footer trap)
-\&. sp |\\\\n(.pu-48p
-\&. tl 'left'center'right'
-\&..
-.
-.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 ,
-sections that are kept together across page breaks.
-.i Mg
-does not define any such macros by default.
-The simplest way to achieve the same is to use troff's
-.c ne
-request:
-.l
-\&.ne 7 \\" break page if seven lines won't fit on this page
-\&.\\" ... some text ...
-.p
-If you want to keep text of various styles together,
-you can use
-.i mg 's
-own
-.c w
-macro:
-.l
-\&.w s qq \\" break page if a subheading and two lines of a quotation won't fit
-\&.\\" ... some text ...
-.ig
-.p
-For a more general solution, you can use a diversion:
-.l
-\&.di keep
-\&.\\" ... some text ...
-\&.br
-\&.di
-\&.ne \\n(dnu
-\&.keep
-..
-.
-.se How do I define my own environments?
-.p
-Environments are a feature built into troff,
-accessed via the
-.c ev
-request, but because
-.i mg
-extends environments with additional functionality,
-it provides special macros to be used instead of
-.c ev :
-.n 1
-.c (e ,
-set environment (same as
-.c ev )
-.n
-.c @e ,
-set extended environment
-.n
-.c @c ,
-copy environment (same as
-.c evc )
-.p
-The
-.c @e
-macro
-can be used to activate any environment that supports
-.i mg 's
-extensions (see
-.i Environments ,
-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
-\&..
-.
-.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 toc ,
-a script that invokes troff in three passes
-in order to allow a table of contents to be generated
-.n
-.i gtoc ,
-an alias of
-.i toc
-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
-Wherever you want the table of contents to be inserted,
-you may simply invoke
-.c to .
-.p
-Just remember to run
-.c toc /\c
-.c gtoc
-instead of
-.c troff /\c
-.c groff :
-.l
-gtoc -Tps example.t > example.ps
-.p
-Thanks to the multiple passes performed by
-.i toc ,
-.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 toc
-with certain troff post-pocessors.
-.
-.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 toc
-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