diff options
Diffstat (limited to 'README.t')
| -rw-r--r-- | README.t | 786 |
1 files changed, 786 insertions, 0 deletions
diff --git a/README.t b/README.t new file mode 100644 index 0000000..7e6e6f9 --- /dev/null +++ b/README.t @@ -0,0 +1,786 @@ +.so g.tmac +.so toc/toc.tmac +. +.\" configure header and footer +.eo +.de @h +. sp |36p +. if \n%>1 .tl ''-%-'' +. sp |1i +.. +. +.de @f +. sp |\n(.pu-48p +. tl ''\*(#e'' +.. +.ec +. +.\" define macros +.eo +.de he +. h +\$* +. te .the \n% \$* +.. +. +.de se +. s +\$* +. te .the \n% \\h'18p'\$* +.. +. +.de the +. nr _ \$1 +. shift +. ta 0 \n(.luR +. tc . +\$* \n_ +. tc +. br +.. +. +.de n +. if !'\$1'' \{\ +. nr ni \$1-1 +. af ni 0 +. if !'\$2'' .af ni \$2 +. ds n. . +. if !'\$3'' .ds n. \$3 +. \} +. nr ni +1 +. br +. @e n +. ti \n(tiu +\n(ni\*(n. \c +.. +.ec +. +.\" configure environments +.@e l +. fam M +. vs +1p +.@e n +. @c p +. nr sq \n(sp +. nr sp 0 +. ta 3n +3n +3n +3n +.@e +. +.\" start document +.t +.x Mg , +a simple macro package for troff +.d +John Ankarstr\(:om +.d e +. +.s +.ft I +.tl ''TABLE OF CONTENTS'' +.ft +.sp 4p +.@e +.to +.sp 0.5i +.ns +. +.he Introduction +.p +.i Mg +is a simple macro package for troff with the following features: +.n 1 +It is designed to be easy to understand and to customize +by editing the source code. +.n +It makes use of the extended support for environments +offered by many modern troff implementations. +.n +It is designed to be practically easy to use. +Macros are consistently one letter long and written in lowercase. +.p +While +.i mg +does provide macros for many common tasks, +including footnotes, +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 +.n 1 a ) +modify the source code +according to their own needs, as well as +.n +use built-in troff requests for some things +that other packages might provide custom macros for. +.p +All in all, +.i mg +aspires to abstract as little as possible +from the underlying troff requests and registers. +In its author's humble opinion, +it is the ideal macro package for learning troff. +.p +In this document, the fundamental concepts of +.i mg +are explained. +The document itself also serves as a demonstration of +.i mg . +With a couple of exceptions, it uses +.i mg 's +default settings. +The reader is encouraged to inspect the document's source code +in order to see how the macro package is used in practice. +. +. +.he Environments +.te .nr &env \n% +.p +.i Mg +makes heavy use of named environments, +supported by implementations such as GNU troff and Neatroff. +Environments obliviate the need for many special registers +that a macro package (and its user) would otherwise need to keep track of. +For example, +.i ms +keeps track of the document's font size in the +.c PS +register. +For the font size of headings, +it has yet another register. +.i Mg +has no such registers. +If the user wishes to modify the default font size, +he or she can simply switch to the relevant environment +and set the font size as desired +using regular troff requests: +.l +\&.\\" set heading font +\&.h +\&.fam H +\&.ps +1p +.p +Troff saves the font settings in the environment, +so that the next time the environment is invoked, +the desired font family and point size are automatically restored. +.p +The environments are initialized +as soon as the first +.q block-level +macro is called. +At the initialization of each environment, +the default environment (0) is copied, +meaning that all environment-relevant settings +defined before the first macro call +are applied to all +.i mg +environments. +It is thus remarkably simple and intuitive to set, +for example, the default font of a document: +.l +\&.fam N +\&.t +Document title +\&.p +First paragraph. +.p +In addition to the normal environment-relevant settings, +.i mg +manually associates a few special registers with the current environment: +.n 1 +.c sp , +the amount of vertical space to add before an environment +.n +.c sq , +the amount of vertical space to add before a different type of environment +.n +.c ti , +the indentation of the first line in some environments +(currently only +.c p ) +.p +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 ), +which are treated specially +and do not support these registers. +. +. +.he External macros +.p +.i Mg +defines a number of macros. +Some of them are used internally by +.i mg +itself; +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 . +.se Inline macros +.p +There is a group of macros that provide +convenient inline formatting. +All take three arguments: +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: +.n 1 +.c b , +bold font +.n +.c c , +constant-width font +.n +.c i , +italic font +.n +.c i , +bold italic font +.p +For example, the following request outputs +.i mg .\(rq: \(lq +.l +\&.i mg . +. +.p +Note that +.c c +uses the font family and point size +set in the +.c l +environment (see below). +.se Block-level macros +.p +There is a large group of macros that provide +block-level formatting: +.n 1 +.c d , +centered date or text +.n +.c h , +heading +.n +.c l , +literal display (for source code) +.n +.c p , +paragraph +.n +.c s , +subheading +.n +.c t , +centered title +.p +The +.c t +and +.c d +macros can be used at the beginning of a document +to create a centered header: +.l +\&.t +Document title +\&.d +First author +\&.br +Second author +\&.d i \\" current date formatted as YYYY-MM-DD +.p +In the example above, you can see that the +.c d +macro may be used for other things than just dates. +This works because +.c d +displays the date only if given +an argument describing the desired date format: +.n 1 a ) +.c i : +international date, like +.q 2021-06-21 +.n +.c e : +English date, like +.q "21 June 2021" +.p +The formatted dates are defined in strings prefixed with a hash symbol +.c # ): ( +.c #i +and +.c #e +are provided by default, +but more may be added by the user. +. +.se Other macros +.p +Finally, there are a few macros +that belong to neither category: +.n 1 +.ne 2 +.c ( , +begin footnote +.n +.c ) , +end footnote +.n +.ne 2 +.c q , +quotation +.n +.c w , +want space +.p +The macros +.c ( +and +.c ) +create footnotes, +placing a numerical reference at the place of their invocation. +Both +.c ( +and +.c ) +take an optional argument, +which is output either immediately before or immediately after +the inline reference. +For example, the following code +.l +\&.q +This is a quotation\\c +\&.( +.ne 1 +This is a footnote. +\&.) . +.p +creates the following reference: +.q +This is a quotation\c +.( +This is a footnote. +.) . +.p +If +.c ( +and +.c ) +are called at such a position that the collected footnotes +cannot fit on the current page, +.i mg +will print the footnotes on the next page instead. +.p +The +.c q +behaves like an inline macro by default, +surrounding text in quotation marks, +but if no arguments are given to it, +it starts an indented block quotation instead: +.l +.ne 2 +\&.q +This is an indented quotation. +\&.p +This is an inline +\&.q quotation . +.p +The +.c w +macro is an alternative to troff's +.c ne +request, +which ensures that a given amount of space is available on the page +\(en otherwise, a line break is issued \(en +but unlike +.c ne , +which takes an exact amount of space as its argument, +.c w +takes a declarative specification +describing the amount of desired space +in terms of +.i mg +environments. +For example: +.l +\&.\\" want space for... +\&.w s p \\" a subheading of one line + a paragraph of one line +\&.w s pp \\" a subheading of one line + a paragraph of two lines +\&.w ss p \\" a subheading of two lines + a paragraph of one line +. +. +.he Internal macros +.p +.i Mg 's +internal macros are generally not meant to be used outside of +.i g.tmac . +Documented in this section are the exceptions to this rule. +For examples of how these macros are used in practice, +see the FAQ section on page \n[&faq]. +. +.se Page header and footer +.p +The +.c @h , +.c @f , +.c @th +and +.c @tf +macros control the page header and footer. +.p +At document initialization, +.i mg +automatically creates traps for +.c @th +and +.c @tf . +When sprung, +.c @th +and +.c @tf +call +.c @h +and +.c @t , +which control the text and spacing of the header and footer. +.p +.i Mg +will avoid creating a trap for +.c @tf +if any trap has already been set before document initialization. +This means that users can override the position of the +.c @tf +trap by setting it themselves. +Likewise, users can redefine +.c @h +and +.c @f +to change the content of the header and footer. +. +.se Environments +.p +The environment-related macros +.c (e , +.c @e +and +.c @c +may be used in advanced documents to define custom environments. +.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. +.p +.c @e +and +.c @c +are equivalent to troff's +.c ev +and +.c evc , +but perform some extra work to keep track of +.i mg 's +special environment variables +(see +.i Environments , +p. \n[&env]). +. +. +.he Frequently anticipated questions +.te .nr &faq \n% +. +.se How do I customize the default appearance of a document? +.p +All environment settings, +like point size, font family and indentation\c +.( +For a complete list of settings that are associated with the environment, +see 5.26\~\c +.i Environments +in the full GNU troff manual +.nh +.c "info '(groff.\:info)Environments'" ). ( +.hy +.) , +are configured with the standard troff requests. +If you set the point size at the beginning of the document, +before any +.i mg +macros have been called, +it will be correctly set for the entire document. +This works because +.i mg 's +environments initially copy all their settings from 0, +the default environment. +.p +For example, if you wanted to write a document +with the New Century Schoolbook font +at 9 points +and a vertical spacing of 12 points, +you would start the document like this +(before you call any +.i mg +macros): +.l +\&.fam N +\&.ps 9p +\&.vs 12p +. +.se How do I customize the default appearance of a given environment? +.p +To configure the layout and font settings of a specific environment, +you can switch to that environment and use the relevant troff requests: +.l +.ne 1 +\&.q +\&.ps +1p +.p +If you are merely configuring the environment +without printing anything in it, +you can also use the +.c @e +macro: +.l +\&.@e q +\&.ps +1p +. +.w s ll +.se How do I customize the default appearance of the margin text? +.l +\&.(e @m \\" margin environment +\&.ps +1p +.p +You can also set such settings in your redefinition of +.c @h +or +.c @f . +. +.w s ll +.se How do I customize the default appearance of footnotes? +.l +\&.(e @f \\" footnote environment +\&.ps +1p +. +.w s ll +.se How do I redefine the page header? +.l +\&.de @h +\&. \\" set position of header text +\&. sp |36p +\&. \\" set header text +\&. tl 'left'center'right' +\&. \\" set position of page text +\&. sp |1i +\&.. +. +.w s ll +.se How do I redefine the page footer? +.l +\&.\\" set position of footer trap +\&.\\" (must be done before any macros have been called) +\&.wh -1i @tf +\&. +\&.de @f +\&. \\" set position of footer text +\&. \\" (must be below the footer trap) +\&. sp |\\\\n(.pu-48p +\&. tl 'left'center'right' +\&.. +. +.se 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 such macros by default. +The simplest way to achieve the same is to use troff's +.c ne +request: +.l +\&.ne 7 \\" break page if seven lines won't fit on this page +\&.\\" ... some text ... +.p +If you want to keep text of various styles together, +you can use +.i mg 's +own +.c w +macro: +.l +\&.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 +.. +. +.se 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 @c , +copy environment (same as +.c evc ) +.p +The +.c @e +macro +can be used to activate any environment that supports +.i mg 's +extensions (see +.i Environments , +p. \n[&env]). +The following code configures an environment called +.c n +and defines a corresponding macro: +.l +\&.@e n +\&. @c 0 \\" copy default environment +\&. ps -1p +\&.@e +\&. +\&.de n +\&. br \\" finish current environment +.ne 1 +\&. @e n \\" activate new environment +\&.. +. +.se How do I include a table of contents in my document? +.p +Included with the +.i mg +distribution is a package called +.i toc , +which includes the following files: +.n 1 +.i toc.tmac , +which provides the +.c te +and +.c to +macros +.n +.i toc , +a script that invokes troff in three passes +in order to allow a table of contents to be generated +.n +.i gtoc , +an alias of +.i toc +that invokes groff instead of troff +.p +Use +.c te +to register a line to be inserted into the table of contents. +Use +.c to +to insert the table of contents. +Note that the argument given to +.c te +will be interpreted as a troff input line. +.p +The following definitions provide a good basis: +.l +\&.eo +\&.de he +\&. h +\\$* +\&. tm .the \\n% \\$* +\&.. +\&.de the +\&. nr _ \\$1 +\&. shift +\&. ta 0 \\n(.luR +\&. tc . +\\$* \\n_ +\&. tc +\&. br +\&.. +\&.ec +.p +Now, instead of +.c h , +you may use +.c he +to create a heading to be included in the table of contents: +.l +\&.he A heading +.p +Wherever you want the table of contents to be inserted, +you may simply invoke +.c to . +.p +Just remember to run +.c toc /\c +.c gtoc +instead of +.c troff /\c +.c groff : +.l +gtoc -Tps example.t > example.ps +.p +Thanks to the multiple passes performed by +.i toc , +.c to +can be invoked at any place in the document, +including the beginning. +The macros listed above are the ones used to generate +the table of contents of this document. +.p +Note that you can invoke a custom program instead of troff +by setting the +.i TROFF +environment variable. +This may be useful if you need to combine +.i toc +with certain troff post-pocessors. +. +.se How do I create a reference to a later page? +.p +Use the macros provided by +.i toc.tmac +in combination with the +.i toc +program. +Near the beginning of your document, invoke +.c to . +Then, at each position you want to reference, +invoke +.c .te +like this: +.l +\&.te .nr &refname \n% +.p +To refer to that position, interpolate the register: +.l +See page \\n[&refname]. +.p +(I prefer prefixing my references with an ampersand.) |