diff options
| -rw-r--r-- | example.pdf | bin | 81347 -> 82588 bytes | |||
| -rw-r--r-- | example.t | 110 | ||||
| -rw-r--r-- | g.tmac | 292 |
3 files changed, 224 insertions, 178 deletions
diff --git a/example.pdf b/example.pdf Binary files differindex 0fab32c..b69f26b 100644 --- a/example.pdf +++ b/example.pdf @@ -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 \&.. @@ -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 |