Rename example.t to README.t

1 files changed, 0 insertions, 786 deletions

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