Organize and document source code

2 files changed, 111 insertions, 33 deletions

diff --git a/example.t b/example.t
index 1ea01b1..bee06da 100644
--- a/example.t
+++ b/example.t
@@ -13,14 +13,16 @@ Introduction
 .i Mg
 is a simple macro package for troff with the following features:
 .p
-1.	It is designed to be easy to understand and to customize
+1.	\c
+It is designed to be easy to understand and to customize
 by editing the source code.
 .p
-2.	It makes use of the extended support for environments
-offered by many modern troff implementations
-(but it can be made compatible with the original troff if need be).
+2.	\c
+It makes use of the extended support for environments
+offered by many modern troff implementations.
 .p
-3.	It is designed to be practically easy to use.
+3.	\c
+It is designed to be practically easy to use.
 Macros are consistently one letter long and written in lowercase.
 .p
 While
@@ -53,7 +55,7 @@ If the user wishes to modify the default font size,
 he or she can simply switch to the
 .i p
 environment and set the font size as desired:
-.c
+.l
 .eo
 .cc ,
 .\" set heading font
@@ -76,7 +78,7 @@ are applied to all
 environments.
 It is thus remarkably simple and intuitive to set,
 for example, the default font of a document:
-.c
+.l
 .cc ,
 .fam N
 .t
@@ -85,4 +87,14 @@ Document title
 First paragraph.
 ,cc
 .p
-\&...
+In addition to the normal environment-relevant settings,
+.i mg
+manually associates a few special registers with the current environment:
+.p
+1.	\c
+.c sp ,
+the amount of vertical space to add before environment.
+.p
+2.	\c
+.c ti ,
+the indentation of the first line in the environment.
diff --git a/g.tmac b/g.tmac
index d995c03..3b5bbd6 100644
--- a/g.tmac
+++ b/g.tmac
@@ -1,44 +1,53 @@
-.eo
-.\" s -- setup document
+.eo \" disable backslash escapes
+.
+.\" Internal macros
+.\" ---------------
+.
+.\" _s -- setup document
 .de _s
+.
 . \" configure initial options
-. _nr mt 1i	\" margin top
-. _nr mb 1i	\" margin bottom
+. _nr mt 1i \" margin top
+. _nr mb 1i \" margin bottom
+. _ds cfam C \" inline constant-width font family
+. _ds cps -1p \" inline constant-width font size
+.
 . \" initialize document
 . wh 0 _h
 . wh -\n(mbu _f
-. sp 1u		\" trigger header
+. sp 1u \" trigger header
 . ns
+.
 . \" configure environments
-. _e t		\" title
+. t \" title
 .  evc 0
 .  ps +4p
 .  vs +2p
 .  ft B
 .  ad c
-. _e n		\" name (of author)
+. n \" name (of author)
 .  evc 0
 .  nr sp 0.4v
 .  ad c
-. _e d		\" date
+. d \" date
 .  evc 0
 .  nr sp 0.4v
 .  ad c
-. _e h		\" heading
+. h \" heading
 .  evc 0
 .  nr sp 0.6v
 .  ps +1p
 .  ft B
-. _e s		\" section heading
+. s \" section heading
 .  evc 0
 .  nr sp 0.6v
 .  ft B
-. _e p		\" paragraph
+. p \" paragraph
 .  evc 0
 .  nr sp 0.3v
 .  nr ti 0.5c
 .  ad b
-. _e c		\" code listing
+. l \" literal display
 .  evc 0
 .  nr sp 0.3v
 .  nr in 0.5c
@@ -48,35 +57,53 @@
 .  ps -1p
 . _e
 ..
+.
 .\" _h -- page header
 .de _h
 ' sp \n(mtu
 ..
+.
 .\" _f -- page footer
 .de _f
 ' sp 1v
 . tl ''%''
 ' bp
 ..
-.\" _nr -- set default value
+.
+.\" _nr -- set default numeric value
 .de _nr
 . if \n[\$1]=0 .nr \$1 \$2
 ..
+.
+.\" _ds -- set default string value
+.de _ds
+. if '\*[\$1]'' .ds \$1 \$2
+..
+.
 .\" _e -- set environment
 .de _e
+.
+. \" initialize document?
 . if '\n(_s'0' \{\
 .  nr _s 1
 .  _s
 . \}
+.
 . br
+.
+. \" save special environment variables
 . if !'\n[.ev]'0' \{\
 .  nr \n[.ev]_sp \n(sp
 .  nr \n[.ev]_in \n(in
 .  nr \n[.ev]_ti \n(ti
 .  ev
 . \}
+.
+. \" keep track of previous and new environment
 . ds penv \*[env]
 . ds env \$1
+.
+. \" activate new environment
 . if !'\$1'' \{\
 .  ev \$1
 .  nr sp \n[\n[.ev]_sp]
@@ -85,41 +112,75 @@
 .  sp \n(spu
 .  in \n(inu
 . \}
-. _mb
-..
-.\" _mb -- margin bottom
-.de _mb
-. ie '\*[env]'n' .return
-. el .if '\*[env]'d' .return
+.
+. \" perform post-environment operations
+. _pe
+..
+.
+.\" _pe -- post-environment operations
+.de _pe
+.
+. \" add small space after title
+. if '\*[penv]'t' \{\
+.  if '\*[env]'n' .sp 0.1v
+.  if '\*[env]'d' .sp 0.1v
+. \}
+.
+. \" add space after title/name/date
+. if '\*[env]'n' .return
+. if '\*[env]'d' .return
 . ie '\*[penv]'t' .sp 1v
 . el .ie '\*[penv]'n' .sp 1v
 . el .if '\*[penv]'d' .sp 1v
 ..
+.
+.
+.\" Inline macros
+.\" -------------
+.
 .\" i -- italic
 .de i
 \$3\fI\$1\fP\$2
 ..
+.
 .\" x -- bold italic
 .de x
 \$3\f(BI\$1\fP\$2
 ..
+.
+.\" c -- constant-width
+.de c
+\$3\c
+. fam \*[cfam]
+. ps \*[cps]
+\$1\c
+. fam
+. ps
+\$2
+..
+.
 .\" q -- quote
 .de q
 \$3\(lq\$1\(rq\$2
 ..
+.
+.
+.\" Environment macros
+.\" ------------------
+.
 .\" t -- title
 .de t
 . _e t
 ..
+.
 .\" n -- name (of author)
 .de n
 . _e n
-. if '\*[penv]'t' .sp 0.2v
 ..
+.
 .\" d -- date
 .de d
 . _e d
-. if '\*[penv]'t' .sp 0.2v
 . af mo 00
 . af dy 00
 . ie '\$1'' \n[year]-\n(mo-\n(dy
@@ -127,21 +188,26 @@
 . af mo 1
 . af dy 1
 ..
+.
 .\" h -- heading
 .de h
 . _e h
+.
 ..
 .\" s -- section heading
 .de s
 . _e s
+.
 ..
 .\" p -- paragraph
 .de p
 . _e p
 . if '\*[penv]'p' .ti \n(tiu
 ..
-.\" c -- code listing
-.de c
-. _e c
+.
+.\" l -- literal display
+.de l
+. _e l
 ..
-.ec
+.
+.ec \" re-enable backslash escapes