example.t: Rename e to n

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