example.t: Start documenting internal macros

1 files changed, 61 insertions, 14 deletions

diff --git a/example.t b/example.t
index 84e65ec..d192f86 100644
--- a/example.t
+++ b/example.t
@@ -3,8 +3,9 @@
 . _e p
 .  nr sq \n(sp
 .  nr sp 0
-. _e
-.
+. _e l
+.  fam M
+.  vs +1p
 ._e e
 . _ec p
 . ta 3n +3n +3n +3n
@@ -49,8 +50,13 @@ 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 modify the source code
-according to their own needs.
+are encouraged to
+.e 0
+modify the source code
+according to their own needs, as well as
+.e
+use standard troff requests for some things
+that other packages provide custom macros for.
 .
 .h
 Environments
@@ -130,7 +136,21 @@ and does not support these registers.
 .
 .
 .h
-Macros
+Global variables
+.p
+Thanks to the reliance on environments,
+there are only two global variables
+controlling the state of
+.i mg :
+.e 0
+.c mt ,
+the margin at the beginning of the page
+.e
+.c mb ,
+the margin at the end of the page
+.
+.h
+External macros
 .
 .p
 .i Mg
@@ -139,9 +159,9 @@ Some of them are used internally by
 .i mg
 itself;
 these carry an underscore prefix
-and are not explained here.
-The rest provide useful features,
-like headings, subheadings and paragraphs.
+and are going to be explored later.
+For now, we will focus on the external macros provided by
+.i mg .
 .s
 Inline macros
 .p
@@ -224,9 +244,21 @@ By default,
 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.
+it starts an indented block quotation instead:
+.l
+.cc ,
+.q
+This is an indented quotation.
+.p
+This is an inline
+.q quotation .
+,cc
 .p
-The footnote macros are used like this\c
+The footnote macros
+.c (
+and
+.c )
+are used like this\c
 .(
 Note that
 .c (
@@ -239,17 +271,32 @@ the footnote number.
 .l
 .eo
 .cc ,
-a line of text\c
+.p
+A line of text\c
 .(
-a footnote
+A footnote.
 .) .
 ,cc
 .ec
 .p
-Note that
-.i mg
+.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 .
+The exception to this rule is
+.c _E ,
+.c _e
+and
+.c _ec ,
+which are a group of macros controlling the environment,
+as it may be desirable to define custom environments
+for advanced documents.