Change macro/register naming scheme

3 files changed, 224 insertions, 178 deletions

diff --git a/example.pdf b/example.pdf
index 0fab32c..b69f26b 100644
--- a/example.pdf
+++ b/example.pdf
diff --git a/example.t b/example.t
index 29f0452..78a3879 100644
--- a/example.t
+++ b/example.t
@@ -1,16 +1,16 @@
 .so g.tmac
 .
 . \" configure environments
-._e p
+.@e p
 . nr sq \n(sp
 . nr sp 0
-._e l
+.@e l
 . fam M
 . vs +1p
-._e n
-. _ec p
+.@e n
+. @c p
 . ta 3n +3n +3n +3n
-._e
+.@e
 .
 . \" define macros
 .eo
@@ -24,7 +24,7 @@
 . \}
 . nr ni +1
 . br
-. _e n
+. @e n
 . ti \n(tiu
 \n(ni\*(n.	\c
 ..
@@ -154,8 +154,8 @@ the indentation of the first line in some environments
 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 ),
+.c @m , (
+.c @f ),
 which are treated specially
 and do not support these registers.
 .
@@ -204,7 +204,9 @@ defines a number of macros.
 Some of them are used internally by
 .i mg
 itself;
-these carry an underscore prefix
+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 .
@@ -377,14 +379,40 @@ Internal macros
 .i Mg 's
 internal macros are generally not meant to be used outside of
 .i g.tmac .
-.c _E ,
-.c _e
+The group of macros controlling the environment \(en
+.c (e ,
+.c @e
 and
-.c _ec ,
-a group of macros controlling the environment,
-are excepted from this rule,
+.c @c
+\(en are excepted from this rule,
 as it may be desirable to define custom environments
 for advanced documents.
+.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.
+.c @e
+and
+.c @c
+are equivalent to troff's
+.c ev
+and
+.c evc ,
+but keep track of a few extra variables (see
+.i Environments
+above).
+.p
+For examples of how
+.c (e ,
+.c @e
+and
+.c @c
+are used in practice,
+see the FAQ section below.
 .
 .
 .h
@@ -437,24 +465,24 @@ you can switch to that environment and use the relevant troff requests:
 If you are merely configuring the environment
 without printing anything in it,
 you can also use the
-.c _e
+.c @e
 macro:
 .l
-\&._e q
+\&.@e q
 \&.ps +1p
 .
 .w s ll
 .s
 How do I customize the default appearance of the margin text?
 .l
-\&._E _m \\" margin environment
+\&.(e @m \\" margin environment
 \&.ps +1p
 .
 .w s ll
 .s
 How do I customize the default appearance of footnotes?
 .l
-\&._E _f \\" footnote environment
+\&.(e @f \\" footnote environment
 \&.ps +1p
 .
 .s
@@ -464,24 +492,34 @@ 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
+does not define any such macros by default.
+The simplest way to achieve the same is to use troff's
 .c ne
 request:
 .l
-\&.q
-\&.ne 7
-Four score and seven years ago...
+\&.ne 7 \\" break page if seven lines won't fit on this page
+\&.\\" ... some text ...
 .p
-In some cases,
+If you want to keep text of various styles together,
+you can use
 .i mg 's
 own
 .c w
-macro may be useful:
+macro:
 .l
-\&.w qqqqqqq
-\&.q
-Four score and seven years ago...
+\&.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
+..
 .
 .s
 How do I define my own environments?
@@ -495,19 +533,19 @@ extends environments with additional functionality,
 it provides special macros to be used instead of
 .c ev :
 .n 1
-.c _E ,
+.c (e ,
 set environment (same as
 .c ev )
 .n
-.c _e ,
+.c @e ,
 set extended environment
 .n
-.c _ec ,
+.c @c ,
 copy environment (same as
 .c evc )
 .p
 The
-.c _e
+.c @e
 macro
 can be used to activate any environment that supports
 .i mg 's
@@ -518,12 +556,12 @@ The following code configures an environment called
 .c n
 and defines a corresponding macro:
 .l
-\&._e n
-\&. _ec 0 \\" copy default environment
+\&.@e n
+\&. @c 0 \\" copy default environment
 \&. ps -1p
-\&._e
+\&.@e
 \&.
 \&.de n
 \&. br \\" finish current environment
-\&. _e n \\" activate new environment
+\&. @e n \\" activate new environment
 \&..
diff --git a/g.tmac b/g.tmac
index 7c5760e..f1cc374 100644
--- a/g.tmac
+++ b/g.tmac
@@ -9,204 +9,209 @@
 .\" For an index of the macros defined in    "/.
 .\" this file, issue `grep -n [-]- g.tmac'.  "/.
 .\"                                          "/.
-.\" Place new macros in alphabetical order.  "/.
+.\" When editing the source of mg, keep the  "/.
+.\" following rules in mind:                 "/.
 .\"                                          "/.
-.\" Do not use .ev and .evc outside wrapper  "/.
-.\" macros like _e and _ec.                  "/.
+.\" * Prefix temporary registers with _.     "/.
+.\" * Prefix temporary strings with _.       "/.
+.\" * Prefix internal environments with @.   "/.
+.\" * Prefix internal registers with @.      "/.
+.\" * Prefix internal macros with @ (normal  "/.
+.\" macros), * (variants of the same macro)  "/.
+.\" or % (strings).                          "/.
+.\" * Place macros in alphabetical order.    "/.
+.\" * Do not use .ev and .evc outside of     "/.
+.\" wrapper macros like (e, @e and @c.  "/.
 .\"                                          "/.
 .
 .eo \" disable backslash escapes
 .
 .\" Internal macros ----------------------------
 .
-.\" _a -- setup document
-.de _a
+.\" @a -- setup document
+.de @a
 .
 . \" configure initial options
-. _nr mt 1i \" top margin
-. _nr mb 1i \" bottom margin
-. _ds tt '''' \" text in top margin
-. _ds tb ''%'' \" text in bottom margin
+. @nr mt 1i \" top margin
+. @nr mb 1i \" bottom margin
+. @ds tt '''' \" text in top margin
+. @ds tb ''%'' \" text in bottom margin
 .
 . \" initialize document
-. wh 0 _th
-. wh -\n(mbu _tf
+. wh 0 @th
+. wh -\n(mbu @tf
 . sp 1u \" trigger header
 .
 . \" configure environments
-. _e d \" date
-.  _ec 0
+. @e d \" date
+.  @c 0
 .  nr sp 0.4v
 .  ad c
-. _e h \" heading
-.  _ec 0
+. @e h \" heading
+.  @c 0
 .  nr sp 1.2v
 .  ps +1p
 .  ft B
-. _e l \" literal display
-.  _ec 0
+. @e l \" literal display
+.  @c 0
 .  nr sp 0.3v
 .  nf
 .  in 18p
 .  fam C
 .  ps -1p
 .  vs -1p
-. _e n \" name (of author)
-.  _ec 0
+. @e n \" name (of author)
+.  @c 0
 .  nr sp 0.4v
 .  ad c
-. _e p \" paragraph
-.  _ec 0
+. @e p \" paragraph
+.  @c 0
 .  nr sp 0.3v
 .  nr ti 18p
 .  ad b
-. _e q \" quotation
-.  _ec 0
+. @e q \" quotation
+.  @c 0
 .  nr sp 0.3v
 .  nr ti 1c
 .  in 18p
 .  ps -1p
 .  vs -1p
-. _e s \" section heading
-.  _ec 0
+. @e s \" section heading
+.  @c 0
 .  nr sp 1v
 .  ft B
-. _e t \" title
-.  _ec 0
+. @e t \" title
+.  @c 0
 .  ps +4p
 .  vs +2p
 .  ft B
 .  ad c
-. _e
+. @e
 .
 . \" configure special environments
-. _E _f \" footnote
-.  _ec 0
+. (e @f \" footnote
+.  @c 0
 .  ps -2p
 .  vs -1p
-. _E _m \" margins (header, footer)
-.  _ec 0
-. _E
+. (e @m \" margins (header, footer)
+.  @c 0
+. (e
 ..
 .
-.\" _ds -- set default string value
-.de _ds
+. \" @c -- copy environment
+.de @c
+. evc \$1
+. nr sp \n[@\$1_sp]
+. nr sq \n[@\$1_sq]
+. nr ti \n[@\$1_ti]
+..
+.
+.\" @ds -- set default string value
+.de @ds
 . if '\*[\$1]'' .ds \$1 \$2
 ..
 .
-.\" _E -- just set environment
-.de _E
+.\" (e -- set environment
+.de (e
 . ev \$1
 ..
 .
-.\" _e -- set environment
-.de _e
+.\" @e -- set extended environment
+.de @e
 .
-. \" initialize document?
-. if '\n(_a'0' \{\
-.  nr _a 1
-.  _a
+. \" initialize document if not initialized
+. if '\n(@a'0' \{\
+.  nr @a 1
+.  @a
 . \}
 .
 . \" save special environment variables
 . if !'\n[.ev]'0' \{\
-.  nr \n[.ev]_sp \n(sp \" vertical space before any environment
-.  nr \n[.ev]_sq \n(sq \" vertical space before different environment
-.  nr \n[.ev]_ti \n(ti \" first line indentation
+.  nr @\n[.ev]_sp \n(sp \" vertical space before any environment
+.  nr @\n[.ev]_sq \n(sq \" vertical space before different environment
+.  nr @\n[.ev]_ti \n(ti \" first line indentation
 .  ev
 . \}
 .
 . \" keep track of previous and new environment
-. ds _penv \*[_env]
-. ds _env \$1
+. ds %penv \*[%env]
+. ds %env \$1
 .
 . \" post-environment operations
 . if !'\$1'' \{\
 .  \" add small space after title
-.  if '\*[_penv]'t' .if '\*[_env]'d' .sp 0.1v
-.
-.  \" add space after title block (including date)
-.  if !'\*[_env]'n' .if !'\*[_env]'d' \{\
-.   nr _tb 0
-.   ie '\*[_penv]'t' .nr _tb 1
-.   el .if '\*[_penv]'d' .nr _tb 1
-.   if \n[_tb]==1 \{\
-.    sp 0.5i
-.    ns
-.   \}
+.  if '\*[%penv]'t' .if '\*[%env]'d' .sp 0.1v
+.
+.  \" add space after title block
+.  nr _ 0
+.  if !'\*[%env]'d' .nr _ 1
+.  if !'\*[%penv]'t' .if !'\*[%penv]'d' .nr _ 0
+.  if \n_ \{\
+.   sp 0.5i
+.   ns
 .  \}
-. \}
 .
-. \" activate new environment
-. if !'\$1'' \{\
+.  \" activate new environment
 .  ev \$1
-.  nr sp \n[\n[.ev]_sp]
-.  nr sq \n[\n[.ev]_sq]
-.  nr ti \n[\n[.ev]_ti]
+.  nr sp \n[@\n[.ev]_sp]
+.  nr sq \n[@\n[.ev]_sq]
+.  nr ti \n[@\n[.ev]_ti]
 .  sp \n(spu
-.  if !'\*[_env]'\*[_penv]' .sp \n(squ
+.  if !'\*[%env]'\*[%penv]' .sp \n(squ
 . \}
 ..
 .
-. \" _ec -- copy environment
-.de _ec
-. evc \$1
-. nr sp \n[\$1_sp]
-. nr sq \n[\$1_sq]
-. nr ti \n[\$1_ti]
-..
-.
-.\" _nr -- set default numeric value
-.de _nr
+.\" @nr -- set default numeric value
+.de @nr
 . if \n[\$1]=0 .nr \$1 \$2
 ..
 .
-.\" _tf -- footer trap
-.de _tf
+.\" @tf -- footer trap
+.de @tf
 .
 . \" print footer
-. _E _m
-. rt \n(.pu-\n(mbu \" return to correct position?
+. (e @m
+. rt \n(.pu-\n(mbu \" return to correct position if pushed down
 . sp \n(mbu-2v-24p
 . tl \*(tb
 ' bp
 ..
 .
-.\" _th -- header trap
-.de _th
-. _E _m
+.\" @th -- header trap
+.de @th
+. (e @m
 . rt 0
 . sp 24p
 . tl \*(tt
 . rt 0
 . sp \n(mtu
-. _E \*[_env]
+. (e \*[%env]
 . ns
 ..
 .
-.\" _tn -- footnote trap
-.de _tn
+.\" @tn -- footnote trap
+.de @tn
 .
 . \" override footer
-. ch _tf
+. ch @tf
 .
 . \" print collected footnotes
-. _E _m
+. (e @m
 ___________________
 . br
 . sp 1p
-. _E _f
-. _n
+. (e @f
+. @n
 . br
 .
 . \" clear footnotes
-. ch _tn
-. nr _dn 0
-. rm _n
+. ch @tn
+. nr @dn 0
+. rm @n
 .
 . \" trigger and restore footer
-. _tf
-. wh -\n(mbu _tf
+. @tf
+. wh -\n(mbu @tf
 ..
 .
 .
@@ -220,24 +225,26 @@ ___________________
 .\" c -- constant-width font
 .de c
 .
+. \" save original interword spacing
+. nr _ss \n[.ss]
+.
 . \" copy family and (relative) point size from l environment
-. _E 0
-. nr _S \n(.s
-. _E
-. _E l
-. ds _fam \n[.fam]
-. nr _s \n(.s
-. _E
+. (e 0
+. nr _s0 \n(.s
+. (e
+. (e l
+. ds _fl \n[.fam]
+. nr _sl \n(.s
+. (e
 .
 \&\$3\c
-. fam \*[_fam]
-. ps +(\n(_s-\n(_S)u
-. nr _s \n[.ss]
+. fam \*[_fl]
+. ps +(\n[_sl]-\n[_s0])u
 . ss 7
 \&\$1\c
 . fam
 . ps
-. ss \n(_s
+. ss \n[_ss]
 \&\$2
 ..
 .
@@ -263,7 +270,7 @@ ___________________
 . \" block
 . el \{\
 .  br
-.  _e q
+.  @e q
 .  ti \n(tiu
 . \}
 ..
@@ -275,7 +282,7 @@ ___________________
 .\" d -- date
 .de d
 . br
-. _e d
+. @e d
 . af mo 00
 . af dy 00
 . ie '\$1'' \n[year]-\n(mo-\n(dy
@@ -287,33 +294,33 @@ ___________________
 .de h
 . br
 . w h p
-. _e h
+. @e h
 .
 ..
 .\" l -- literal display
 .de l
 . br
-. _e l
+. @e l
 ..
 .
 .\" p -- paragraph
 .de p
 . br
-. _e p
-. if '\*[_penv]'p' .ti \n(tiu
+. @e p
+. if '\*[%penv]'p' .ti \n(tiu
 ..
 .
 .\" s -- subheading
 .de s
 . br
 . w s p
-. _e s
+. @e s
 ..
 .
 .\" t -- title
 .de t
 . br
-. _e t
+. @e t
 ..
 .
 .
@@ -324,14 +331,14 @@ ___________________
 . if !'\$1'' \&\$1\c
 .
 . \" increment and print number
-. nr _n \n(_n+1
-\v'-.3m'\s'\En(.s*80/100'\n(_n\s0\v'.3m'\c
+. nr @n \n(@n+1
+\v'-.3m'\s'\En(.s*80/100'\n(@n\s0\v'.3m'\c
 .
 . \" switch environment and capture footnote
-. _E _f
+. (e @f
 . ti 9p
-. boxa _n
-\v'-.3m'\s'\En(.s*80/100'\n(_n\s0\v'.3m'\h'2p'\c
+. boxa @n
+\v'-.3m'\s'\En(.s*80/100'\n(@n\s0\v'.3m'\h'2p'\c
 ..
 .
 .\" ) -- end footnote
@@ -339,14 +346,14 @@ ___________________
 . br
 \!.br
 . boxa
-. _E \*[_env]
+. (e \*[%env]
 . ie !'\$1'' \&\$1
 . el \&
 .
 . \" print footnote at bottom of page
-. ch _tn
-. nr _dn +\n(dnu
-. if !'\n(dn'0' .wh -\n[_dn]u-\n(mbu-12p _tn
+. ch @tn
+. nr @dn +\n(dnu
+. if !'\n(dn'0' .wh -\n[@dn]u-\n(mbu-12p @tn
 ..
 .
 . \" w -- want space
@@ -354,32 +361,33 @@ ___________________
 . *w 0 \$@
 ..
 .de *w
-. nr s \$1 \" accumulated space
-. length n \$2 \" number of lines in environment
-. ds __e \$2 \" environment
-. nr n -1
-. substring __e 0 0
-.
-. \" add environment sp/sq
-. nr s +\n[\*[__e]_sp]
-. nr s +\n[\*[__e]_sq]
-.
-. \" add environment vs
-. _E \*[__e]
+.
+. \" parse specification -> _s : accumulated space
+. nr _s \$1              \" _e : environment name (e.g. eee -> e)
+. ds _e \$2              \" _n : number of lines specified (e.g. eee -> 3)
+. substring _e 0 0
+. length _n \$2
+.
+. \" add environment spacing
+. nr _s +\n[@\*(_e_sp]
+. nr _s +\n[@\*(_e_sq]
+.
+. \" add environment line height (for each line)
+. (e \*(_e
 . nr _v \n(.v
-. _E
-. nr s +(\nn*\n(_v)
+. (e
+. nr _s +(\n(_n*\n(_v)
 . shift 2
 .
-. \" request space or recurse
-. ie \n(.$=0 \{\
-.  nr S \ns-\n(_v+1u \" do not request too much
-.  if (\nSu)>\n(.tu \{\
+. \" recurse or request space if done
+. ie \n(.$>0 .*w \n(_s \$@
+. el \{\
+.  nr _s \n(_s-\n(_v+1u \" do not request too much
+.  if (\n(_su)>\n(.tu \{\
 .   br
 .   bp
 .  \}
 . \}
-. el .*w \ns \$@
 ..
 .
 .ec \" re-enable backslash escapes