.so g.tmac
.
. \" configure environments
._e p
. nr sq \n(sp
. nr sp 0
._e l
. fam M
. vs +1p
._e n
. _ec p
. ta 3n +3n +3n +3n
._e
.
. \" define macros
.eo
.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
.
.
. \" start document
.t
.x Mg ,
a simple macro package for troff
.d "John Ankarstr\[u00F6]m"
.d
.
.
.h
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 reader is encouraged to inspect the document's source code
in order to see how the macro package is used in practice.
.
.
.h
Environments
.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.
.
.
.h
Global settings
.p
Thanks to the reliance on environments,
there are only four global string values
controlling the state of
.i mg :
.n 1
.c mt ,
the margin at the top of the page
.n
.c mb ,
the margin at the bottom of the page
.n
.c tt ,
the text in the top margin
.n
.c tb ,
the text in the bottom margin
.p
The
.c tt
and
.c tb
registers are passed to troff's
.c tl
request and should be formatted accordingly.
By default,
.c tt
is empty and
.c tb
is set to
.c ''%'' ,
displaying the page number in the center.
.
.
.h
External macros
.p
.i Mg
defines a number of macros.
Some of them are used internally by
.i mg
itself;
these carry an underscore prefix
and are going to be explored later.
For now, we will focus on the external macros provided by
.i mg .
.s
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).
.s
Block-level macros
.p
There is a large group of macros that provide
block-level formatting:
.n 1
.c d ,
centered date (or given string)
.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"
\&.d "Second author"
\&.d \\" current date
.p
Here, you can see that the
.c d
macro may be used for other things than dates.
.
.s
Other macros
.p
Finally, there are a few macros
that belong to neither category.
.n 1
.c q ,
quotation
.n
.c ( ,
begin footnote
.n
.c ) ,
end footnote
.p
By default,
.c q
behaves like an inline macro,
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 footnote macros
.c (
and
.c )
are used like this\c
.(
Note that
.c (
and
.c )
take an optional argument,
which is output immediately before or after
the footnote number.
.) :
.l
\&.p
A line of text\\c
\&.(
.ne 2
A footnote.
\&.) .
.p
.i Mg
does not account for cases where a footnote, because of its height,
pushes the place where it is referenced to the next page.
In such cases, the reference will simply appear on the page
following the footnote.
When this happens, the user must account for it manually.
.
.
.h
Internal macros
.p
.i Mg 's
internal macros are generally not meant to be used outside of
.i g.tmac .
.c _E ,
.c _e
and
.c _ec ,
a group of macros controlling the environment,
are excepted from this rule,
as it may be desirable to define custom environments
for advanced documents.
.
.
.h
Frequently anticipated questions
.
.s
How do I set the default font family, point size, indentation
of a document?
.p
All environment settings\c
.(
For a complete list of settings that are associated with the environment,
see 5.26\ Environments in the full GNU troff manual
.nh
.c "info '(groff.\:info)Environments'" ). (
.hy
.)
such as these
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:
.l
\&.so g.tmac \\" include mg
\&.fam N
\&.ps 9p
\&.vs 12p
.
.s
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 helper macros for this purpose by default.
The user is recommended to use troff's
.c ne
request:
.l
\&.l
\&.ne 3
int
main(int argc, char *argv[])
{
.p
The request
.c ne\ 3
tells troff that it needs three lines of vertical space.
If it finds that there is not enough space on the current page,
it will issue a page break.
While this is not a
.i general
solution to the problem,
as you need to manually count how many lines are needed,
troff itself is not a general solution to the problem of typesetting;
in fact, such a solution likely does not exist.
At the end of the day, all good typesetting requires manual care.
.
.s
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 _ec ,
copy environment (same as
.c evc )
.p
The
.c _e
can be used to activate any environment that supports
.i mg 's
extensions (see
.i Environments
above).