diff options
Diffstat (limited to 'contrib/mm/groff_mm.7.man')
| -rw-r--r-- | contrib/mm/groff_mm.7.man | 1320 |
1 files changed, 754 insertions, 566 deletions
diff --git a/contrib/mm/groff_mm.7.man b/contrib/mm/groff_mm.7.man index b39931842..7cda01b09 100644 --- a/contrib/mm/groff_mm.7.man +++ b/contrib/mm/groff_mm.7.man @@ -597,7 +597,7 @@ to the table of contents with which is either\~0 or in the range 1 to\~7. . See also -.BR .H . +.BR H . . This undocumented DWB .I mm @@ -608,12 +608,13 @@ to enable customized tables of contents. . .TP .BR 1C\~ [ 1 ] -Begin one-column formatting after breaking the page. +Format page text in one column. +. +The page is broken. . .RB A\~ 1 -argument suppresses the page break, -but if a footnote is pending, -it may be overprinted. +argument suppresses this break; +its use may cause body text and a pending footnote to overprint. . See .BR 2C , @@ -644,19 +645,35 @@ 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 -.BI AF\ \fR[\fP name-of-firm \fR]\fP -Author's firm, should be called before -.BR AU , -see also -.BR \%COVER . +.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 -.BI AL\~ \fR[\fPtype\~\fR[\fPtext-indent\~ \fR[\fP1\fR]]]\fP -Start an auto-incrementing list. +.BR AL \~[\c +.IR type \~[ text-indent \~[\c +.BR 1 ]]] +Begin an auto-incrementing numbered list. . -Items are numbered beginning with one. +Item numbers start at one. . The .I type @@ -671,16 +688,13 @@ An explicitly empty .I type also indicates the default. . +A .I text-indent -sets the indentation in ens, -overriding register +argument overrides register .BR Li . . -If a third argument, -conventionally -.BR 1 , -is given, -the blank line that normally precedes each list item is suppressed. +A third argument suppresses the blank line that normally precedes each +list item. . Use .B LI @@ -833,19 +847,32 @@ The default is \[lq]ABSTRACT\[rq]. .TP .BI AT\~ title\c \~[.\|.\|.] -Author's title(s). +Specify author's title(s). . If present, .B AT must appear just after the corresponding author's .BR AU . . -Each title shows up on a separate output line after the name in the -signature block and in the +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. +cover sheet style also uses it. . . +.br +.ne 7v .TP .BR AU \~\c .RI [ name\~\c @@ -860,20 +887,23 @@ cover sheet style. Specify author. . .B AU -terminates a document title being collected with +terminates a document title started with .BR TL , -and can be called without arguments for that sole purpose. +and can be called without arguments for that purpose. . -Author information is used by cover sheets and predefined memorandum -types -.RB ( MT ). +Author information is used by cover sheets, +.B MT +memoranda, +and +.BR SG . . -It can contain initials, +Further arguments comprise +initials, location, department, telephone extension, room number or name, -and up to three additional arguments. +and up to three additional items. . Repeat .B AU @@ -888,25 +918,37 @@ instead to identify the author for documents employing . . .TP -.BI AV\ \fR[\fPname\ \fR[\fP1\fR]]\fP -Approval signature. +.BR AV \~[\c +.IR name \~[\c +.BR 1 ]] +Format approval lines for a handwritten signature and date. . -Generates an approval line with place for signature and date. +Two horizontal rules are drawn, +with the specified +.I name +and the text of the string +.B Letdate +beneath them. . -The text \[lq]APPROVED:\[rq] can be changed with the string -.BR Letapp ; -it is replaced with an empty line if there is a second argument. +Above these rules, +the text in the string +.B Letapp +is formatted; +a second argument replaces this text with a blank line. . -The text \[lq]Date\[rq] can be changed with the string -.BR Letdate . +See +.BR LT . . . .\" XXX: AVL is misnamed; it should have been called SGL or similar. .TP -.BI AVL\ \fR[\fPname\fR]\fP -Letter signature. -. -Generates a line with place for signature. +.BR AVL \~[\c +.IR name ] +As +.BR AV , +but the date, +date rule, +and approval notations are omitted. . . .TP @@ -945,7 +987,7 @@ This is a GNU extension. . .TP .B BE -End bottom block, see +End bottom block; see .BR BS . . . @@ -962,19 +1004,26 @@ without space between the arguments. . . .TP -.BI BL\ \fR[\fPtext-indent\ \fR[\fP1\fR]]\fP -Start bullet list. +.BR BL \~[\c +.IR text-indent \~[\c +.BR 1 ]] +Begin bulleted list. . -Initializes a list with a bullet and a space in the beginning of each -list item (see -.BR LI ). +Items are prefixed with a bullet and a space. . +A .I text-indent -sets the indentation in ens, -overriding register +argument overrides register .BR Pi . . -A third argument prohibits printing of a blank line before each item. +A second argument suppresses blank lines between items. +. +Use +.B LI +to declare list items, +and +.B LE +to end the list. . . .TP @@ -991,41 +1040,51 @@ without space between the arguments. . .TP .B BS -Bottom block start. +Begin bottom block. . -Begins the definition of a text block which is printed at the bottom -of each page. +Input is collected until +.B BE +is called, +and output between the footnote area and footer of each page. . -The block ends with -.BR BE . . +.\" XXX: Couldn't this have been done with an extra parameter to `VL`? .TP -.BI BVL\ "text-indent \fR[\fPmark-indent\ " \fR[\fP1\fR]]\fP -Start of broken variable-item list. +.BR BVL \~[\c +.IR text-indent \~[ mark-indent \~[\c +.BR 1 ]]] +Begin broken variable-item list. . -Broken variable-item list has no fixed mark, -it assumes that every -.B LI -has a mark instead. +Each item is expected to supply its own mark. . -The text always begins at the next line after the mark. +The line is always broken after the mark; +contrast +.BR VL . . .I text-indent -sets the indentation to the text, and +sets the indentation of the text, +and .I mark-indent -the distance from the current indentation to the mark. +the distance from the current list indentation to the mark. +. +A third argument suppresses the blank line that normally precedes each +list item. . -A third argument prohibits printing of a blank line before each 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 sheet description. +Begin a cover page description. . -It is important that .B \%COVER -appear before any of the body text +must appear before the body text (or main matter) of a document. . @@ -1037,25 +1096,31 @@ and load it with the .B mso request. . -Therefore it is possible to create unlimited types of cover sheets. -. The default .I style is .BR ms ; -it structures a cover sheet to resemble that used by the +the +.I ms.cov +file prepares a cover page resembling those of the .I ms package. . -.B \%COVER -requires a +A +.I .cov +file must define a .B \%COVEND -at the end of the cover description. +macro, +which a document must call at the end of the cover description. . -Always use the following ordering of the cover sheet macros. +Use cover description macros in the following order; +only +.B TL +and +.B AU +are required. . . -.RS .IP .EX \&.COVER @@ -1067,22 +1132,11 @@ Always use the following ordering of the cover sheet macros. \&.AE \&.COVEND .EE -.RE -. -. -.IP -Only -.B .TL -and -.B .AU -are required. . . .TP .B COVEND -End the cover description and output the cover page. -. -This macro is defined in the cover sheet macro file. +End the cover description. . . .TP @@ -1097,58 +1151,63 @@ or . .TP .BR DF\~ [\c -.IR format \~[ fill \~[ rindent ]]] +.IR format \~[ fill \~[ right-indentation ]]] Begin floating display. . -A floating display is saved in a queue and is printed in the order -entered. +A floating display is saved in a queue and output in the order entered. . -The arguments -.I format, -.I fill, -and -.I rindent -are handled as in +Arguments are handled as in .BR DS . . Floating displays cannot be nested. . -Floating display output is controlled by the registers +Placement of floating displays is controlled by the registers .B De and .BR Df . . . .TP -.BI DL\ \fR[\fPtext-indent\ "\fR[\fP\fB1\fP \fR[\fP\fB1\fP\fR]]]\fP" -Dash list start. +.BR DL \~[\c +.IR text-indent \~[\c +.BR 1 ]] +Begin dashed list. . -Begins a list where each item is printed after a dash. +Items are prefixed with an em dash and a space. . +A .I text-indent -sets the indentation in ens, -overriding register +argument overrides register .BR Pi . . -A second argument prevents an empty line between each list item. +A second argument suppresses blank lines between items. . -See -.BR LI . +Use +.B LI +to declare list items, +and +.B LE +to end the list. . -A third argument prohibits printing of a blank line before each item. . .TP -.BI DS\ "\fR[\fPformat \fR[\fPfill \fR[\fPrindent\fR]]]\fP" -Static display start. +.BR DS \~[\c +.IR format \~[\c +.IR fill \~[\c +.IR right-indentation ]]] +Begin static display. . -Begins collection of text until -.BR DE . +Input until +.B DE +is called is collected into a display. . -The text is printed together on the same page, unless it is longer -than the height of the page. +The display is output on a single page unless it is taller than the +height of the page. . .B DS -can be nested arbitrarily. +can be nested +(contrast with +.BR DF ). . . .IP @@ -1157,13 +1216,11 @@ tab(@); Lf(BI) Lb L Lx. format@Effect -\[dq]\[dq]@No indentation. -none@No indentation. -L@No indentation. +\f[I]none\f[]@Do not indent the display. +L@Do not indent the display. I@T{ Indent text by -.B \[rs]n[Si] -ens. +.BR \[rs]n[Si] . T} C@Center each line. CB@Center the whole display as a block. @@ -1182,7 +1239,8 @@ and \[lq]CB\[rq] can also be specified as \[lq]0\[rq], and \[lq]3\[rq], respectively, -for compatibility reasons. +for compatibility with +.RI DWB\~ mm. . . .IP @@ -1191,27 +1249,34 @@ tab(@); Lf(BI) Lb L Lx. fill@Effect -\[dq]\[dq]@Line-filling turned off. -none@Line-filling turned off. -N@Line-filling turned off. -F@Line-filling turned on. +\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. +respectively, +for compatibility with +.RI DWB\~ mm. +. . .IP -By default, an empty line is printed before and after the display. +A third argument +reduces the line length by +.I right-indentation. . -Setting register -.B Ds -to\~0 prevents this. . -.I rindent -shortens the line length by that amount. +.IP +.I mm +normally +places blank lines before and after the display. +. +Set register +.B Ds +to\~0 to suppress these. . . .TP @@ -1349,17 +1414,19 @@ without any trap active. See .BR TP . . +. .IP -.B Strings available to EOP -.RS .TS tab(@); -l l. -EOPf@argument of \fBPF\fP -EOPef@argument of \fBEF\fP -EOPof@argument of \fBOF\fP +Cb S +Lb L. +Strings available to EOP +_ +EOPf@argument to \fBPF\fP +EOPef@argument to \fBEF\fP +EOPof@argument to \fBOF\fP .TE -.RE +. . .TP .BI EPIC\ "\fR[\fP\fB\-L\fP\fR]\fP width height \fR[\fPname\fR]\fP" @@ -1404,7 +1471,7 @@ and not to produce output. . If present, .I label -appears at the aligned to the right and +appears aligned to the right and centered vertically within the display; see register .BR Eq . @@ -1454,32 +1521,38 @@ as a heading. . . .TP -.BI FC\ \fR[\fPclosing\fR]\fP -Print \[lq]Yours very truly,\[rq] -as a formal closing of a letter or memorandum. -. -The argument replaces the default string. +.BR FC \~[\c +.IR closing-text ] +Output the string +.BR Letfc , +or the specified +.I closing-text, +as the formal closing of a letter. . -The default is stored in the string -.BR Letfc . . .TP -.BI FD\ \fR[\fParg\ \fR[\fP1\fR]]\fP -Footnote default format. +.BR FD \~[\c +.IR arg \~[\c +.BR 1 ]] +Configure display of footnotes. . -Controls the hyphenation (hyphen), -adjustment to the right margin (adjust), -and indentation of footnote text (indent). +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. . -It can also change the label justification (ljust). . -.RS +.br +.ne 5v .IP +.\" XXX: We can fit one more row using "nokeep" vs. not using it. .TS -tab(@); -lb lb lb lb lb -l l l l l. -arg@hyphen@adjust@indent@ljust +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 @@ -1493,19 +1566,33 @@ arg@hyphen@adjust@indent@ljust 10@no@no@yes@right 11@yes@no@yes@right .TE -.RE +. . .IP -An argument greater than or equal to 11 is considered as value\~0. +An +.I arg +greater than 11 is treated +.RB as\~ 0 . . -The default for -.I mm -is 10. +.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 -Footnote end; +End footnote; see .BR FS . . @@ -1547,9 +1634,9 @@ as a heading. .TP .BR FS \~[\c .IR label ] -Footnote start. +Start footnote. . -Text until +Input until .B FE is called is collected into a footnote. . @@ -1679,12 +1766,17 @@ Set a numbered section heading at .IR level . . .I mm -produces numbered headings in the form +produces numbered +.I "heading marks" +of the form .IR a . b . c .\|.\|., with up to fourteen levels of nesting. . -The numbering of each level increases automatically and is -reset to zero when a more significant level is specified. +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. @@ -1938,7 +2030,7 @@ calls .B HY after determing the header typeface and size. . -It might be used to change indentation. +It could be used to change indentation. . . .TP @@ -1953,7 +2045,7 @@ or .B HU returns. . -It might be used to change the page header to include a section heading. +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 @@ -1998,17 +2090,6 @@ it is treated as a numbered heading of the level stored in . . .TP -.B HX -.TQ -.B HY -.TQ -.B HZ -See -.B H -for descriptions of these user-definable hooks. -. -. -.TP .BR I \~\c \" space in roman; we must use 2-font macro with \c .RI [ italic-text\~\c .RI [ previous-font-text ]]\~.\|.\|. @@ -2024,13 +2105,22 @@ switch font to italic style. . . .TP -.BI IA\ "\fR[\fPaddressee-name \fR[\fPtitle\fR]]\fP" -Begin specification of the addressee and addressee's address in -letter style. +.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. . -Several names can be specified with empty -.BR IA / IE -pairs, -but only one address. +The arguments give each recipient a name and title. . See .BR LT . @@ -2050,86 +2140,75 @@ without space between the arguments. . .TP .B IE -End the address specification after +End the inside address begun with .BR IA . . . .TP -.BI IND\ "arg1 \fR[\fParg2 \fR[.\|.\|.]]\fP" -Write a line in the index file selected by +.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. +. +The entry is arranged as configured by the most recent .B INITI -with all arguments and the page number or header mark separated by tabs. +call. . -.RS -.IP -.B Examples +Each +.I argument +is separated from its predecessor by a tab character. . -.IP -arg1\[rs]tpage number -.br -arg1\[rs]targ2\[rs]tpage number -.br -arg1\[rs]theader mark -.br -arg1\[rs]tpage number\[rs]theader mark -.RE . .TP .B INDP -Print the index by running the command specified by the string -.BR Indcmd , -which has -.RB \[lq] sort\~\-t\[rs]t \[rq] -as the default value. +Output the index set up by +.B INITI +and populated by +.B IND +calls +by running the command specified in the +.B Indcmd +string. . -.B INDP -reads the output from the command to form the index, -by default in two columns (this can be changed by defining -.BR TYIND ). +The index is preceded by a centered header interpolating the string +.BR INDEX . . -The index is printed with the string -.B Index -as header; -the default is \[lq]INDEX\[rq]. +The output of +.B Indcmd +is set in two columns; +afterwards, +single-column output is selected again. . -One-column processing is reactivated after the list. . -.B INDP -calls the user-defined macros -.BR TXIND , -.BR TYIND , -and -.B TZIND -if defined. +.IP +You can define macros to customize the foregoing behavior. . +.B INDP +calls .B TXIND -is called before printing the string \[lq]INDEX\[rq], +before the header, .B TYIND -is called instead of printing \[lq]INDEX\[rq], +.I instead +of writing the header, and .B TZIND -is called after the printing and should take care of restoring to -normal operation again. +after formatting the index to return to the prevailing page layout. . . .TP -.BI INITI\ "type filename \fR[\fPmacro\fR]\fP" -Initialize the new index system and set the filename to collect index -lines in with -.BR IND . +.BI INITI\~ "location-type file-name\~"\c +.RI [ macro ] +Initialize +.IR "groff mm" 's +indexing system. . Argument -.I type -selects the type of index: page number, header marks or both. -. -The default is page numbers. -. -.IP -It is also possible to create a macro that is responsible -for formatting each row; -just add the name of the macro as a third argument. -. -The macro is then called with the index as argument(s). +.I location-type +selects how the location of each index entry is reported. . . .IP @@ -2137,16 +2216,22 @@ The macro is then called with the index as argument(s). tab(@); Lf(BI) Lb L Lx. -type@entry format -N@Page numbers -H@Header marks -B@T{ -Both page numbers and header marks, -separated with a tab character. -T} +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. @@ -2214,49 +2299,53 @@ this is also the default. . . .TP -.BI LB\ "text-indent mark-indent pad type \fR[\fPmark \fR[\fPLI-space \fR[\fPLB-space\fR]]]\fP" -List-begin macro. -. -This is the common macro used for all lists. +.BI LB\~ "text-indent mark-indent pad type"\~\c +.RI [ mark \~[ pre-item-space \~[ pre-list-space ]]] +Begin list. . -.I text-indent -is the number of spaces to indent the text from the current indentation. -. -.IP -.I pad +The macros +.BR AL , +.BR BL , +.BR BVL , +.BR DL , +.BR ML , +.BR RL , and -.I mark-indent -control where to put the mark. +.B VL +call +.B LB +in various ways; +they are simpler to use and may be preferred if they suit the desired +purpose. . -The mark is placed within the mark area, and -.I mark-indent -sets the number of spaces before this area. . -By default it is\~0. +.IP +The nesting level of lists is tracked by +.I mm; +the outermost level is\~0. . -The mark area ends where the text begins. +The text of each list item is indented by +.I text-indent; +the default is taken from the +.B Li +register +(in ens). . -The start of the text is still controlled by -.IR text-indent . +Each item's mark is indented by +.I mark-indent; +the default is +.BR 0n . . -.IP -The mark is left-justified within the mark area if -.I pad -is\~0. +The mark is normally left-aligned. . If .I pad -is greater than\~0, +is greater than zero, .I mark-indent -is ignored, -and the mark is placed +is overridden such that .I pad -spaces before the text. -. -This right-justifies the mark. +ens of space follow the mark. . -. -.IP .I type selects one of six possible ways to display the mark. . @@ -2279,242 +2368,265 @@ type@Output for a mark \[lq]x\[rq] .IP If .I type -is\~0 the list either has a hanging indentation or, -if argument +is\~0 and .I mark -is given, -the string +is unspecified, +the items are set with a hanging indent. +. +Otherwise, .I mark -as a mark. +is interpreted as a string defining the mark. . -.IP If .I type -is greater than\~0 automatic numbering occurs, -using Arabic numerals if +is greater than zero, +items are automatically numbered; .I mark -is empty. +is interpreted as a register format. . -.I mark -can then be any of \[lq]1\[rq], -\[lq]A\[rq], -\[lq]a\[rq], -\[lq]I\[rq], -or \[lq]i\[rq]. +The default +.I type +.RB is\~ 0 . . . .IP -Every item in the list gets -.I LI-space -number of blank lines before them. -. -Default is\~1. +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 . . -.IP .B LB -itself prints -.I LB-space -blank lines. +precedes the list by +.I pre-list-space +multiplied by the register +.BR Lsp ; +the default +.RB is\~ 0 . . -Default is\~0. . .TP -.BI LC\ \fR[\fPlist-level\fR]\fP -List-status clear. +.BR LC \~[\c +.IR list-level ] +Clear list state. . -Terminates all current active lists down to -.IR list-level , -or\~0 if no argument is given. +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. . -This is used by\~\c .B H -to clear any active list. +calls +.B LC +automatically. . . .TP .BR LE \~[ 1 ] -List end. +End list. . The current list is terminated. . -If an argument -.B 1 -is present, +An argument +.RB of\~ 1 +causes vertical space in the amount of register .B Lsp -follows. +to follow the list. . . .TP -.BI LI\ \fR[\fPmark\ \fR[\fP1\fR|\fP2\fR]]\fP -List item preceding every item in a list. +.BR LI \~[\c +.IR mark \~[ item-mark-mode ]] +Begin a list item. . -Without argument, +Input is collected into a list item until the current list is terminated +or .B LI -prints the mark determined by the current list type. +is called again. . -By giving -.B LI -one argument, it uses that as the mark instead. +By default, +the item's text is preceded by any mark configured by the current list. . -Two arguments to -.B LI -makes +If only .I mark -a prefix to the current mark. -. -There is no separating space between the prefix and the mark if the -second argument is \[lq]2\[rq] instead of \[lq]1\[rq]. +is specified, +it replaces the configured mark. . -This behaviour can also be achieved by setting register -.B Limsp -to zero. -. -A zero length +When a second argument is supplied, .I mark -makes a hanging indentation instead. +is prefixed 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). . -.IP -A list item is preceded by vertical space unless its nesting level is -greater than the value of register -.BR Ls . +Also see register +.BR Limsp . . -The amount of space is determined by the register -.B Lsp -and an argument to -.BR LB . -. -. -.IP -The -.B Li -register configures the indentation amount in ens. -. -. -.IP -All lists begin with a list initialization macro, -.BR LB . -. -There are, however, seven predefined list types to make lists easier -to use. . -They all call -.B LB -with different default values. -. -.RS -.IP -.TS -tab(@); -l l. -\fBAL\fP@Automatically Incremented List -\fBML\fP@Marked List -\fBVL\fP@Variable-Item List -\fBBL\fP@Bullet List -\fBDL\fP@Dash List -\fBRL\fP@Reference List -\fBBVL\fP@Broken Variable List. -.TE -.RE +.TP +.BI LO\~ option\~\c +.RI [ value ] +Specify letter options; +see +.BR LT . . +Standard options are as follows. . -.TP -.BI LO\ "type \fR[\fParg\fR]\fP" -Specify options in letter (see -.BR .LT ). +See +.B IA +regarding the inside address and string +.B DT +regarding the date. . -This is a list of the standard options: . -.RS .IP .TS tab(@); -l lx. +Lf(BI) Lb +L Lx. +option@Effect AT@T{ -Attention. -Prints \[lq]ATTENTION:\[rq] and the argument below the inside address. -See also string -.BR LetAT . +Attention; +put contents of string +.B LetAT +and +.I value +left-aligned after the inside address. T} CN@T{ -Confidential notation. -Prints \[lq]CONFIDENTIAL\[rq] on the second line below the date line. -. -Any argument replaces \[lq]CONFIDENTIAL\[rq]. -. -See also string -.BR LetCN . +Confidential; +put +.I value, +or contents of string +.BR LetCN , +left-aligned after the date. T} RN@T{ -Reference notation. -Prints \[lq]In reference to:\[rq] and the argument two lines below the -date line. -. -See also string -.BR LetRN . +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. -Prints \[rq]To Whom It May Concern:\[rq] or the argument if it was -present. -. -The salutation is printed two lines below the inside address. -See also string -.BR LetSA . +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 line. -Prints the argument as subject prefixed with \[lq]SUBJECT:\[rq] -two lines below the inside address, -except in letter type \[lq]SP\[rq], -where the subject is printed in all-capital without any prefix. -See also string -.BR LetSJ . +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 -.RE . . -.TP -.BI LT\ \fR[\fIarg\/\fR]\fI -Format a letter in one of four different styles depending -on the argument. +.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. . -Also see section \[lq]Internals\[rq] below. . -.RS .IP .TS tab(@); -lb lb -l lx. -Arg@Style +Lf(BI) Lb +Lb Lx. +style@Description BL@T{ -Blocked. -Date line, return address, writer's address and closing -begins at the center of the line. +Blocked: +the writer's address, +date, +formal closing, +and signature are indented to the center of the line. . -All other lines begin at the left margin. +Everything else is left-aligned. T} SB@T{ -Semi-blocked. -Same as blocked, -except that the first line in every paragraph is indented five spaces. +Semi-blocked: +as +.BR BL , +but the first line of each paragraph is indented by +.BR 5n . +.\" XXX: 5m or 5n? T} FB@T{ -Full-blocked. -All lines begin at the left margin. +Fully blocked: +everything begins at the left margin. T} SP@T{ -Simplified. -As full-blocked, -but the salutation is replaced by a fully-capitalized subject, -any formal closing is omitted, -and the author's signature is presented on a single line in full -capitals. +Simplified: +as +.BR FB , +but a formal closing is omitted, +and the signature is set in full capitals. T} .TE -.RE . . .TP @@ -2652,9 +2764,10 @@ Begin alternative multi-column mode. All column widths must be specified, as must the amount of space between each column pair. . -The default unit for the width and space arguments is \[lq]n\[rq]. +The arguments' default scaling unit is +.BR n . . -.B .MULB +.B MULB uses a diversion and operates in a separate environment. . . @@ -2681,14 +2794,15 @@ Contrast with . . .TP -.BI ND\ new-date -New date. -. -Overrides the current date. +.BR ND \~[\c +.IR arg ] +Set the document's date. . -Date is not printed if -.I new-date -is an empty string. +.I mm +does not interpret +.IR arg ; +it can be a revision identifier +(or empty). . . .TP @@ -2700,35 +2814,50 @@ filling is enabled. . .TP .BI nP\ \fR[\fPtype\fR]\fP -Print numbered paragraph with header level two. +Begin a numbered paragraph at heading level two. . See -.BR .P . +.BR P . . . -.TP -.BI NS\ \fR[\fParg\ \fR[\fP1\fR]]\fP -Collect notations of the type specified by -.I arg +.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; -filling is disabled. +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 below, +each line of notations is formatted as +.RI "\[lq]Copy (" line ") to\[rq]." . If a second argument, conventionally .BR 1 , is given, -then the argument becomes the entire notation and +.I code +becomes the entire notation and .B NE is not necessary. . -If -.I arg -does not match one of the predefined types listed below, -the notations are prefixed with -.RI "\[lq]Copy (" arg ") to\[rq]." -. In .IR "groff mm" , you can set up further notations to be recognized by @@ -2740,14 +2869,13 @@ and below. . . -.RS .IP .TS tab(@); -l l. -\fBArg@Notation\fP -\fInone\/\fP@Copy To -\[dq]\[dq]@Copy To +Lf(BI) Lb +Lb L. +code@Notation +\f[I]none\f[]@Copy To 1@Copy To (with att.\&) to 2@Copy To (without att.\&) to 3@Att. @@ -2763,7 +2891,6 @@ l l. 13@Complete Memorandum to 14@CC .TE -.RE . . .TP @@ -2850,8 +2977,7 @@ and is\~1 by default (one blank line). .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 special formatting, -like letter heads and other. +This macro can be used for letterheads and similar. . It is normally the first macro call in a file, though it is not necessary. @@ -2873,12 +2999,10 @@ line length, page length, and page offset instead.) . .TP .B PGNH -No header is printed on the next page. -. -Used to get rid of the header in letters or other special texts. +Suppress header on the next page. . -This macro must be used before any text to inhibit the page header -on the first page. +This macro must be called before any macros that produce output to +affect the layout of the first page. . . .TP @@ -3009,14 +3133,6 @@ Picture start; see . . .TP -.B PX -Page header hook. -. -This macro is called just after the printing of the page header in -no-space mode. -. -. -.TP .B PY Picture end with flyback. . @@ -3098,14 +3214,26 @@ without space between the arguments. . .TP .BI RL\ \fR[\fPtext-indent \fR[\fP1\fR]]\fP -Reference list start. +Begin reference list. . -Begins a list where each item is preceded with an automatically -incremented number between square brackets. +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 third argument 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 @@ -3147,27 +3275,37 @@ The string contains the reference page caption. . . +.br +.ne 5v .TP -.BI RS\ \fR[\fPstring-name\fR]\fP +.BR RS \~[\c +.IR string-name ] Begin an automatically numbered reference definition. . -Put the string -.B \[rs]*(Rf +By default, +references are automatically 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 -at next new line after the reference mark. +on an input line after the reference mark. . -The reference number is stored in register -.BR :R . . -If +.IP +If the .I string-name -is given, a string with that name is defined and contains the current +argument is given, +.I "groff ms" +also defines a string with that identifier containing the current reference mark. . -The string can be referenced as +This string can interpolated as .BI \[rs]*[ string-name ] -later in the text. +subsequently. +. . .TP .BI S\ "\fR[\fPsize \fR[\fPspacing\fR]]\fP" @@ -3229,7 +3367,7 @@ is defined. . .I string is retrieved with -.BR .GETST . +.BR GETST . . See .BR INITR . @@ -3245,13 +3383,13 @@ first or last author. . The reference data is the location, department, and initials specified with -.BR .AU . +.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 . +.BR WA / WE . . See section \[lq]Internals\[rq] below. . @@ -3276,23 +3414,22 @@ blank except for any headers and footers, are printed. . . +.br +.ne 4v \" XXX: 3v should suffice .TP -.BI SM\ "string1 \fR[\fPstring2 \fR[\fPstring3\fR]]\fP" -Make a string smaller. -. -If -.I string2 -is given, -.I string1 -is made smaller and -.I string2 -stays at normal size, -concatenated with -.IR string1 . +.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. . -With three arguments, everything is concatenated, but only -.I string2 -is made smaller. . .TP .BI SP\ \fR[\fPlines\fR]\fP @@ -3505,11 +3642,14 @@ Argument \[lq]N\[rq] isn't implemented yet. .BR TL \~[\c .IR charging-case-number \~[\c .IR filing-case-number ]] -Begin collecting document title. +Begin document title. . -Text up to the next +Input is collected into the title until +.B AF +or .B AU -call is included in the title. +is called, +and output as directed by the cover page. . .I charging-case-number and @@ -3543,17 +3683,19 @@ Line length is preserved, though. See .BR EOP . . +. .IP -.B strings available to TP -.RS .TS tab(@); -l l. -TPh@argument of \fBPH\fP -TPeh@argument of \fBEH\fP -TPoh@argument of \fBOH\fP +Cb S +Lb L. +Strings available to TP +_ +TPh@argument to \fBPH\fP +TPeh@argument to \fBEH\fP +TPoh@argument to \fBOH\fP .TE -.RE +. . .TP .B TS \fR[\fPH\fR]\fP @@ -3573,14 +3715,6 @@ that the table has a header. See .BR TH . . -.TP -.B TX -.TQ -.B TY -See -.B TC -for descriptions of these user-definable hooks. -. . .TP .BR VERBON \~\c \" space in roman; we must use 2-font macro with \c @@ -3633,19 +3767,35 @@ End verbatim display. . . .TP -.BI VL\ "text-indent \fR[\fPmark-indent\ " \fR[\fP1\fR]]\fP -Variable-item list. +.BR VL \~[\c +.IR text-indent \~[ mark-indent \~[\c +.BR 1 ]]] +Begin variable-item list. . -It has no fixed mark, it assumes that every -.B LI -has a mark instead. +Each item is expected to supply its own mark. +. +If the mark is wider than +.I mark-indent, +one space separates it from subsequent text; +contrast +.BR BVL . . .I text-indent -sets the indent to the text, and +sets the indentation of the text, +and .I mark-indent -the distance from the current indentation to the mark. +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. . -A third argument prohibits printing of a blank line before each item. . .TP .BI "VM \fR[\fP\-T\fR] [\fP" "top \fR[\fPbottom\fR]]\fP" @@ -3686,12 +3836,22 @@ to increase user control of page layout. . . .TP -.BI WA\ "\fR[\fPwriter-name \fR[\fPtitle\fR]]\fP" -Begin specification of the writer and writer's address. +.BR WA \~[\c +.IR sender-name \~[\c +.IR title ]] +Specify the writer's address in a letter. . -Several names can be specified with empty +Input is collected into the writer's address until +.B WA +is called, +and then output. +. +You can specify multiple senders with empty .BR WA / WE -pairs, but only one address. +pairs; +only the last address is used. +. +The arguments give each sender a name and title. . . .TP @@ -3739,7 +3899,7 @@ T} . .TP .B WE -End the address specification after +End the writer's address begun with .BR WA . . . @@ -4064,6 +4224,23 @@ 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] . @@ -4087,7 +4264,6 @@ Empty outside of Useful in user-defined macros like .BR .TP . . -.RS .IP .TS tab(@); @@ -4101,7 +4277,6 @@ ec@List of equations ex@List of exhibits ap@Appendix .TE -.RE . . .TP @@ -4113,13 +4288,13 @@ the trade mark sign. . .TP .B Verbnm -Argument to -.B .nm -in the -.B .VERBON +supplies argument(s) to the +.B nm +request employed by the +.B VERBON macro. . -Default is\~1. +The default is\~\[lq]1\[rq]. . . .br @@ -4603,7 +4778,7 @@ output device. .B Lt .TQ .B Lx -configures the report of lists of equation, +configure the report of lists of equation, figure, table, and exhibit captions, @@ -4899,6 +5074,19 @@ 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 @@ -5030,7 +5218,7 @@ It is therefore possible to define other letter types, either in the territory-specific macro file, or as local additions. . -.B .LT +.B LT sets the registers .B Pt and @@ -5043,7 +5231,7 @@ The following strings and macros must be defined for a new letter type. .TP .BI let@init_ type This macro is called directly by -.BR .LT . +.BR LT . . It is supposed to initialize registers and other stuff. . @@ -5060,7 +5248,7 @@ otherwise it is called for all pages. .TP .BI let@sg_ type\~\c .IR "name title n is-surname\~" [ SG-arg\~ .\|.\|.] -.B .SG +.B SG calls this macro only for letters; memoranda have their own processing. . @@ -5068,7 +5256,7 @@ memoranda have their own processing. and .I title are specified through -.BR .WA / .WE . +.BR WA / WE . . .IR n \~is the index of the @@ -5079,19 +5267,19 @@ and is true for the last name. . Further -.B .SG +.B SG arguments are appended to the signature line. . . .TP .BI let@fc_ "type closing" This macro is called by -.BR .FC , +.BR FC , and has the formal closing as the argument. . . .LP -.B .LO +.B LO is implemented as a general option-macro. . It demands that a string named @@ -5100,7 +5288,7 @@ is defined, where .I type is the letter type. . -.B .LO +.B LO then assigns the argument to the string .BI let*lo- type\fR.\fP . |