diff options
Diffstat (limited to '')
| -rw-r--r-- | contrib/mm/groff_mm.7.man | 5428 |
1 files changed, 5428 insertions, 0 deletions
diff --git a/contrib/mm/groff_mm.7.man b/contrib/mm/groff_mm.7.man new file mode 100644 index 0000000..4f94191 --- /dev/null +++ b/contrib/mm/groff_mm.7.man @@ -0,0 +1,5428 @@ +'\" t +.TH groff_mm @MAN7EXT@ "@MDATE@" "groff @VERSION@" +.SH Name +groff_mm \- memorandum macros for GNU +.I roff +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2023 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_mm_7_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY "groff \-m@TMAC_M_PREFIX@m" +.RI [ option\~ .\|.\|.\&] +.RI [ file\~ .\|.\|.] +. +.SY "groff \-m m@TMAC_M_PREFIX@m" +.RI [ option\~ .\|.\|.\&] +.RI [ file\~ .\|.\|.] +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The GNU implementation of the +.I mm +macro package is part of the +.I groff +document formatting system. +. +The +.I mm +package is suitable for the composition of +letters, +memoranda, +reports, +and books. +. +. +.P +Call an +.I mm +macro at the beginning of a document to initialize the package. +. +A simple +.I mm +document might use only +.B P +for paragraphing. +. +Set numbered and unnumbered section headings with +.B H +and +.BR HU , +respectively. +. +Change the style of the typeface with +.BR B , +.BR I , +and +.BR R ; +you can alternate styles with +.BR BI , +.BR BR , +.BR IB , +.BR IR , +.BR RB , +and +.BR RI . +. +Several nestable list types are available via +.BR AL , +.BR BL , +.BR BVL , +.BR DL , +.BR ML , +.BR RL , +and +.BR VL ; +each of these begins a list, +to which +.B LI +adds an item and +.B LE +ends the (nested) list. +. +Customized list arrangements are supported by +.BR LB . +. +.B DS +and +.B DF +start static and floating displays, +respectively; +either is terminated with +.BR DE . +. +. +.P +.I groff mm +is intended to be compatible with the +.I mm +implementation found in the AT&T Documenter's Workbench (DWB), +with the following limitations. +. +. +.IP \[bu] 2n +Omitted features include +the logo and company name strings, +.B }Z +and +.BR ]S , +respectively; +the encoded company site location addresses recognized as the third +argument to the +.B AU +macro; +the +.B Pv +(\[lq]private\[rq] heading) +register; +and the +.B OK +(other keywords), +and +.B PM +(proprietary markings) +macros. +. +. +.IP \[bu] 2n +The +.B CS +(output cover sheet) +macro is implemented only for memorandum type 4. +. +. +.IP \[bu] +The +.I grap +preprocessor is not explicitly supported; +no +.B G1 +and +.B G2 +macros +are defined. +. +. +.IP \[bu] +The registers +.BR A , +.BR C , +.BR E , +.BR T , +and +.BR U , +typically set from the +.I troff \" generic +or +.I nroff \" generic +command lines with DWB +.IR mm , +are not recognized. +. +. +.IP \[bu] +When setting the registers +.B L +or +.B W +from the command line, +use an explicit scaling unit to avoid surprises. +. +. +.IP \[bu] +DWB +.IR mm 's +.B nP +macro indented the second line of a paragraph to align it with the start +of the text of the first +(after the paragraph number); +.IR "groff mm" 's +does not. +. +. +.IP \[bu] +Cut marks are not supported. +. +. +.P +DWB +.I mm +supported only seven levels of heading. +. +As a compatible extension, +.I groff mm +supports fourteen, +introducing new registers +.B H8 +through +.BR H14 , +and affecting the interpretation of the +.B HF +and +.B HP +strings. +. +. +.P +Macro, +register, +and string descriptions in this page frequently mention each other; +most cross references are to macros. +. +Where a register or string is referenced, +its type is explicitly identified. +. +.IR mm 's +macro names are usually in full capitals; +registers and strings tend to have mixed-case names. +. +. +.\" ==================================================================== +.SS "Document styles" +.\" ==================================================================== +. +.I groff mm +offers three different frameworks for document organization. +. +.BR \%COVER /\: \%COVEND +is a flexible means of preparing any document requiring a cover page. +. +.BR LT / LO +aids preparation of typical Anglophone correspondence +(business letters, +for example). +. +The +.B MT +memorandum type mechanism implements a group of formal styles +historically used by AT&T Bell Laboratories. +. +Your document can select at most one of these approaches; +when used, +each disables the others. +. +. +.\" ==================================================================== +.SS Localization +.\" ==================================================================== +. +.I groff mm +is designed to be easily localized. +. +For languages other than English, +strings that can appear in output are collected in the file +.IR @MACRODIR@/\: xx \:.tmac , +where +.I xx +is an ISO\~639 two-letter language identifier. +. +Localization packages should be loaded after +.IR mm ; +for example, +you might format a Swedish +.I mm +document with the command +.RB \[lq] "groff \-mm \-msv" \[rq]. +. +. +.P +This package can also be localized by site or territory; +for example, +.I @MACRODIR@/\:@TMAC_M_PREFIX@mse\:.tmac +illustrates how to adapt the output to a national standard using its ISO +3166 territory code. +. +Such a package can define a string that causes a macro file +.IR @MACRODIR@/\:mm/\:\% territory _locale +to be loaded at package initialization. +. +If this mechanism is not used, +.I @MACRODIR@/\:mm/\:\%locale +is loaded instead. +. +No diagnostic is produced if these files do not exist. +. +. +.\" ==================================================================== +.SS "Registers and strings" +.\" ==================================================================== +. +Much +.I mm +behavior can be configured by registers and strings. +. +A register is assigned with the +.B nr +request. +. +. +.RS +.P +.B .nr +.I ident +.RB [ \[+-] ]\c +.I n +.RI [ i ] +.RE +. +. +.P +.I ident +is the name of the register, +and +.IR n \~is +the value to be assigned. +. +.IR n \~can +be prefixed with a plus or minus sign if incrementation or +decrementation (respectively) of the register's existing value +.RI by\~ n +is desired. +. +If assignment of a (possibly) negative +.IR n \~is +required, +further prefix it with a zero or enclose it in parentheses. +. +If +.IR i \~is +specified, +the register is automatically modified +.RI by \~i +prior to interpolation if a plus or minus sign is included in the escape +sequence as follows. +. +. +.RS +.P +.B \[rs]n\c +.RB [ \[+-] ]\c +.BI [ ident ] +.RE +. +. +.P +.IR i \~can +be negative; +it combines algebraically with the sign in the interpolation escape +sequence. +. +. +.P +Strings are defined with the +.B ds +request. +. +. +.RS +.P +.B .ds +.I ident contents +.RE +. +. +.P +.I contents +consumes everything up to the end of the line, +including trailing spaces. +. +It is a good practice to end +.I contents +with a comment escape sequence +.RB ( \[rs]\[dq] ) +so that extraneous spaces do not intrude during document maintenance. +. +To include leading spaces in +.IR contents , +prefix it with a double quote. +. +Strings are interpolated with the +.B \[rs]* +escape sequence. +. +. +.RS +.P +.B \[rs]*\c +.BI [ ident ] +.RE +. +. +.P +Register and string name spaces are distinct, +but strings and macros share a name space. +. +Defining a string with the same name as an +.I mm +macro is not supported and may cause incorrect rendering, +the emission of diagnostic messages, +and an error exit status from +.IR @g@troff . +. +. +.\" ==================================================================== +.SS "Register format" +.\" ==================================================================== +. +A register is interpolated using Arabic numerals if no other format has +been assigned to it. +. +Assign a format to a register with the +.B af +request. +. +. +.RS +.LP +.BI .af\~ "R c" +.RE +. +. +.LP +.IR R \~is +the name of the register, +and +.IR c \~is +the format. +. +If +.IR c \~is +a sequence of Arabic numerals, +their quantity defines a zero-padded minimum width for the interpolated +register value. +. +. +.RS +.LP +.TS +tab(@); +lb lb +l l. +Form@Sequence +1@0, 1, 2, 3, .\|.\|., 10, .\|.\|. +001@000, 001, 002, 003, .\|.\|., 1000, .\|.\|. +i@0, i, ii, iii, iv, .\|.\|. +I@0, I, II, III, IV, .\|.\|. +a@0, a, b, c, .\|.\|., z, aa, ab, .\|.\|. +A@0, A, B, C, .\|.\|., Z, AA, AB, .\|.\|. +.TE +.RE +. +. +.\" ==================================================================== +.SS Fonts +.\" ==================================================================== +. +In +.IR "groff mm" , +the fonts +(or rather, +font styles) +.BR R \~(roman), +.BR I \~(italic), +and +.BR B \~(bold) +are mounted at font positions +.BR 1 , +.BR 2 , +.RB and\~ 3 , +respectively. +. +Internally, +font positions are used for backward compatibility. +. +From a practical point of view, +it doesn't make a big difference\[em]a different font family can still +be selected by invoking +.IR groff 's +.B fam +request or using its +.B \-f +command-line option. +. +On the other hand, +if you want to replace just, +for example, +.RB font\~ I +with Zapf Chancery Medium italic +(available on +.IR groff 's +.B pdf +and +.B ps +output devices), +you have to use the +.B fp +request, +replacing the font at position\~2 with +.RB \[lq] .fp\~2\~ZCMI \[rq]). +. +Because the cover sheet, +memorandum type, +and +.MR @g@refer @MAN1EXT@ +integration macros explicitly request fonts named +.BR B , +.BR I , +and +.BR R , +you will also need to remap these font names with the +.B ftr +request, +for instance with +.RB \[lq] .ftr\~I\~ZCMI \[rq]. +. +. +.\" ==================================================================== +.SH Macros +.\" ==================================================================== +. +An explicitly empty argument may be specified with a pair of double +quotes; +to call a macro +.B XX +with an empty second argument but non-empty first and third ones, +you could input the following. +. +. +.P +.RS +.EX +\&.XX foo \[dq]\[dq] baz +.EE +.RE +. +. +.P +Macro names longer than two characters are GNU extensions; +some shorter names were not part of DWB +.IR mm 's +published interface but are documented aspects of +.I groff mm. +. +. +.TP +.BI )E\ "level text" +Add heading text +.I text +to the table of contents with +.IR level , +which is either\~0 or in the range 1 to\~7. +. +See also +.BR H . +. +This undocumented DWB +.I mm +macro is exposed by +.I groff mm +to enable customized tables of contents. +. +. +.TP +.BR 1C\~ [ 1 ] +Format page text in one column. +. +The page is broken. +. +.RB A\~ 1 +argument suppresses this break; +its use may cause body text and a pending footnote to overprint. +. +See +.BR 2C , +.BR MC , +and +.BR NCOL . +. +. +.TP +.B 2C +Begin two-column formatting. +. +This is a special case of +.BR MC . +. +See +.B 1C +and +.BR NCOL . +. +. +.TP +.B AE +Abstract end; +stop collecting abstract text. +. +See +.BR AS . +. +. +.\" In DWB mm, the mnemonic for `AF` was "alternate first-page format", +.\" and was described in the context of the `A` and `E` registers and +.\" `}Z` and `]S` strings, none of which we support. +.TP +.BR AF \~[\c +.IR firm-name ] +Specify firm associated with the document. +. +At most one can be declared; +the firm name is used by memorandum types and available to cover sheets. +. +.B AF +terminates a document title started with +.BR TL , +and can be called without an argument for that purpose. +. +See +.B MT +and +.BR COVER . +. +. +.TP +.BR AL \~[\c +.IR type \~[ text-indent \~[\c +.BR 1 ]]] +Begin an auto-incrementing numbered list. +. +Item numbers start at one. +. +The +.I type +argument assigns the register format +(see above) +of the list item enumerators. +. +The default +.RB is\~ 1 . +. +An explicitly empty +.I type +also indicates the default. +. +A +.I text-indent +argument overrides register +.BR Li . +. +A third argument suppresses the blank line that normally precedes each +list item. +. +Use +.B LI +to declare list items, +and +.B LE +to end the list. +. +. +.TP +.BR APP \~\c +.RI [ id\~ [ title ]] +Begin an appendix. +. +If the identifier +.I id +is omitted, +it is incremented +(or initialized, +if necessary). +. +The register format used for +.I id +is \[lq]A\[rq]. +. +The page is broken. +. +The register +.B Aph +determines whether an appendix heading is then formatted. +. +This heading uses the string +.B App +followed by +.IR id . +. +Appendices appear in any table of contents +(see +.BR TC ). +. +The string +.B Apptxt +is set to +.I title +if the latter is present, +and made empty otherwise. +. +. +.TP +.BI APPSK\~ "id n" \~\c +.RI [ title ] +As +.BR APP , +but increment the page number by +.IR n . +. +Use this macro to \[lq]skip pages\[rq] when diagrams or other materials +not formatted by +.I @g@troff +are included in appendices. +. +. +.TP +.BR AS\~ [\c +.IR placement \~[ indentation ]] +Abstract start; +begin collecting abstract. +. +Input up to the next +.B AE +call is included in the abstract. +. +.I placement +influences the location of the abstract on the cover sheet of a +memorandum +(see +.BR MT ). +. +.BR \%COVER , +by contrast, +ignores +.I placement +by default, +but can be customized to interpret it. +. +. +.IP +.TS +tab(@); +lf(BI) lb +l lx. +placement@Effect +0@T{ +The abstract appears on page\~1 and cover sheet if the document is a +\[lq]released paper\[rq] memorandum +.RB (\[lq] ".MT 4" \[rq]); +otherwise, +it appears on page\~1 without a cover sheet. +T} +1@T{ +The abstract appears only on the cover sheet +.RB (\[lq] ".MT 4" \[rq] +only). +T} +.\" XXX: This does not appear to be implemented. +.\"2@T{ +.\"The abstract is printed only on the cover sheet (if not +.\".BR ".MT 4" ) +.\". +.\"The cover sheet is printed without a need for \fBCS\fP. +.\"T} +.TE +. +. +.IP +An abstract does not appear at all in external letters +.RB (\[lq] ".MT 5" \[rq]). +. +.RI A\~ placement +of +.B 2 +was supported by DWB +.I mm +but is not by +.IR "groff mm" . +. +. +.IP +A second argument increases the indentation by +.I indentation +and reduces the line length by twice this amount. +. +A scaling unit of ens is assumed. +. +The default is\~0. +. +. +.\" XXX: Do we need a macro for this? Why is it not a string like App +.\" or Licon? It is usefully localizable. +.TP +.BR AST \~\c +.RI [ caption ] +Set the caption above the abstract to +.IR caption , +or clear it if there is no argument. +. +The default is \[lq]ABSTRACT\[rq]. +. +. +.TP +.BI AT\~ title\c +\~.\|.\|. +Specify author's title(s). +. +If present, +.B AT +must appear just after the corresponding author's +.BR AU . +. +Each +.I title +occupies an output line beneath the author's name in the signature block +used by +.B LT +letters +(see +.BR SG ) +and in +.B MT +memoranda. +. +The +.B ms +cover sheet style also uses it. +. +. +.br +.ne 7v +.TP +.BR AU \~\c +.RI [ name\~\c +.RI [ initials\~\c +.RI [ loc\~\c +.RI [ dept\~\c +.RI [ ext\~\c +.RI [ room\~\c +.RI [ arg1\~\c +.RI [ arg2\~\c +.RI [ arg3 ]]]]]]]]] +Specify author. +. +.B AU +terminates a document title started with +.BR TL , +and can be called without arguments for that purpose. +. +Author information is used by cover sheets, +.B MT +memoranda, +and +.BR SG . +. +Further arguments comprise +initials, +location, +department, +telephone extension, +room number or name, +and up to three additional items. +. +Repeat +.B AU +to identify multiple authors. +. +. +.IP +Use +.BR WA / WE +instead to identify the author for documents employing +.BR LT . +. +. +.TP +.BR AV \~[\c +.IR name \~[\c +.BR 1 ]] +Format approval lines for a handwritten signature and date. +. +Two horizontal rules are drawn, +with the specified +.I name +and the text of the string +.B Letdate +beneath them. +. +Above these rules, +the text in the string +.B Letapp +is formatted; +a second argument replaces this text with a blank line. +. +See +.BR LT . +. +. +.\" XXX: AVL is misnamed; it should have been called SGL or similar. +.TP +.BR AVL \~[\c +.IR name ] +As +.BR AV , +but the date, +date rule, +and approval notation +.B Letapp +are omitted. +. +. +.TP +.BR B \~\c \" space in roman; we must use 2-font macro with \c +.RI [ bold-text\~\c +.RI [ previous-font-text ]]\~.\|.\|. +Join +.I bold-text +in boldface with +.I previous-font-text +in the previous font, +without space between the arguments. +. +If no arguments, +switch font to bold style. +. +. +.TP +.B B1 +Begin boxed, +kept display. +. +The text is indented one character, +and the right margin is one character shorter. +. +This is a GNU extension. +. +. +.TP +.B B2 +End boxed, +kept display. +. +This is a GNU extension. +. +. +.TP +.B BE +End bottom block; see +.BR BS . +. +. +.TP +.BR BI \~\c \" space in roman; we must use 2-font macro with \c +.RI [ bold-text\~\c +.RI [ italic-text ]]\~.\|.\|. +Join +.I bold-text +in boldface with +.I italic-text +in italics, +without space between the arguments. +. +. +.TP +.BR BL \~[\c +.IR text-indent \~[\c +.BR 1 ]] +Begin bulleted list. +. +Items are prefixed with a bullet and a space. +. +A +.I text-indent +argument overrides register +.BR Pi . +. +A second argument suppresses blank lines between items. +. +Use +.B LI +to declare list items, +and +.B LE +to end the list. +. +. +.TP +.BR BR \~\c \" space in roman; we must use 2-font macro with \c +.RI [ bold-text\~\c +.RI [ roman-text ]]\~.\|.\|. +Join +.I bold-text +in boldface with +.I roman-text +in roman style, +without space between the arguments. +. +. +.TP +.B BS +Begin bottom block. +. +Input is collected until +.B BE +is called, +and output between the footnote area and footer of each page. +. +. +.\" XXX: Couldn't this have been done with an extra parameter to `VL`? +.\" Or a register influencing VL behavior? +.TP +.BR BVL \~[\c +.IR text-indent \~[ mark-indent \~[\c +.BR 1 ]]] +Begin broken variable-item +(or \[lq]tagged\[rq]) +list. +. +Each item is expected to supply its own mark. +. +The line is always broken after the mark; +contrast +.BR VL . +. +.I text-indent +sets the indentation of the text, +and +.I mark-indent +the distance from the current list indentation to the mark. +. +A third argument suppresses the blank line that normally precedes each +list item. +. +Use +.B LI +to declare list items, +and +.B LE +to end the list. +. +. +.TP +.BR \%COVER \~\c \" space in roman; we must use 2-font macro with \c +.RI [ style ] +Begin a cover page description. +. +.B \%COVER +must appear before the body text +(or main matter) +of a document. +. +The argument +.I style +is used to construct the file name +.IR @TMAC_MDIR@/\: style \:.cov +and load it with the +.B mso +request. +. +The default +.I style +is +.BR ms ; +the +.I ms.cov +file prepares a cover page resembling those of the +.I ms +package. +. +A +.I .cov +file must define a +.B \%COVEND +macro, +which a document must call at the end of the cover description. +. +Use cover description macros in the following order; +only +.B TL +and +.B AU +are required. +. +. +.IP +.EX +\&.COVER +\&.TL +\&.AF +\&.AU +\&.AT +\&.AS +.ne 2v +\&.AE +\&.COVEND +.EE +. +. +.TP +.B COVEND +End the cover description. +. +. +.TP +.B DE +End static or floating display begun with +.B DS +or +.BR DF . +. +. +.TP +.BR DF\~ [\c +.IR format \~[ fill \~[ right-indentation ]]] +Begin floating display. +. +A floating display is saved in a queue and output in the order entered. +. +Arguments are handled as in +.BR DS . +. +Floating displays cannot be nested. +. +Placement of floating displays is controlled by the registers +.B De +and +.BR Df . +. +. +.TP +.BR DL \~[\c +.IR text-indent \~[\c +.BR 1 ]] +Begin dashed list. +. +Items are prefixed with an em dash and a space. +. +A +.I text-indent +argument overrides register +.BR Pi . +. +A second argument suppresses blank lines between items. +. +Use +.B LI +to declare list items, +and +.B LE +to end the list. +. +. +.TP +.BR DS \~[\c +.IR format \~[\c +.IR fill \~[\c +.IR right-indentation ]]] +Begin static display. +. +Input until +.B DE +is called is collected into a display. +. +The display is output on a single page unless it is taller than the +height of the page. +. +.B DS +can be nested +(contrast with +.BR DF ). +. +. +.IP +.TS +tab(@); +Lf(BI) Lb +L Lx. +format@Effect +\f[I]none\f[]@Do not indent the display. +L@Do not indent the display. +I@T{ +Indent text by +.BR \[rs]n[Si] . +T} +C@Center each line. +CB@Center the whole display as a block. +R@Right-adjust the lines. +RB@Right-adjust the whole display as a block. +.TE +. +. +.IP +The values \[lq]L\[rq], +\[lq]I\[rq], +\[lq]C\[rq], +and \[lq]CB\[rq] can also be specified as \[lq]0\[rq], +\[lq]1\[rq], +\[lq]2\[rq], +and +\[lq]3\[rq], +respectively, +for compatibility with +.RI DWB\~ mm. +. +. +.IP +.TS +tab(@); +Lf(BI) Lb +L Lx. +fill@Effect +\f[I]none\f[]@Disable filling. +N@Disable filling. +F@Enable filling. +.TE +. +. +.IP +\[lq]N\[rq] and \[lq]F\[rq] can also be specified as \[lq]0\[rq] and +\[lq]1\[rq], +respectively, +for compatibility with +.RI DWB\~ mm. +. +. +.IP +A third argument +reduces the line length by +.I right-indentation. +. +. +.IP +.I mm +normally +places blank lines before and after the display. +. +Set register +.B Ds +to\~0 to suppress these. +. +. +.TP +.BR EC \~\c +.RI [ title \~[ override \~[ flag \~[ refname ]]]] +Caption an equation. +. +The caption consists of the string +.B Liec +followed by an automatically incrementing counter stored in the register +.BR Ec , +punctuation configured by the register +.BR Of , +then +.I title +(if any). +. +Use the +.B af +request to configure +.BR Ec 's +number format. +. +.I override +and +.I flag +alter the equation number as follows. +. +Omitting +.I flag +and specifying +.B 0 +in its place are equivalent. +. +. +.IP +.TS +tab(@); +Lf(BI) Lb +L Lx. +flag@Effect +0@T{ +Prefix number with +.IR override . +T} +1@T{ +Suffix number with +.IR override . +T} +2@T{ +Replace number with +.IR override . +T} +.TE +. +. +.IP +Equation captions are centered irrespective of the alignment of any +enclosing display. +. +. +.IP +.I refname +stores the equation number using +.BR SETR ; +it can be retreived with +.RB \[lq] .GETST +.IR refname \[rq]. +. +This argument is a GNU extension. +. +. +.IP +Captioned equations are listed in a table of contents +(see +.BR TC ) +if the Boolean register +.B Le +is true. +. +Such a list uses the string +.B Le +as a heading. +. +. +.TP +.BR EF\~ [ \[dq]\|\[aq]\c +.IB left \[aq] center \[aq] right \[aq]\|\[dq]\c +] +Define the even-page footer, +which is formatted just above the normal page footer on even-numbered +pages. +. +See +.BR PF . +. +.B EF +defines the string +.BR EOPef . +. +. +.TP +.BR EH\~ [ \[dq]\|\[aq]\c +.IB left \[aq] center \[aq] right \[aq]\|\[dq]\c +] +Define the even-page header, +which is formatted just below the normal page header on even-numbered +pages. +. +See +.BR PH . +. +.B EH +defines the string +.BR TPeh . +. +. +.TP +.B EN +End equation input preprocessed by +.MR @g@eqn @MAN1EXT@ ; +see +.BR EQ . +. +. +.TP +.B EOP +If defined, +this macro is called in lieu of normal page footer layout. +. +Headers and footers are formatted in a separate environment. +. +See +.BR TP . +. +. +.IP +.TS +tab(@); +Cb S +Lb L. +Strings available to EOP +_ +EOPf@argument to \fBPF\fP +EOPef@argument to \fBEF\fP +EOPof@argument to \fBOF\fP +.TE +. +. +.TP +.BI EPIC\ "\fR[\fP\fB\-L\fP\fR]\fP width height \fR[\fPname\fR]\fP" +Draw a box with the given +.I width +and +.IR height . +. +It also prints the text +.I name +or a default string if +.I name +is not specified. +. +This is used to include external pictures; +just give the size of the picture. +. +.B \-L +left-aligns the picture; +the default is to center. +. +See +.BR PIC . +. +. +.TP +.BR EQ \~[\c +.IR label ] +Start equation input preprocessed by +.MR @g@eqn @MAN1EXT@ . +. +.B EQ +and +.B EN +macro calls bracket an equation region. +. +Such regions must be contained in displays +.RB ( DS / DE ), +except when the region is used only to configure +.I @g@eqn +and not to produce output. +. +If present, +.I label +appears aligned to the right and +centered vertically within the display; +see register +.BR Eq . +. +. +If multiple +.I eqn \" generic +regions occur within a display, +only the last +.I label +(if any) +is used. +. +. +.TP +.BR EX \~\c +.RI [ title \~[ override \~[ flag \~[ refname ]]]] +Caption an exhibit. +. +Arguments are handled analogously to +.BR EC . +. +The register +.B Ex +is the exhibit counter. +. +The string +.B Liex +precedes the exhibit number and any +.I title. +. +Exhibit captions are centered irrespective of the alignment of any +enclosing display. +. +. +.IP +Captioned exhibits are listed in a table of contents +(see +.BR TC ) +if the Boolean register +.B Lx +is true. +. +Such a list uses the string +.B Lx +as a heading. +. +. +.TP +.BR FC \~[\c +.IR closing-text ] +Output the string +.BR Letfc , +or the specified +.I closing-text, +as the formal closing of a letter. +. +. +.TP +.BR FD \~[\c +.IR arg \~[\c +.BR 1 ]] +Configure display of footnotes. +. +The first argument encodes enablement of +automatic hyphenation, +adjustment to the right margin, +indentation of footnote text, +and left- vs.\& right-alignment of the footnote label within the space +allocated for it. +. +. +.br +.ne 5v +.IP +.\" XXX: We can fit one more row using "nokeep" vs. not using it. +.TS +tab(@) nokeep; +Lf(BI) Lb Lb Lb Lb +L L L L L. +arg@Hyphenate?@Adjust?@Indent?@Label alignment +0@no@yes@yes@left +1@yes@yes@yes@left +2@no@no@yes@left +3@yes@no@yes@left +4@no@yes@no@left +5@yes@yes@no@left +6@no@no@no@left +7@yes@no@no@left +8@no@yes@yes@right +9@yes@yes@yes@right +10@no@no@yes@right +11@yes@no@yes@right +.TE +. +. +.IP +An +.I arg +greater than 11 is treated +.RB as\~ 0 . +. +.IR mm 's +default +.RB is\~ 0 . +. +. +.IP +If a second argument, +conventionally +.BR 1 , +is given, +footnote numbering is reset when a first-level heading is encountered. +. +See +.BR FS . +. +. +.TP +.B FE +End footnote; +see +.BR FS . +. +. +.TP +.BR FG \~\c +.RI [ title \~[ override \~[ flag \~[ refname ]]]] +Caption a figure. +. +Arguments are handled analogously to +.BR EC . +. +The register +.B Fg +is the figure counter. +. +The string +.B Lifg +precedes the figure number and any +.I title. +. +Figure captions are centered irrespective of the alignment of any +enclosing display. +. +. +.IP +Captioned figures are listed in a table of contents +(see +.BR TC ) +if the Boolean register +.B Lf +is true. +. +Such a list uses the string +.B Lf +as a heading. +. +. +.TP +.BR FS \~[\c +.IR label ] +Start footnote. +. +Input until +.B FE +is called is collected into a footnote. +. +By default, +footnotes are automatically numbered starting at 1; +the number is available in register +.B :p +and, +with a trailing period, +in +.RB string\~ F . +. +This string precedes the footnote text at the bottom of the column or +page. +. +Footnotes are vertically separated by the product of +.RB registers\~ Fs +and +.BR Lsp . +. +In +.IR "groff mm" , +footnotes may be used in displays. +. +. +.IP +A +.I label +argument replaces the contents of the string +.BR F ; +it need not be numeric. +. +In this event, +the footnote marker in the body text must be explicitly written. +. +. +.TP +.BI GETHN\ "refname \fR[\fPvarname\fR]\fP" +Include the heading number where the corresponding +.RB \[lq] .SETR +.IR refname \[rq] +was placed. +. +This is displayed as \[lq]X.X.X.\[rq] in pass\~1. +. +See +.BR INITR . +. +If +.I varname +is used, +.B GETHN +sets the string +.I varname +to the heading number. +. +.TP +.BI GETPN\ "refname \fR[\fPvarname\fR]\fP" +Include the page number where the corresponding +.RB \[lq] .SETR +.IR refname \[rq] +was placed. +. +This is displayed as \[lq]9999\[rq] in pass\~1. +. +See +.BR INITR . +. +If +.I varname +is used, +.B GETPN +sets the string +.I varname +to the page number. +. +.TP +.BI GETR\ refname +Combine +.B GETHN +and +.B GETPN +with the text \[lq]chapter\[rq] and \[lq],\~page\[rq]. +. +The string +.B Qrf +contains the text for the cross reference: +. +.RS +.IP +\&.ds Qrf See chapter \[rs]\[rs]*[Qrfh], page \[rs]\[rs]*[Qrfp]. +.RE +. +.IP +.B Qrf +may be changed to support other languages. +. +Strings +.B Qrfh +and +.B Qrfp +are set by +.B GETR +and contain the page and heading number, +respectively. +. +.TP +.BI GETST\ "refname \fR[\fPvarname\fR]\fP" +Include the string saved with the second argument to +.BR .SETR . +. +This is a dummy string in pass\~1. +. +If +.I varname +is used, +.B GETST +sets it to the saved string. +. +See +.BR INITR . +. +. +.TP +.BI H\~ level\~\c +.RI [ title \~[ suffix ]] +Set a numbered section heading at +.IR level . +. +.I mm +produces numbered +.I "heading marks" +of the form +.IR a . b . c .\|.\|., +with up to fourteen levels of nesting. +. +Each level's number increases automatically with each +.B H +call and is reset to zero when a more significant +.I level +is specified. +. +.RB \[lq] 1 \[rq]\~is +the most significant or coarsest division of the document. +. +Text after an +.B H +call is formatted as a paragraph; +calling +.B P +is unnecessary. +. +. +.IP +.I title +specifies an optional title; +it must be double-quoted if it contains spaces. +. +.I mm +appends +.I suffix +to +.I title +in the body of the document, +but omits it from any table of contents +(see +.BR TC ). +. +This facility can be used to annotate the heading title with a footnote. +. +.I suffix +should not interpolate +.RB the\~ F +string; +specify a footnote mark explicitly. +. +See +.BR FS . +. +. +.IP +Heading behavior is highly configurable. +. +Several registers set a +.I threshold, +where heading levels at or below the threshold value are handled in one +way, +and those above it another. +. +For example, +a heading level within the threshold of register +.B Cl +is included in the table of contents +(see +.BR TC ). +. +. +.IP +.I Heading layout. +. +Register +.B Ej +sets a threshold for page breaking (ejection) prior to a heading. +. +If not preceded by a page break, +a heading level below the threshold in register +.B Hps +is preceded by the amount of vertical space in register +.BR Hps1 , +and by the amount in +.B Hps2 +otherwise. +. +The +.B Hb +register sets a threshold below which a break occurs after the heading, +and register +.B Hs +sets a threshold below which vertical space follows it. +. +If the heading level is not less than both of these, +a +.I run-in heading +is produced; +paragraph text follows on the same output line. +. +Otherwise, +register +.B Hi +configures the indentation of text after headings. +. +Threshold register +.B Hc +enables the centering of headings; +a heading level below both of the +.B Hb +and +.B Hc +thresholds is centered. +. +. +.IP +.I Heading typeface and size. +. +The fonts used for heading numbers and titles at each level are +configured by the +.B HF +string. +. +The string +.B HP +likewise assigns a type size to each heading level. +. +.\" XXX: Why not an "Hvs" string? +The vertical spacing used by headings may be controlled by +the user-definable macros +.B HX +and/or +.BR HZ . +. +. +.IP +.I Heading number format. +. +Registers named +.B H1 +through +.B H14 +store counters for each heading level. +. +Their values are printed using Arabic numerals by default; +see +.BR HM . +. +The heading levels are catenated with dots for formatting; +to typeset only the deepest, +set the +.B Ht +register. +. +Heading numbers are not suffixed with a trailing dot except when only +the first level is output; +to omit a dot in this case as well, +clear the +.B H1dot +register. +. +. +.IP +.I Customizing heading behavior. +. +.I mm +calls +.I hook +macros to enable further customization of headings. +. +(DWB +.I mm +called these \[lq]exits\[rq].) +. +They can be used to change the heading's +.I mark +(the numbered portion before any heading title), +its vertical spacing, +and its vertical space requirements +(for instance, +to require a minimum quantity of subsequent output lines). +. +Define hook macros in expectation of the following parameters. +. +The argument +.I declared-level +is the +.I level +argument to +.BR H , +.RB or\~ 0 +for unnumbered headings (see +.BR HU ). +. +.I actual-level +is the same as +.I declared-level +for numbered headings, +and the value of +.RB register\~ Hu +for unnumbered headings. +. +.I title +is the corresponding argument to +.B H +or +.BR HU . +. +. +.RS +.TP +.BI HX\~ "declared-level actual-level title" +.I mm +calls +.B HX +before setting the heading. +. +Your definition may alter +.BR }0 , +.BR }2 , +and +.BR ;3 . +. +. +.\" XXX: These names are ugly and of no obvious meaning. Make +.\" documented aliases for them. +.RS +.TP +.BR }0\~ (string) +contains the heading mark plus two spaces if +.I declared-level +is non-zero, +and otherwise is empty. +. +. +.TP +.BR ;0\~ (register) +encodes a position for the text after the heading. +. +0\~means that the heading is to be run in, +1\~means that a break is to occur before the text, +and 2\~means that vertical space is to separate heading and text. +. +. +.TP +.BR }2\~ (string) +is the suffix that separates a run-in heading from the text. +. +It contains two spaces if register +.B ;0 +is\~0, +and otherwise is empty. +. +. +.TP +.BR ;3\~ (register) +contains the vertical space required for the heading to be typeset. +. +If that amount is not available, +the page is broken prior to the heading. +. +The default is +.BR 2v . +.RE +. +. +.TP +.BI HY\~ "declared-level actual-level title" +.I mm +calls +.B HY +after determing the heading typeface and size. +. +It could be used to change indentation. +. +. +.TP +.BI HZ\~ "declared-level actual-level title" +.I mm +calls +.B HZ +after formatting the heading, +just before +.B H +or +.B HU +returns. +. +It could be used to change the page header to include a section heading. +.\" XXX: ...but only for the _next_ page, not the current one. See +.\" Savannah #62825. +.RE +. +. +.TP +.BI HC\ \fR[\fPhyphenation-character\fR]\fP +Set hyphenation character. +. +Default value is \[lq]\[rs]%\[rq]. +. +Resets to the default if called without argument. +. +Hyphenation can be turned off by setting register +.B Hy +to\~0 at the beginning of the file. +. +. +.TP +.BI HM\ "\fR[\fParg1 \fR[\fParg2 \fR[.\|.\|.\& [\fParg14\fR]]]]\fP" +Set the heading mark style. +. +Each argument assigns the specified register format +(see above) +to the corresponding heading level. +. +The default +.RB is\~ 1 +for all levels. +. +An explicitly empty argument also indicates the default. +. +. +.TP +.BI HU\~ heading-text +Set an unnumbered section heading. +. +Except for a heading number, +it is treated as a numbered heading of the level stored in +.RB register\~ Hu ; +.RB see\~ H . +. +. +.TP +.BR I \~\c \" space in roman; we must use 2-font macro with \c +.RI [ italic-text\~\c +.RI [ previous-font-text ]]\~.\|.\|. +Join +.I italic-text +in italics with +.I previous-font-text +in the previous font, +without space between the arguments. +. +If no arguments, +switch font to italic style. +. +. +.TP +.BR IA \~[\c +.IR recipient-name \~[\c +.IR title ]] +Specify the inside address in a letter. +. +Input is collected into the inside address until +.B IE +is called, +and then output. +. +You can specify multiple recipients with empty +.BR IA / IE +pairs; +only the last address is used. +. +The arguments give each recipient a name and title. +. +See +.BR LT . +. +. +.TP +.BR IB \~\c \" space in roman; we must use 2-font macro with \c +.RI [ italic-text\~\c +.RI [ bold-text ]]\~.\|.\|. +Join +.I italic-text +in italics with +.I bold-text +in boldface, +without space between the arguments. +. +. +.TP +.B IE +End the inside address begun with +.BR IA . +. +. +.TP +.BI IND\~ argument\~\c +\&.\|.\|. +If the Boolean register +.B Ref +is true, +write an index entry as a specially prepared +.I roff +comment to the standard error stream, +with each +.I argument +separated from its predecessor by a tab character. +. +The entry's location information is arranged as configured by the most +recent +.B INITI +call. +. +. +.TP +.B INDP +Output the index set up by +.B INITI +and populated by +.B IND +calls. +. +By default, +.B INDP +calls +.B SK +and writes a centered caption interpolating the string +.BR Index . +. +It then disables filling and calls +.BR 2C ; +afterward, +it restores filling and calls +.BR 1C . +. +. +.IP +Define macros to customize this behavior. +. +.B INDP +calls +.B TXIND +before the caption, +.B TYIND +.I instead +of writing the caption, +and +.B TZIND +after formatting the index. +. +. +.TP +.BI INITI\~ "location-type file-name\~"\c +.RI [ macro ] +Initialize +.IR "groff mm" 's +indexing system. +. +Argument +.I location-type +selects how the location of each index entry is reported. +. +.I file-name +populates an internal string used later by +.BR INDP . +. +. +.IP +.TS +tab(@); +Lf(BI) Lb +L Lx. +location-type@Entry format +N@page number +H@heading mark +B@page number, tab character, heading mark +.TE +. +. +.IP +If +.I macro +is specified, +it is called for each index entry +with the arguments given to +.BR IND . +. +. +.TP +.BI INITR\~ id +Initialize the cross reference macros. +. +Cross references are written to the standard error stream, +which should be redirected into a file named +.RI id .qrf . +. +.MR mmroff @MAN1EXT@ +handles this and the two formatting passes it requires. +.\". +.\"This program exists because +.\".MR groff @MAN1EXT@ +.\"by default deactivates the unsafe operations that are required by +.\".BR INITR . +. +The first pass identifies cross references, +and the second one includes them. +.\" +.\".B INITR +.\"can be used several times, +.\"but it is only the first occurrence of +.\".B INITR +.\"that is active. +. +. +.IP +See +.BR SETR , +.BR GETPN , +and +.BR GETHN . +. +. +.TP +.BR IR \~\c \" space in roman; we must use 2-font macro with \c +.RI [ italic-text\~\c +.RI [ roman-text ]]\~.\|.\|. +Join +.I italic-text +in italics with +.I roman-text +in roman style, +without space between the arguments. +. +. +.TP +.BR ISODATE\~ [ 0 ] +Use ISO\~8601 format for the date string +.B DT +used by some cover sheet and memorandum types; +that is, +.IR YYYY - MM - DD . +. +Must be called before +.B ND +to be effective. +. +If given an argument +.RB of\~ 0, +the traditional date format for the +.I groff +locale is used; +this is also the default. +. +. +.TP +.BI LB\~ "text-indent mark-indent pad type"\~\c +.RI [ mark \~[ pre-item-space \~[ pre-list-space ]]] +Begin list. +. +The macros +.BR AL , +.BR BL , +.BR BVL , +.BR DL , +.BR ML , +.BR RL , +and +.B VL +call +.B LB +in various ways; +they are simpler to use and may be preferred if they suit the desired +purpose. +. +. +.br +.ne 5v +.IP +The nesting level of lists is tracked by +.I mm; +the outermost level is\~0. +. +The text of each list item is indented by +.I text-indent; +the default is taken from the +.B Li +register +(in ens). +. +Each item's mark is indented by +.I mark-indent; +the default is +.BR 0n . +. +The mark is normally left-aligned. +. +If +.I pad +is greater than zero, +.I mark-indent +is overridden such that +.I pad +ens of space follow the mark. +. +.I type +selects one of six possible ways to display the mark. +. +. +.IP +.TS +tab(@); +Lf(BI) Lb +L L. +type@Output for a mark \[lq]x\[rq] +1@x. +2@x) +3@(x) +4@[x] +5@<x> +6@{x} +.TE +. +. +.IP +If +.I type +is\~0 and +.I mark +is unspecified, +the items are set with a hanging indent. +. +Otherwise, +.I mark +is interpreted as a string defining the mark. +. +If +.I type +is greater than zero, +items are automatically numbered; +.I mark +is interpreted as a register format. +. +The default +.I type +.RB is\~ 0 . +. +. +.IP +The last two arguments manage vertical space. +. +Unless a list's nesting level is greater than the value of register +.BR Ls , +its items are preceded by +.I pre-item-space +multiplied by the register +.BR Lsp ; +the default +.RB is\~ 1 . +. +.B LB +precedes the list by +.I pre-list-space +multiplied by the register +.BR Lsp ; +the default +.RB is\~ 0 . +. +. +.TP +.BR LC \~[\c +.IR list-level ] +Clear list state. +. +Active lists are terminated as if with +.BR LE , +either all +(the default) +or only those from the current level down to +.I list-level +if specified. +. +.B H +calls +.B LC +automatically. +. +. +.TP +.BR LE \~[ 1 ] +End list. +. +The current list is terminated. +. +An argument +.RB of\~ 1 +causes +vertical space in the amount of register +.B Lsp +to follow the list. +. +. +.TP +.BR LI \~[\c +.IR mark \~[ item-mark-mode ]] +Begin a list item. +. +Input is collected into a list item until the current list is terminated +or +.B LI +is called again. +. +By default, +the item's text is preceded by any mark configured by the current list. +. +If only +.I mark +is specified, +it replaces the configured mark. +. +A second argument +prefixes +.I mark +to the configured mark; +an +.I item-mark-mode +value of\~1 places an unbreakable space after +.I mark, +while +a value of\~2 does not +(rendering the two adjacent). +. +Also see register +.BR Limsp . +. +. +.TP +.BI LO\~ option\~\c +.RI [ value ] +Specify letter options; +see +.BR LT . +. +Standard options are as follows. +. +See +.B IA +regarding the inside address and string +.B DT +regarding the date. +. +. +.IP +.TS +tab(@); +Lf(BI) Lb +L Lx. +option@Effect +AT@T{ +Attention; +put contents of string +.B LetAT +and +.I value +left-aligned after the inside address. +T} +CN@T{ +Confidential; +put +.I value, +or contents of string +.BR LetCN , +left-aligned after the date. +T} +RN@T{ +Reference; +put contents of string +.B LetRN +and +.I value +after the confidental notation +(if any) +and the date, +aligned with the latter. +T} +SA@T{ +Salutation; +put +.I value, +or contents of string +.BR LetSA , +left-aligned after the inside address +and the confidental notation +(if any). +T} +SJ@T{ +Subject; +put contents of string +.B LetSJ +and +.I value +left-aligned after the inside address +and the attention and salutation notations +(if any). +. +In letter type \[lq]SP\[rq], +.B LetSJ +is ignored and +.I value +is set in full capitals. +T} +.TE +. +. +.br +.ne 5v +.TP +.BR LT \~[\c +.IR style ] +Format a letter in the designated +.I style, +defaulting to +.B BL +(see below). +. +A letter begins with the writer's address +.RB ( WA / WE ), +followed by the date +.RB ( ND ), +the inside address +.RB ( IA / IE ), +the body of the letter +.RB ( P +and other general-purpose +.I mm +macros), +the formal closing +.RB ( FC ), +the signature +.RB ( SG ), +and notations +.RB ( NS / NE ). +. +Any of these may be omitted. +. +Letter options specified with +.B LO +add further annotations, +which are extensible; +see section \[lq]Internals\[rq] below. +. +. +.br +.ne 6v +.IP +.TS +tab(@); +Lf(BI) Lb +Lb Lx. +style@Description +BL@T{ +Blocked: +the writer's address, +date, +formal closing, +and signature are indented to the center of the line. +. +Everything else is left-aligned. +T} +SB@T{ +Semi-blocked: +as +.BR BL , +but the first line of each paragraph is indented by +.BR 5m . +.\" XXX: https://savannah.gnu.org/bugs/?64315 +T} +FB@T{ +Fully blocked: +everything begins at the left margin. +T} +SP@T{ +Simplified: +as +.BR FB , +but a formal closing is omitted, +and the signature is set in full capitals. +T} +.TE +. +. +.TP +.BI MC\~ column-width\~\c +.RI [ gutter-width ] +Begin multi-column layout. +. +.I groff mm +creates as many columns of +.I column-width +as the line length will permit. +. +.I gutter-width +is the interior spacing between columns. +. +It defaults to +.IR column-width /15. +. +.B 1C +returns to single-column layout. +. +.B MC +is a GNU extension. +. +See +.B MULB +for an alternative. +. +. +.TP +.BI ML\~ "mark \fR[\fPtext-indent\~" \fR[\fP1\fR]]\fP +Start a list with the +.I mark +argument preceding each list item. +. +.I text-indent +overrides the default indentation of the list items set by register +.BR Li . +. +If a third argument, +conventionally +.BR 1 , +is given, +the blank line that normally precedes each list item is suppressed. +. +Use +.B LI +to declare list items, +and +.B LE +to end the list. +. +. +.TP +.BR MT \~\c \" space in roman; we must use 2-font macro with \c +.RI [ type \~[ addressee ]] +Select memorandum type. +. +These correspond to formats used by AT&T Bell Laboratories, +where the +.I mm +package was initially developed, +affecting the document layout. +. +Some of these included a cover page with a caption categorizing the +document. +. +.I groff mm +uses +.I type +to construct the file name +.IR @TMAC_MDIR@/\:\% type \:.MT +and load it with the +.B mso +request. +. +Memorandum types 0 to\~5 are supported; +any other value of +.I type +is mapped to type\~6. +. +If +.I type +is omitted, +.B 0 +is implied. +. +.I addressee +sets a string analogous to one used by AT&T cover sheet macros that are +not implemented in +.IR "groff mm" . +. +. +.IP +.TS +tab(@); +Lf(BI) Lb +L L. +type@Description +0@normal memorandum; no caption +1@captioned \[lq]MEMORANDUM FOR FILE\[rq] +2@captioned \[lq]PROGRAMMER'S NOTES\[rq] +3@captioned \[lq]ENGINEER'S NOTES\[rq] +4@released paper +5@external letter +.TE +. +. +.IP +See +.B \%COVER +for a more flexible cover sheet mechanism. +. +. +.TP +.BI MOVE\ "y-pos \fR[\fPx-pos \fR[\fPline-length\fR]]\fP" +Move to a position, setting page offset to +.IR x-pos . +. +If +.I line-length +is not given, the difference between current and new page offset is +used. +. +Use +.B PGFORM +without arguments to return to normal. +. +. +.TP +.BR MULB \~\c \" space in roman; we must use 2-font macro with \c +.IR "cw1 space1\~" [ "cw2 space2" "] .\|.\|.\~" cwn +Begin alternative multi-column mode. +. +All column widths must be specified, +as must the amount of space between each column pair. +. +The arguments' default scaling unit is +.BR n . +. +.B MULB +uses a diversion and operates in a separate environment. +. +. +.TP +.B MULN +Begin next column in alternative column mode. +. +. +.TP +.B MULE +End alternative multi-column mode and emit the columns. +. +. +.TP +.B NCOL +Move to the start of the next column +(only when using +.B 2C +or +.BR MC ). +. +Contrast with +.BR MULN . +. +. +.TP +.BR ND \~[\c +.IR arg ] +Set the document's date. +. +.I mm +does not interpret +.IR arg ; +it can be a revision identifier +(or empty). +. +. +.TP +.B NE +End notation begun with +.BR NS ; +filling is enabled. +. +. +.TP +.BI nP\ \fR[\fPtype\fR]\fP +Begin a numbered paragraph at heading level two. +. +See +.BR P . +. +. +.br +.ne 6v +.TP +.BR NS \~[\c +.IR code \~[\c +.BR 1 ]] +Declare notations, +typically for letters or memoranda, +of the type specified by +.IR code . +. +The text corresponding to +.I code +is output, +and filling is disabled +until +.B NE +is called. +. +Typically, +a list of names or attachments lies within +.BR NS / NE . +. +If +.I code +is absent or does not match one of the values listed under the +.B Letns +string description below, +each line of notations is formatted as +.RI "\[lq]Copy (" line ") to\[rq]." +. +If a second argument, +conventionally +.BR 1 , +is given, +.I code +becomes the entire notation and +.B NE +is not necessary. +. +In +.IR "groff mm" , +you can set up further notations to be recognized by +.BR NS ; +see the strings +.B Letns +and +.B Letnsdef +below. +. +. +.TP +.BR OF\~ [ \[dq]\|\[aq]\c +.IB left \[aq] center \[aq] right \[aq]\|\[dq]\c +] +Define the odd-page footer, +which is formatted just above the normal page footer on odd-numbered +pages. +. +See +.BR PF . +. +.B OF +defines the string +.BR EOPof . +. +. +.TP +.BR OH\~ [ \[dq]\|\[aq]\c +.IB left \[aq] center \[aq] right \[aq]\|\[dq]\c +] +Define the odd-page header, +which is formatted just below the normal page header on odd-numbered +pages. +. +See +.BR PH . +. +.B OH +defines the string +.BR TPoh . +. +. +.TP +.B OP +Make sure that the following text is printed at the top of an +odd-numbered page. +. +Does not output an empty page if currently at the top of an odd page. +. +. +.br +.ne 4v +.TP +.BR P \~[\c +.IR type ] +Begin new paragraph. +. +If +.I type +is missing or\~ 0, +.BR P \~sets +the paragraph fully left\-aligned. +. +A +.I type +of\~1 +idents the first line by +.B \[rs][Pi] +ens. +. +Set the register +.B Pt +to select a default paragraph indentation style. +. +The register +.B Ps +controls the vertical spacing between paragraphs. +. +. +.TP +.B PE +Picture end; +see +.MR @g@pic @MAN1EXT@ . +. +. +.TP +.BR PF\~ [ \[dq]\|\[aq]\c +.IB left \[aq] center \[aq] right \[aq]\|\[dq]\c +] +Define the page footer. +. +The footer is formatted at the bottom of each page; +the argument is otherwise as described in +.BR PH . +. +.B PF +defines the string +.BR EOPf . +. +See +.BR EF , +.BR OF , +and +.BR EOP . +. +.TP +.BI PGFORM\ "\fR[\fPlinelength \fR[\fPpagelength \fR[\fPpageoffset\ " \fR[\fP1\fR]]]]\fP +Set line length, page length, and/or page offset. +. +This macro can be used for letterheads and similar. +. +It is normally the first macro call in a file, +though it is not necessary. +. +.B PGFORM +can be used without arguments to reset everything after a +.B MOVE +call. +. +A line break is done unless the fourth argument is given. +. +This can be used to avoid the page number on the first page +while setting new width and length. +. +(It seems as if this macro sometimes doesn't work too well. +. +Use the command-line arguments to change +line length, page length, and page offset instead.) +. +.TP +.B PGNH +Suppress header on the next page. +. +This macro must be called before any macros that produce output to +affect the layout of the first page. +. +. +.TP +.BR PH\~ [ \[dq]\|\[aq]\c +.IB left \[aq] center \[aq] right \[aq]\|\[dq]\c +] +.RS +Define the page header, +formatted at the top of each page, +as the argument, +where +.IR left , +.IR center , +and +.I right +are aligned to the respective locations on the line. +. +A +.RB \[lq] % \[rq] +character in +.I arg +is replaced by the page number. +. +If the argument is absent, +no page header is set. +. +The default page header is +. +.RS +.EX +\[dq]\[aq]\[aq]\- % \-\[aq]\[aq]\[dq] +.EE +.RE +. +which centers the page number between hyphens and formats nothing at the +upper left and right. +. +Header macros call +.B PX +(if defined) +after formatting the header. +. +.B PH +defines the string +.BR TPh . +. +See +.BR EH , +.BR OH , +and +.BR TP . +.RE +. +. +.TP +.BR PIC \~\c +.RB [ \-B ]\~\c +.RB [ \-C |\c +.BI \-I\~ n\c +.RB | \-L \c +.RB | \-R ]\~\c +.IR file \~[ width \~[ height ]] +Include PostScript document +.IR file . +. +The optional +.B \-B +argument draws a box around the picture. +. +The optional +.BR \-L , +.BR \-C , +.BR \-R , +and +.BI \-I\~ n +arguments align the picture or indent it by +.I n +(assuming a scaling unit of +.BR m ). +. +By default, +the picture is left-aligned. +. +Optional +.I width +and +.I height +arguments resize the picture. +. +Use of this macro requires two-pass processing; +see +.B INITR +and +.MR mmroff @MAN1EXT@ . +. +. +.TP +.B PS +Picture start; see +.MR @g@pic @MAN1EXT@ . +. +. +.TP +.B PY +Picture end with flyback. +. +Ends a +.MR @g@pic @MAN1EXT@ +picture, +returning the vertical position to where it was prior to the picture. +. +This is a GNU extension. +. +. +.TP +.BR R \~\c \" space in roman; we must use 2-font macro with \c +.RI [ roman-text\~\c +.RI [ previous-font-text ]]\~.\|.\|. +Join +.I roman-text +in roman style with +.I previous-font-text +in the previous font, +without space between the arguments. +. +If no arguments, +switch font to roman style. +. +. +.TP +.BR RB \~\c \" space in roman; we must use 2-font macro with \c +.RI [ roman-text\~\c +.RI [ bold-text ]]\~.\|.\|. +Join +.I roman-text +in roman style with +.I bold-text +in boldface, +without space between the arguments. +. +. +.TP +.BI RD\ "\fR[\fPprompt \fR[\fPdiversion \fR[\fPstring\fR]]]\fP" +Read from standard input to diversion and/or string. +. +The text is saved in a diversion named +.IR diversion . +. +Recall the text by writing the name of the diversion after a dot +on an empty line. +. +A string is also defined if +.I string +is given. +. +.I Diversion +and/or +.I prompt +can be empty (\[dq]\[dq]). +. +.TP +.B RF +Reference end. +. +Ends a reference definition and returns to normal processing. +. +See +.BR RS . +. +. +.TP +.BR RI \~\c \" space in roman; we must use 2-font macro with \c +.RI [ roman-text\~\c +.RI [ italic-text ]]\~.\|.\|. +Join +.I roman-text +in roman style with +.I italic-text +in italics, +without space between the arguments. +. +. +.TP +.BR RL \~[\c +.IR text-indent \~[\c +.BR 1 ]] +Begin reference list. +. +Each item is preceded by an automatically incremented number between +square brackets; +compare +.BR AL . +. +.I text-indent +changes the default indentation. +. +Use +.B LI +to declare list items, +and +.B LE +to end the list. +. +A second argument, +conventionally +.BR 1 , +suppresses the blank line that normally precedes each list item. +. +. +.TP +.BR RP \~\c \" space in roman; we must use 2-font macro with \c +.RI [ suppress-counter-reset \~[ page-ejection-policy ]] +Format a reference page, +listing items accumulated within +.BR RS / RF +pairs. +. +The reference counter is reset unless the first argument +.RB is\~ 1 . +. +Normally, +page breaks occur before and after the references are output; +the register +.B Rpe +configures this behavior, +and a second argument overrides its value. +. +.B TC +calls +.B RP +automatically if references have accumulated. +. +. +.IP +References are list items, +and thus are vertically separated +(see +.BR LB ). +. +Setting register +.B Ls +.RB to\~ 0 +suppresses this spacing. +. +The string +.B Rp +contains the reference page caption. +. +. +.br +.ne 5v +.TP +.BR RS \~[\c +.IR reference-string ] +Begin an automatically numbered reference definition. +. +By default, +references are numbered starting at 1; +the number is available in register +.BR :R . +. +Interpolate the string +.B Rf +where the reference mark should be and write the reference between +.BR RS / RF +on an input line after the reference mark. +. +If +.I reference-string +is specified, +.I "groff ms" +also stores the reference mark in a string of that name, +which can be interpolated as +.BI \[rs]*[ reference-string ] +subsequently. +. +. +.TP +.BR S \~[\c +.IR type-size \~[ vertical-spacing ]] +Set type size and vertical spacing. +. +Each argument is a +.I groff +measurement, +using an appropriate scaling unit and an optional +.B + +or +.B \- +prefix to increment or decrement the current value. +. +An argument of +.B P +restores the previous value, +.B C +indicates the current value, +and +.B D +requests the default. +. +An empty or omitted argument is treated as +.BR P . +. +. +.TP +.BR SA \~\c +.RI [ mode ] +Set or restore the default enablement of adjustment. +. +Specify +.B 0 +or +.B 1 +as +.I mode +to set a document's default explicitly; +.B 1 +is assumed by +.IR mm . +. +Adjustment can be temporarily suspended with the +.B na +request. +. +When the +.B H +or +.B HU +macros are used to format a heading, +or when +.B SA +is called without a +.I mode +argument, +the default adjustment is restored. +. +. +.TP +.BI SETR\ "refname \fR[\fPstring\fR]\fP" +Remember the current heading and page numbers as +.IR refname . +. +Saves +.I string +if +.I string +is defined. +. +.I string +is retrieved with +.BR GETST . +. +See +.BR INITR . +. +.TP +.BI SG\ \fR[\fParg\ \fR[\fP1\fR]]\fP +Signature line. +. +Prints the authors name(s) after the formal closing. +. +The argument is appended to the reference data, printed at either the +first or last author. +. +The reference data is the location, department, and initials specified +with +.BR AU . +. +It is printed at the first author if the second argument is given, +otherwise at the last. +. +No reference data is printed if the author(s) is specified through +.BR WA / WE . +. +See section \[lq]Internals\[rq] below. +. +. +.TP +.BR SK \~\c +.RI [ n ] +Skip +.I n +pages. +. +If +.I n +is\~0 or omitted, +the page is broken unless the drawing position is already at the top of +a page. +. +Otherwise, +.I n +pages, +blank except for any headers and footers, +are printed. +. +. +.br +.ne 4v \" XXX: 3v should suffice +.TP +.BI SM\~ text\~\c +.RI [ post ] +.TQ +.BI SM\~ "pre text post" +Format +.I text +at a smaller type size, +joined with any specified +.I pre +and +.I post +at normal size. +. +. +.TP +.BI SP\ \fR[\fPlines\fR]\fP +Space vertically. +. +.I lines +can have any scaling factor, +like \[lq]3i\[rq] or \[lq]8v\[rq]. +. +Several +.B SP +calls in a line only produces the maximum number of lines, not the sum. +. +.B SP +is ignored also until the first text line in a page. +. +Add +.B \[rs]& +before a call to +.B SP +to avoid this. +. +. +.TP +.B TAB +Reset tab stops to every 5\~ens. +. +. +.br +.ne 4v +.TP +.BR TB \~\c +.RI [ title \~[ override \~[ flag \~[ refname ]]]] +Caption a table. +. +Arguments are handled analogously to +.BR EC . +. +The register +.B Tb +is the table counter. +. +The string +.B Litb +precedes the table number and any +.I title. +. +Table captions are centered irrespective of the alignment of any +enclosing display. +. +. +.IP +Captioned tables are listed in a table of contents +(see +.BR TC ) +if the Boolean register +.B Lt +is true. +. +Such a list uses the string +.B Lt +as a heading. +. +. +.TP +.BR TC \~\c +.RI [ slevel\~\c +.RI [ spacing\~\c +.RI [ tlevel\~\c +.RI [ tab\~\c +.RI [ h1\~\c +.RI [ h2\~\c +.RI [ h3\~\c +.RI [ h4\~\c +.RI [ h5 ]]]]]]]]] +Output table of contents. +. +This macro is normally the last called in the document. +. +It flushes any pending displays and, +if any references are pending +(see +.BR RS ), +calls +.BR RP . +. +It then begins a new page with the contents caption, +stored in the string +.BR Licon , +centered at the top. +. +The entries follow after three vees of space. +. +Each entry is a +saved section +(number and) +heading title +(see the +.B Cl +register), +along with its associated page number. +. +By default, +an entry is indented by an amount corresponding to its heading level +and the maximum heading length encountered at that heading level; +if defined, +the string +.B Ci +overrides these indentations. +. +Entries at heading levels up to and including +.I slevel +are preceded by +.I spacing +vees of space. +. +Entries at heading levels up to and including +.I tlevel +are followed by a leader and a right-aligned page number. +. +If the Boolean-valued +.I tab +argument is true, +the leader is replaced with horizontal motion in the same amount. +. +For entries above heading level +.IR tlevel , +the page number follows the heading text after a word space. +. +Each argument +.IR h1 .\|.\|. h5 +appears in order on its own line, +centered, +above the contents caption. +. +Page numbering restarts at 1, +in register format \[lq]i\[rq]. +. +If the +.B Oc +register is true, +numbering of these pages is suppressed. +. +. +.IP +If +.B TC +is called with at most four arguments, +it calls the user-defined macro +.B TX +(if defined) +prior to formatting the contents caption, +and +.B TY +(if defined) +.I instead +of formatting the contents caption. +. +. +.IP +Analogous handling of lists of figures, +tables, +equations, +and exhibits is achieved by defining +.BI TX xx +and +.BI TY xx +macros, +where +.I xx +is \[lq]FG\[rq], +\[lq]TB\[rq], +\[lq]EC\[rq], +or \[lq]EX\[rq], +respectively. +. +Similarly, +the strings +.BR Lifg , +.BR Litb , +.BR Liex , +and +.B Liec +determine captions for their respective lists. +. +. +.TP +.B TE +Table end. +. +See +.BR TS . +. +.TP +.B TH +End table heading. +. +It is repeated after page breaks within a table. +. +See +.BR TS . +. +The +.B N +argument supported by DWB +.I mm +is not implemented by +.I "groff mm." +. +. +.TP +.BR TL \~[\c +.IR charging-case-number \~[\c +.IR filing-case-number ]] +Begin document title. +. +Input is collected into the title until +.B AF +or +.B AU +is called, +and output as directed by the cover page. +. +.I charging-case-number +and +.I filing-case-number +are saved for use in memorandum types 0 and 5. +. +See +.BR MT . +. +. +.TP +.BI TM\~ number\c +\~.\|.\|. +Declare technical memorandum number(s) used by +.BR MT . +. +. +.br +.ne 6v +.TP +.B TP +If defined, +this macro is called in lieu of normal page header layout. +. +Headers and footers are formatted in a separate environment. +. +See +.BR EOP . +. +. +.IP +.TS +tab(@); +Cb S +Lb L. +Strings available to TP +_ +TPh@argument to \fBPH\fP +TPeh@argument to \fBEH\fP +TPoh@argument to \fBOH\fP +.TE +. +. +.TP +.B TS \fR[\fPH\fR]\fP +Table start. +. +Argument \[lq]H\[rq] tells +.I mm +that the table has a heading. +. +See +.BR TE , +.BR TH , +and +.MR @g@tbl @MAN1EXT@ . +. +. +.TP +.BR VERBON \~\c \" space in roman; we must use 2-font macro with \c +.RI [ format \~[ type-size \~[ font ]]] +Begin verbatim display, +where characters have equal width. +. +.I format +controls several parameters. +. +Add up the values of desired features; +the default +.RB is\~ 0 . +. +On typesetting devices, +further arguments configure the +.I type-size +in scaled points, +and the face +.RI ( font ); +the default is +.B CR +(Courier roman). +. +. +.IP +.TS +tab(@); +lb lb +l lx. +Value@Effect +1@Disable the formatter's escape character (\[rs]). +2@Vertically space before the display. +4@Vertically space after the display. +8@T{ +Number output lines; call formatter's +.B nm +request with arguments in string +.BR Verbnm . +T} +16@T{ +Indent by the amount stored in register +.BR Verbin . +T} +.TE +. +. +.TP +.B VERBOFF +End verbatim display. +. +. +.TP +.BR VL \~[\c +.IR text-indent \~[ mark-indent \~[\c +.BR 1 ]]] +Begin variable-item +(or \[lq]tagged\[rq]) +list. +. +Each item should supply its own mark, +or tag. +. +If the mark is wider than +.I mark-indent, +one space separates it from subsequent text; +contrast +.BR BVL . +. +.I text-indent +sets the indentation of the text, +and +.I mark-indent +the distance from the current list indentation to the mark. +. +A third argument suppresses the blank line that normally precedes each +list item. +. +Use +.B LI +to declare list items, +and +.B LE +to end the list. +. +. +.TP +.BI "VM \fR[\fP\-T\fR] [\fP" "top \fR[\fPbottom\fR]]\fP" +Vertical margin. +. +Increase the top and bottom margin by +.I top +and +.IR bottom , +respectively. +. +If option +.B \-T +is specified, set those margins to +.I top +and +.IR bottom . +. +If no argument is given, reset the margin to zero, or to the default +(\[lq]7v 5v\[rq]) +if +.B \-T +is used. +. +It is highly recommended that macros +.B TP +and/or +.B EOP +are defined if using +.B \-T +and setting top and/or bottom margin to less than the default. +. +This undocumented DWB +.I mm +macro is exposed by +.I groff mm +to increase user control of page layout. +. +. +.TP +.BR WA \~[\c +.IR writer's-name \~[\c +.IR title ]] +Specify the writer(s) of an +.B LT +letter. +. +Input is collected into the writer's address until +.B WA +is called, +and then output. +. +You can specify multiple writers with empty +.BR WA / WE +pairs; +only the last address is used. +. +The arguments give each writer a name and title. +. +. +.TP +.BR WC \~[\c +.IR format \~.\|.\|.] +Control width of footnotes and displays. +. +. +.IP +.RS +.TS +tab(@); +Lf(BI) Lb +Lb Lx. +format@Effect +N@T{ +equivalent to +.RB \[lq] "\-WF \-FF \-WD" \[rq] +.\" FB \" XXX: see Savannah ticket reference below +(default) +T} +WF@T{ +set footnotes at full line length, +even in two-column mode +.\" XXX: what about multi-column modes more generally? +T} +\-WF@T{ +set footnotes using column line length +T} +FF@T{ +apply width of first footnote to encountered to subsequent ones +T} +\-FF@T{ +footnote width determined by +.B WF +and +.B \-WF +T} +WD@T{ +set displays at full line length, +even in two-column mode +.\" XXX: what about multi-column modes more generally? +T} +\-WD@T{ +set displays using column line length +T} +.TE +.RE +.\" XXX: See <https://savannah.gnu.org/bugs/?64316>. +.\"FB@T{ +.\"Break when outputting floating displays. +.\"T} +.\"\-FB@T{ +.\"Do not break when outputting floating displays. +.\"T} +. +. +.TP +.B WE +End the writer's address begun with +.BR WA . +. +. +.br +.ne 4v +.\" ==================================================================== +.SH Strings +.\" ==================================================================== +. +Many +.I mm +strings interpolate predefined, +localizable text. +. +These are presented in quotation marks. +. +. +.TP +.B App +\[lq]APPENDIX\[rq] +. +. +.TP +.B Apptxt +stores the +.I title +argument to the last +.B APP +call. +. +. +.TP +.B BU +interpolates a bullet +(see +.BR BL ). +. +. +.TP +.B Ci +is a list of indentation amounts to use for table of contents heading +levels, +overriding their automatic computation. +. +Each word must be a horizontal measurement +(like +.RB \[lq] 1i \[rq]) +and is mapped one-to-one to heading levels 1, +2, +and so on. +. +. +.TP +.B DT +The date; +set by the +.B ND +macro +(defaults to the date the document is formatted). +. +The format is the conventional one for the +.I groff +locale, +but see the +.B ISODATE +macro and +.B Iso +register. +. +. +.TP +.B EM +interpolates an em dash. +. +. +.TP +.B F +interpolates an automatically numbered footnote marker; +the number is used by the next +.B FS +call without an argument. +. +In +.I troff +mode, +the marker is superscripted; +in +.I nroff +mode, +it is surrounded by square brackets. +. +. +.TP +.B H1txt +Updated by +.B .H +and +.B .HU +to the current heading text. +. +Also updated in table of contents & friends. +. +. +.TP +.B HF +assigns font identifiers, +separated by spaces, +to heading levels in one-to-one correspondence. +. +Each identifier may be a font mounting position, +font name, +or style name. +. +Omitted values are assumed to be\~1. +. +The default is +.RB \[lq] "2 2 2 2 2 2 2 2 2 2 2 2 2 2" \[rq], +which places all headings in italics. +. +DWB +.IR mm 's +default was +.RB \[lq] "3 3 2 2 2 2 2" \[rq]. +. +. +.TP +.B HP +assigns type sizes, +separated by spaces, +to heading levels in one-to-one correspondence. +. +Each size is interpreted in scaled points; +zero values are translated to +.BR 10 . +. +Omitted values are assumed to be\~0 +(and are translated accordingly). +. +The default is +.RB \[lq] "0 0 0 0 0 0 0 0 0 0 0 0 0 0" \[rq]. +. +. +.TP +.B Index +\[lq]INDEX\[rq] +. +. +.TP +.B Le +\[lq]LIST OF EQUATIONS\[rq] +. +. +.TP +.B Letfc +\[lq]Yours very truly,\[rq] +(see +.BR FC ) +. +. +.TP +.B Letapp +\[lq]APPROVED:\[rq] +(see +.BR AV ) +. +. +.TP +.B LetAT +\[lq]ATTENTION:\[rq] +(see +.BR LO ) +. +. +.TP +.B LetCN +\[lq]CONFIDENTIAL\[rq] +(see +.BR LO ) +. +. +.TP +.B Letdate +\[lq]Date\[rq] +(see +.BR AV ) +. +. +.TP +.B Letns +is a group of strings structuring the notations produced by +.BR NS . +. +If the +.I code +argument to +.B NS +has no corresponding string, +the notation is included between parentheses, +prefixed with +.BR Letns!copy , +and suffixed with +.BR Letns!to . +. +Observe the spaces after \[lq]Copy\[rq] and before \[lq]to\[rq]. +. +. +.RS +.P +.TS +tab(@); +Lb Lb Lb +L L L. +NS code@String@Contents +0@Letns!0@Copy to +1@Letns!1@Copy (with att.\&) to +2@Letns!2@Copy (without att.\&) to +3@Letns!3@Att. +4@Letns!4@Atts. +5@Letns!5@Enc. +6@Letns!6@Encs. +7@Letns!7@Under separate cover +8@Letns!8@Letter to +9@Letns!9@Memorandum to +10@Letns!10@Copy (with atts.\&) to +11@Letns!11@Copy (without atts.\&) to +12@Letns!12@Abstract Only to +13@Letns!13@Complete Memorandum to +14@Letns!14@CC +\[em]@Letns!copy@Copy \fI(with trailing space)\fP +\[em]@Letns!to@ to \fI(note leading space)\fP +.TE +.RE +. +. +.TP +.B Letnsdef +Select the notation format used by +.B NS +when it is given no argument. +. +The default is +.RB \[lq] 0 \[rq]. +. +. +.TP +.B LetRN +\[lq]In reference to:\[rq] +(see +.BR LO ) +. +. +.TP +.B LetSA +\[lq]To Whom It May Concern:\[rq] +(see +.BR LO ) +. +. +.TP +.B LetSJ +\[lq]SUBJECT:\[rq] +(see +.BR LO ) +. +. +.TP +.B Lf +\[lq]LIST OF FIGURES\[rq] +. +. +.TP +.B Licon +\[lq]CONTENTS\[rq] +. +. +.TP +.B Liec +\[lq]Equation\[rq] +. +. +.TP +.B Liex +\[lq]Exhibit\[rq] +. +. +.TP +.B Lifg +\[lq]Figure\[rq] +. +. +.TP +.B Litb +\[lq]TABLE\[rq] +. +. +.TP +.B Lt +\[lq]LIST OF TABLES\[rq] +. +. +.TP +.B Lx +\[lq]LIST OF EXHIBITS\[rq] +. +. +.TP +.BR MO1 \|.\|.\|.\| MO12 +\[lq]January\[rq] through \[lq]December\[rq] +. +. +.TP +.B Qrf +\[lq]See chapter \[rs]\[rs]*[Qrfh], +page \[rs]\[rs]n[Qrfp].\[rq] +. +. +.TP +.B Rf +interpolates an automatically numbered reference mark; +the number is used by the next +.B RS +call. +. +In +.I troff +mode, +the marker is superscripted; +in +.I nroff +mode, +it is surrounded by square brackets. +. +. +.TP +.B Rp +\[lq]REFERENCES\[rq] +. +. +. +.TP +.B Sm +interpolates +.if c \[u2120] \[u2120], +the service mark sign. +. +. +.TP +.B Tcst +interpolates an indicator of the +.B TC +macro's processing status. +. +If +.B TC +is not operating, +it is empty. +. +User-defined +.B TP +or +.B EOP +macros might condition page headers or footers on its contents. +. +. +.IP +.TS +tab(@); +lb lb +l l. +Value@Meaning +co@Table of contents +fg@List of figures +tb@List of tables +ec@List of equations +ex@List of exhibits +ap@Appendix +.TE +. +. +.TP +.B Tm +interpolates +.if c \[tm] \[tm], +the trade mark sign. +. +. +.TP +.B Verbnm +supplies argument(s) to the +.B nm +request employed by the +.B VERBON +macro. +. +The default is\~\[lq]1\[rq]. +. +. +.br +.ne 4v +.\" ==================================================================== +.SH Registers +.\" ==================================================================== +. +Default register values, +where meaningful, +are shown in parentheses. +. +Many are also marked as Boolean-valued, +meaning that they are considered \[lq]true\[rq] +(on, +enabled) +when they have a positive value, +and \[lq]false\[rq] +(off, +disabled) +otherwise. +. +. +.TP +.B .mgm +indicates that +.I groff mm +is in use +(Boolean-valued; +.BR 1 ). +. +. +.TP +.B :p +is an auto-incrementing footnote counter; +see +.BR FS . +. +. +.TP +.B :R +is an auto-incrementing reference counter; +see +.BR RS . +. +. +.TP +.B Aph +formats an appendix heading +(and title, +if supplied); +see +.B APP +(Boolean-valued; +.BR 1 ). +. +. +.TP +.B Au +includes supplemental author information +(the third and subsequent arguments to +.BR AU ) +in memorandum \[lq]from\[rq] information; +see +.B COVER +and +.B MT +(Boolean-valued; +.BR 1 ). +. +. +.TP +.B Cl +sets the threshold for inclusion of headings in a table of contents. +. +Headings at levels above this value are excluded; +see +.B H +and +.B TC +.RB ( 2 ). +. +The +.B Cl +register controls whether a heading is +.I saved +for output in the table of contents at the time +.B H +or +.B HU +is called; +if you change +.BR Cl 's +value immediately prior to calling +.BR TC , +you are unlikely to get the result you want. +. +. +.TP +.B Cp +suppresses page breaks before lists of captioned +equations, +exhibits, +figures, +and tables, +and before an index; +see +.BR EC , +.BR EX , +.BR FG , +.BR TB , +and +.B INDP +(Boolean-valued; +.\" DWB 3.3's manual said this was 1, but the code said 0. +.BR 0 ). +. +. +.TP +.B D +produces debugging information for the +.I mm +package on the standard error stream. +. +A value of\~0 outputs nothing; +1\~reports formatting progress. +. +Higher values communicate internal state information of increasing +verbosity +.RB ( 0 ). +. +. +.TP +.B De +causes a page break after a floating display is output; +see +.B DF +(Boolean-valued; +.BR 0 ). +. +. +.TP +.B Df +configures the behavior of +.BR DF . +. +The following values are recognized; +4 and 5 do not override the +.B De +register +.RB ( 5 ). +. +. +.IP +.TS +tab(@); +Lb Lb +L Lx. +Value@Effect +0@T{ +Flush pending displays +at the end of each section +when section-page numbering is active, +otherwise at the end of the document. +T} +1@T{ +Flush a pending display +on the current page or column +if there is enough space, +otherwise at the end of the document. +T} +2@T{ +Flush one pending display +at the top of each page or column. +T} +3@T{ +Flush a pending display +on the current page or column +if there is enough space, +otherwise at the top of the next. +T} +4@T{ +Flush as many pending displays +as possible in a new page or column. +T} +5@T{ +Fill columns or pages with flushed displays +until none remain. +T} +.TE +. +. +.TP +.B Ds +puts vertical space in the amount of register +.B Dsp +(if defined) or +.B Lsp +before and after each static display; +see +.B DS +(Boolean-valued; +.BR 1 ). +. +. +.TP +.B Dsp +configures the amount of vertical space placed +before and after static displays; +see +.B DS +and register +.B Ds +.RI ( undefined ). +. +. +.TP +.B Ec +is an auto-incrementing equation counter; +see +.BR EC . +. +. +.TP +.B Ej +sets the threshold for page breaks (ejection) prior to the format of +headings. +. +Headings at levels above this value are set on the same page and column +if possible; +see +.B H +.RB ( 0 ). +. +. +.TP +.B Eq +aligns an equation label to the left of a display instead of the right +(Boolean-valued; +.BR 0 ). +. +. +.TP +.B Ex +is an auto-incrementing exhibit counter; +see +.BR EX . +. +. +.TP +.B Fg +is an auto-incrementing figure counter; +see +.BR FG . +. +. +.TP +.B Fs +is multiplied by register +.B Lsp +to vertically separate footnotes; +see +.B FS +.RB ( 1 ). +. +. +.TP +.BR H1 \|.\|.\|.\| H14 +are auto-incrementing counters corresponding to each heading level; +see +.BR H . +. +. +.\" XXX: This could be generalized to an "Hdot" threshold register with +.\" a default of 2. +.TP +.B H1dot +appends a period to the number of a level one heading; +see +.B H +(Boolean-valued; +.BR 1 ). +. +. +.\" XXX: This may be insufficiently general; see Savannah #62825. +.TP +.B H1h +is a copy of +A copy of register +.RB register\~ H1 , +but it is incremented just before a page break. +. +This can be useful in user-defined macros; +see +.B H +and +.BR HX . +. +. +.TP +.B Hb +sets the threshold for breaking the line after formatting a heading. +. +Text after headings at levels above this value are set on the same +output line if possible; +see +.B H +.RB ( 2 ). +. +. +.TP +.B Hc +sets the threshold for centering a heading. +. +Headings at levels above this value use the prevailing alignment +(that is, +they are not centered); +see +.B H +.RB ( 0 ). +. +. +.TP +.B Hi +configures the indentation of text after headings. +. +It does not affect \[lq]run-in\[rq] headings. +. +The following values are recognized; +see +.B H +and +.B P +.RB ( 1 ). +. +. +.IP +.TS +tab(@); +Lb Lb +L Lx. +Value@Effect +0@no indentation +1@indent per the paragraph type +2@indent to align with heading title +.TE +. +. +.TP +.B Hps +sets the heading level threshold for application of preceding vertical +space; +see +.BR H . +. +Headings at levels above the value in register +.B Hps +use the amount of space in register +.BR Hps1 ; +otherwise that in +.BR Hps2 . +. +The value of +.B Hps +should be strictly greater than that of +.B Ej +.RB ( 1 ). +. +. +.TP +.B Hps1 +configures the amount of vertical space preceding a heading above the +.B Hps +threshold; +see +.B H +.RI ( troff +devices: +.BR 0.5v ; +.I nroff +devices: +.BR 1v ). +. +. +.TP +.B Hps2 +configures the amount of vertical space preceding a heading at or below +the +.B Hps +threshold; +see +.B H +.RI ( troff +devices: +.BR 1v ; +.I nroff +devices: +.BR 2v ). +. +. +.TP +.B Hs +sets the heading level threshold for application of succeeding vertical +space. +. +If the heading level is greater than +.BR Hs , +the heading is followed by vertical space in the amount of +.RB register\~ Hss ; +see +.B H +.RB ( 2 ). +. +. +.TP +.B Hss +is multiplied by register +.B Lsp +to produce vertical space after headings above the +threshold in +.RB register\~ Hs ; +see +.B H +.RB ( 1 ). +. +. +.TP +.B Ht +suppresses output of heading level counters above the lowest when the +heading is formatted; +see +.B H +(Boolean-valued; +.BR 0 ). +. +. +. +.TP +.B Hu +sets the heading level used by unnumbered headings; +see +.B HU +.RB ( 2 ). +. +. +.TP +.B Hy +enables automatic hyphenation of words +(Boolean-valued; +.BR 0 ). +. +. +.TP +.B Iso +configures the use of ISO\~8601 date format +if specified +(with any value) +on the command line; +see +.BR ISODATE . +. +The default is determined by localization files. +. +. +.TP +.B L +defines the page length for the document, +and must be set from the command line. +. +A scaling unit should be appended. +. +The default is that of the selected +.I groff +output device. +. +. +.TP +.B Le +.TQ +.B Lf +.TQ +.B Lt +.TQ +.B Lx +configure the report of lists of equation, +figure, +table, +and exhibit captions, +respectively, +after a table of contents; +see +.B TC +(Boolean-valued; +.BR Le :\~ 0 ; +.BR Lf , +.BR Lt , +.BR Lx :\~ 1 ). +. +. +.\" XXX: What is the rationale for this feature? +.TP +.B Letwam +sets the maximum number of input lines permitted in a writer's address; +see +.B WA +and +.B WE +.RB ( 14 ). +. +. +.TP +.B Li +configures the amount of indentation in ens applied to list items; +see +.B LI +.RB ( 6 ). +. +. +.TP +.B Limsp +inserts a space between the prefix and the mark +in automatically numbered lists; +see +.B AL +(Boolean-valued; +.BR 1 ). +. +. +.TP +.B Ls +sets a threshold for placement of vertical space before list items. +. +If the list nesting level is greater than this value, +no such spacing occurs; +see +.B LI +.RB ( 99 ). +. +. +.TP +.B Lsp +configures the base amount of vertical space used for separation +in the document. +. +.I mm +applies this spacing to many contexts, +sometimes with multipliers; +see +.BR DS , +.BR FS , +.BR H , +.BR LI , +and +.B P +.RI ( troff +devices: +.BR 0.5v ; +.I nroff +devices: +.BR 1v ). +. +. +.TP +.B N +configures the header and footer placements used by +.BR PH . +. +The default footer is empty. +. +If \[lq]section-page\[rq] numbering is selected, +the default header becomes empty +and the default footer becomes +.RI \[lq] x - y \[rq], +where +.IR x \~is +is the section number +(the number of the current first-level heading) +.RI and\~ y +the page number within the section. +.\" XXX: section-figure numbering needs more documentation. +. +The following values are recognized; +for finer control, +see +.BR PH , +.BR PF , +.BR EH , +.BR EF , +.BR OH , +and +.BR OF , +and registers +.B Sectf +and +.BR Sectp . +. +Value 5 is a GNU extension +.RB ( 0 ). +. +. +.IP +.TS +tab(@); +Lb Lb +L Lx. +Value@Effect +0@Set header on all pages. +1@Move header to footer on page 1. +2@Omit header on page 1. +3@Use \[lq]section-page\[rq] numbering style on all pages. +4@Omit header on all pages. +5@T{ +Use \[lq]section-page\[rq] and \[lq]section-figure\[rq] \ +numbering style on all pages. +T} +.TE +. +. +.TP +.B Np +causes paragraphs after first-level headings (only) to be numbered +in the format +.IR s . p , +where +.IR s \~is +is the section number +(the number of the current first-level heading) +and +.IR p \~is +the paragraph number, +starting at 1; +see +.B H +and +.B P +(Boolean-valued; +.BR 0 ). +. +. +.TP +.B O +defines the page offset of the document, +and must be set from the command line. +. +A scaling unit should be appended. +. +The default +.RB is\~ \&.75i +on terminal devices. +. +On typesetters, +it is +.B \&.963i +or set to +.B 1i +by the +.I papersize.tmac +package; +see +.MR groff_tmac @MAN5EXT@ . +. +. +.TP +.B Oc +suppresses the appearance of page numbers in the table of contents; +see +.B TC +(Boolean-valued; +.BR 0 ). +. +. +.\" XXX: This really should just be a string, shouldn't it? +.TP +.B Of +selects a separator format within equation, +exhibit, +figure, +and table captions; +see +.BR EC , +.BR EX , +.BR FG , +and +.BR TB . +. +The following values are recognized; +the spaces shown are unpaddable +.RB ( 0 ). +. +. +.IP +.TS +tab(@); +Lb Lb +L Lx. +Value@Effect +0@\[dq]. \[dq] +1@\[dq] \[em] \[dq] +.TE +. +. +.TP +.B P +interpolates the current page number; +it is the same as +.RB register\~ % +except when +\[lq]section-page\[rq] numbering is enabled. +. +. +.TP +.B Pi +configures the amount of indentation in ens applied to the first line of +a paragraph; +see +.B P +.RB ( 5 ). +. +. +.TP +.B Pgps +causes the type size and vertical spacing set by +.B S +to apply to headers and footers, +overriding the +.B HP +string. +. +If not set, +.B S +calls affect headers and footers only when followed by +.BR PH , +.BR PF , +.BR OH , +.BR EH , +.BR OF , +or +.B OE +calls +(Boolean-valued; +.BR 1 ). +. +. +.TP +.B Ps +is multiplied by register +.B Lsp +to vertically separate paragraphs; +see +.B P +.RB ( 1 ). +. +. +.TP +.B Pt +determines when a first-line indentation is applied to a paragraph; +see +.B P +.RB ( 0 ). +. +. +.IP +.TS +tab(@); +Lb Lb +L Lx. +Value@Effect +0@never +1@always +2@T{ +always, +except immediately after +.BR H , +.BR DE , +or +.B LE +T} +.TE +. +. +.TP +.B Ref +is used internally to control +.MR mmroff 1 's +two-pass approach to index and reference management; +see +.B INITI +and +.B RS +(Boolean-valued; +.BR 0 ). +. +. +.\" XXX: Why is this not named `Rpej`? +.TP +.B Rpe +configures the default page ejection policy for reference pages; +see +.B RP +.RB ( 0 ). +. +. +.IP +.TS +tab(@); +Lb Lb +L Lx. +Value@Effect +0@Break the page before and after the list of references. +1@Suppress page break after the list. +2@Suppress page break before the list. +3@Suppress page breaks before and after the list. +.TE +. +. +.TP +.B S +defines the type size for the document, +and must be set from the command line. +. +A scaling unit should be appended; +.B p +is typical +.RB ( 10p ). +. +. +.TP +.B Sectf +selects the \[lq]section-figure\[rq] numbering style. +. +Its default +.RB is\~ 0 +unless +.RB register\~ N +is set +.RB to\~ 5 +at the command line +(Boolean-valued). +. +. +.TP +.B Sectp +selects the \[lq]section-page\[rq] numbering style. +. +Its default +.RB is\~ 0 +unless +.RB register\~ N +is set +.RB to\~ 3 +.RB or\~ 5 +at the command line +(Boolean-valued). +. +. +.TP +.B Si +configures the amount of display indentation in ens; +see +.B DS +.RB ( 5 ). +. +. +.TP +.B Tb +is an auto-incrementing table counter; +see +.BR TB . +. +. +.TP +.B V +defines the vertical spacing for the document, +and must be set from the command line. +. +A scaling unit should be appended; +.B p +is typical. +. +The default vertical spacing is 120% of the type size. +. +. +.TP +.B Verbin +configures the amount of indentation for verbatim displays +when indentation is selected; +see +.B \%VERBON +.RB ( 5n ). +. +. +.TP +.B W +defines the \[lq]width\[rq] +of the document +(that is, +the length of an output line with no indentation); +it must be set from the command line. +. +A scaling unit should be appended. +. +The default +.RB is\~ 6i +or assigned by the +.I papersize.tmac +package; +see +.MR groff_tmac @MAN5EXT@ . +. +. +. +.\" ==================================================================== +.SH Internals +.\" ==================================================================== +. +The +.B LT +letter macros call further macros depending on the letter type, +with which they are suffixed. +. +It is therefore possible to define additional letter types, +either in the territory-specific macro file, +or as local additions. +. +.B LT +sets the registers +.B Pt +and +.B Pi +to 0 and\~5, \" XXX: ...but doesn't use Pi for indentation... +respectively. +.\" XXX: and why aren't both of these actions the responsibility of +.\" let@init_type as described below? +. +The following macros must be defined to support a new letter type. +. +. +.TP +.BI let@init_ type +.B LT +calls this macro to initialize any registers and other data needed by +the letter type. +. +. +.TP +.BI let@head_ type +formats the letterhead; +it is called instead of the usual page header macro. +. +Its definition should remove the alias +.B let@header +unless the letterhead is desired on subsequent pages. +. +. +.TP +.BI let@sg_ type\~\c +.IR "name title n is-final\~" [ SG-arg\~ .\|.\|.] +.B SG +calls this macro only for letters; +.B MT +memoranda have their own signature processing. +. +.I name +and +.I title +are specified through +.BR WA / WE . +. +.IR n \~is +the index of the +.IR n th +writer, +and +.I is-final +is true for the last writer to be listed. +. +Further +.B SG +arguments are appended to the signature line. +. +. +.TP +.BI let@fc_ "type closing" +This macro is called by +.BR FC , +and has the formal closing as the argument. +. +. +.P +.B LO +implements letter options. +. +It requires that a string named +.BI Let type +be defined, +where +.I type +is the letter type. +. +.B LO +then assigns its second argument +.RI ( value ) +to the string +.BI let*lo\- type\c +\&. +. +. +.\" ==================================================================== +.\".SH BUGS +.\" ==================================================================== +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I @MACRODIR@/@TMAC_M_PREFIX@m.tmac +is the +.I groff +implementation of the memorandum macros. +. +. +.TP +.I @MACRODIR@/mm.tmac +is wrapper to load +.IR m.tmac . +. +. +.TP +.I @MACRODIR@/refer\-mm.tmac +implements +.MR @g@refer @MAN1EXT@ +support for +.IR mm . +. +. +.TP +.I @TMAC_MDIR@/ms.cov +implements an +.IR ms -like +cover sheet. +. +. +.TP +.I @TMAC_MDIR@/0.MT +implements memorandum types 0\[en]3 and 6. +. +. +.TP +.I @TMAC_MDIR@/4.MT +implements memorandum type 4. +. +. +.TP +.I @TMAC_MDIR@/5.MT +implements memorandum type 5. +. +. +.TP +.I @TMAC_MDIR@/locale +performs any (further) desired necessary localization; +empty by default. +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +The GNU version of the +.I mm +macro package was written by +.MT jh@\:axis\:.se +J\[:o]rgen H\[:a]gg +.ME +of Lund, Sweden. +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.UR https://tkurtbond\:.github\:.io/\:troff/\:mm\-all\:.pdf +.I MM \- A Macro Package for Generating Documents +.UE , +the DWB\~3.3 +.I mm +manual, +introduces the package but does not document GNU extensions. +. +. +.P +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the primary +.I groff +manual. +. +You can browse it interactively with \[lq]info groff\[rq]. +. +. +.P +.MR groff @MAN1EXT@ , +.MR @g@troff @MAN1EXT@ , +.MR @g@tbl @MAN1EXT@ , +.MR @g@pic @MAN1EXT@ , +.MR @g@eqn @MAN1EXT@ , +.MR @g@refer @MAN1EXT@ , +.MR groff_mmse @MAN7EXT@ +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_mm_7_man_C] +.do rr *groff_groff_mm_7_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: |