Rename example.t to README.t

1 files changed, 786 insertions, 0 deletions

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.)