aboutsummaryrefslogtreecommitdiff
path: root/example.t
diff options
context:
space:
mode:
Diffstat (limited to 'example.t')
-rw-r--r--example.t169
1 files changed, 127 insertions, 42 deletions
diff --git a/example.t b/example.t
index 63db743..f9bda72 100644
--- a/example.t
+++ b/example.t
@@ -7,26 +7,26 @@
._e l
. fam M
. vs +1p
-._e e
+._e n
. _ec p
. ta 3n +3n +3n +3n
._e
.
. \" define macros
.eo
-.de e
+.de n
. if !'\$1'' \{\
-. nr ei \$1-1
-. af ei 0
-. if !'\$2'' .af ei \$2
-. ds e. .
-. if !'\$3'' .ds e. \$3
+. nr ni \$1-1
+. af ni 0
+. if !'\$2'' .af ni \$2
+. ds n. .
+. if !'\$3'' .ds n. \$3
. \}
-. nr ei +1
+. nr ni +1
. br
-. _e e
+. _e n
. ti \n(tiu
-\n(ei\*(e. \c
+\n(ni\*(n. \c
..
.ec
.
@@ -44,13 +44,13 @@ Introduction
.p
.i Mg
is a simple macro package for troff with the following features:
-.e 1
+.n 1
It is designed to be easy to understand and to customize
by editing the source code.
-.e
+.n
It makes use of the extended support for environments
offered by many modern troff implementations.
-.e
+.n
It is designed to be practically easy to use.
Macros are consistently one letter long and written in lowercase.
.p
@@ -63,10 +63,10 @@ written to serve the author's personal needs.
Users of
.i mg
are encouraged to
-.e 1 a )
+.n 1 a )
modify the source code
according to their own needs, as well as
-.e
+.n
use built-in troff requests for some things
that other packages might provide custom macros for.
.p
@@ -138,13 +138,13 @@ First paragraph.
In addition to the normal environment-relevant settings,
.i mg
manually associates a few special registers with the current environment:
-.e 1
+.n 1
.c sp ,
the amount of vertical space to add before an environment
-.e
+.n
.c sq ,
the amount of vertical space to add before a different type of environment
-.e
+.n
.c ti ,
the indentation of the first line in some environments
(currently only
@@ -152,25 +152,47 @@ the indentation of the first line in some environments
.p
These can be set inside a given environment
to control its behavior when invoked.
-The only exception is the footnote environment
-.c _f ), (
-which is treated specially
-and does not support these registers.
+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 variables
+Global settings
.p
Thanks to the reliance on environments,
-there are only two global variables
+there are only four global string values
controlling the state of
.i mg :
-.e 1
+.n 1
.c mt ,
the margin at the top of the page
-.e
+.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
@@ -195,16 +217,16 @@ 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:
-.e 1
+.n 1
.c b ,
bold font
-.e
+.n
.c c ,
constant-width font
-.e
+.n
.c i ,
italic font
-.e
+.n
.c i ,
bold italic font
.p
@@ -225,22 +247,22 @@ Block-level macros
.p
There is a large group of macros that provide
block-level formatting:
-.e 1
+.n 1
.c d ,
centered date (or given string)
-.e
+.n
.c h ,
heading
-.e
+.n
.c l ,
literal display (for source code)
-.e
+.n
.c p ,
paragraph
-.e
+.n
.c s ,
subheading
-.e
+.n
.c t ,
centered title of document
.
@@ -249,13 +271,13 @@ Other macros
.p
Finally, there are a few macros
that belong to neither category.
-.e 1
+.n 1
.c q ,
quotation
-.e
+.n
.c ( ,
begin footnote
-.e
+.n
.c ) ,
end footnote
.p
@@ -290,6 +312,7 @@ the footnote number.
\&.p
A line of text\\c
\&.(
+.ne 2
A footnote.
\&.) .
.p
@@ -307,12 +330,12 @@ Internal macros
.i Mg 's
internal macros are generally not meant to be used outside of
.i g.tmac .
-The exception to this rule is
.c _E ,
.c _e
and
.c _ec ,
-which are a group of macros controlling the environment,
+a group of macros controlling the environment,
+are excepted from this rule,
as it may be desirable to define custom environments
for advanced documents.
.
@@ -321,7 +344,7 @@ for advanced documents.
Frequently anticipated questions
.
.s
-How do I set the default font family, point size, indentation etc.
+How do I set the default font family, point size, indentation
of a document?
.p
All environment settings\c
@@ -354,3 +377,65 @@ you would start the document like this:
\&.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).