rsml(5) — Macro Packages and Conventions

Digital

NAME

RSML − the RSML macro package for reference pages

SYNOPSIS

FLAGS

Note that the following descriptions contain information about ∗troff output. This is provided for completeness, only. Digital does not supply or support any ∗troff formatters.

−hUses output tabs during horizontal spacing to speed output and reduce output character count. Tab settings are assumed to be every eight nominal character widths.

-nNNumbers the first generated page as N. Ignored by the RSML macros for nroff output. Ignored for ∗troff output unless -rpS is also specified.

-rlNTurns on line double-spacing mode if N is greater than 0.

-rnNNumbers the first generated page as N. Page numbers always print on the outside end of the page footer. Ignored by the RSML macros for nroff output.

-rpSSets the section number to S. Section numbers appear in output page footers as S−N (chapter−page-number). Page numbers always print on the outside end of the page footer. Starting page number defaults to “1” unless -nN or -rnN is also specified. Ignored by the RSML macros for nroff output.

-rv2Prints crop marks. Only for use with ∗troff formatters.

DESCRIPTION

To use the RSML macro package to format a reference page, include the following as the first two lines of the reference page source file: .so /usr/share/lib/tmac/sml
.so /usr/share/lib/tmac/rsml

Make sure these lines are included in the order shown. Once these lines are included in the reference page source file, use −man on the command line to process the reference page for unpaginated viewing, or for printing on ASCII printers. Use −man.page on the command line to process the reference page for paginated ASCII output.

The file argument is the name of the reference page source file.

Macros

The following describes the macros in the RSML macro package.

Note that some of the macro descriptions contain information about ∗troff output. This is provided for completeness, only. Digital does not supply or support any ∗troff formatters.

Any text, phrase, or title argument can consist of more than one word. Use quotation marks (" ") to enclose an argument containing more than a single word.

The following macros and ∗troff requests are described in this section because they may be used in a reference page source file coded with RSML. However, they are not defined in the RSML macro package:

.ds

.EN

.EQ

.ne

.PE

.PS

.T&

.TE

.TS

.ALStarts a numbered list. Use the .LI macro to identify the list items. Use the .LE macro to end the list.

.cEEnds a comment section.

.cSBegins a comment section. Text between a .cS and a .cE macro does not appear in the output.

.dI subdocument
Includes a subdocument containing RSML macros.

.dEEnds a type declaration section.

.dS [arg-type]Starts a type declaration section. Use within a function definition section (.fS/.fE). Use the optional arg-type argument to specify the argument type. Place the parameter name on a line between the .dS and .dE macros. Imbed the .fS/.fE and .dS/.dE macro pairs within an .sS/.sE region.

.ds string text
Defines a string. The argument string is one or two characters. Use the \∗string construct to cause a single-character string to be replaced by the specified text in the output. Use the \∗(string construct to cause a two-character string to be replaced by the specified text in the output.

.E, phrase text
Sets phrase in the font selected for emphasis, generally italics. The phrase is followed by text set in the normal font with no intervening space.

.,E text phrase
Sets phrase in the font selected for emphasis, generally italics. The phrase is preceded by text set in the normal font with no intervening space.

.EC titleSets the title argument as the caption for an equation.

.eI subdocument
Includes an example subdocument. No troff commands in the subdocument are processed. The subdocument can contain backslash (\) characters and lines beginning with a period. The subdocument is treated as a display; line breaks in the subdocument cause line breaks in the output document.

.eM textSets text in the font selected for emphasis, generally italics.

.ENEnds a section containing one or more equations.

.EQStarts a section containing one or more equations.

.EX titleSets the title argument as the caption for an example.

.FG titleSets the title argument as the caption for a figure.

.fEEnds a function definition section.

.fSStarts a function definition section. Use the type declaration macros (.dS/.dE) within the function definition macros (.fS/.fE). Imbed the .fS/.fE and .dS/.dE macro pairs within an .sS/.sE region.

.iEEnds a user comand input region.

.iSStarts a user command input region. When a section is designed to show user command input, use the .iS/.iE markup. This region is not a display. It continues to the next page, if needed. To ensure that a user command input region is not continued over a page boundary, use the .ne command to check for enough space on the current page. The default font for an .iS/.iE region is \∗L.

.iX ["−flags"] "primary"
[""secondary""|""cross-reference""]" Creates an index entry. The primary entry is required; the flags and other entries are optional. The flags are as follows:

!Highlight an entry as the main entry for this topic.

[Start a page range for this topic.

]End a page range for this topic.

:Specify use of See other-entry-name instead of a page number.

;Specify use of See also other-entry-name instead of a page number. If used, the flags : or ; must appear last. The flag ! may be used with [, :, or ; — no other combination is meaningful.

.K, key text
Sets the key argument in the bold font and encloses it in angle brackets. The key name is followed by text set in the normal font with no intervening space. Use this macro when you have ordinary text immediately following the keyboard key name.

.,K text key
Sets the key argument in the bold font and encloses it in angle brackets. The key name is preceded by text set in the normal font with no intervening space. Use this macro when you have ordinary text immediately preceding the keyboard key name.

.kY key
Sets the key argument in the bold font and encloses it in angle brackets. Use this macro to display the name of a keyboard key.

.LEEnds a list started by .AL, .ML, or .VL.

.LI [phrase]
Marks an item in a list started by .AL, .ML, or .VL. For lists started by .AL and .ML, place the list item on the lines following the .LI macro. The .VL macro starts a two-column list; place the left-column entry on the same line as the .LI macro, surrounded by double quotes (" "). Place the right-column entry starting on the line below the .LI macro.

.MLStarts a marked list. Use the .LI macro to identify the list items. Use the .LE macro to end the list.

.ne xStarts a new page if fewer than x number of lines remain on the current page.

.nLForces a line break.

.nPForces a page break.

.oEEnds a system output example region.

.oSStarts a system output example region. When a section is designed to show system output or a file listing, use the .oS/.oE markup. This region is not a display. It continues to the next page, if needed. To ensure that a system output example region is not continued over a page boundary, use the .ne command to check for enough space on the current page. The default font for an .oS/.oE region is \∗C.

.PStarts a block paragraph; same as .PP.

.PEEnds a pic drawing.

.PPStarts a block paragraph. Sets the prevailing indent to .5i for nroff and four picas for ∗troff text formatters.

.PSStarts a pic drawing; for use with ∗troff text formatters only.

.rE [ k ]
Returns to the kth relative right shift indent level. (Restores the left margin to the position prior to the kth .rS call). Specifying k=0 is equivalent to specifying k=1. If k is omitted, .rE restores the left margin to the most recent previous position. When k=1 or 0, the default .rS indent increment is restored.

.rS [ i ]
Shifts the left margin to the right (relatively) the amount of i ens. The .rS macro calls can be nested up to nine levels. If i is not specified for the first .rS call, the relative right shift increases .5 inch for nroff and four picas for ∗troff text formatters. Nested .rS calls increment the relative indent by i ens, or by .2 inch for nroff, or by 2 picas for ∗troff text formatters.

.sEEnds a synopsis definition.

.SH
Creates a section header.

.SS text
Creates a subsection header.

.sS
Starts a synopsis definition. When coding function prototypes, imbed the .fS/.fE and .dS/.dE macro pairs within an .sS/.sE region. If you use the .iS/.iE macros to code a function prototype, imbed the .iS/.iE macros within the .sS/.sE region. To code a command synopsis, start the synopsis with the .sS macro, code the command line with \∗L, \∗V, and \∗O text markup, and end the synopsis with the .sE macro.

.T&
Changes the format of columns within a table. Follow the table continue request (.T&) with the new format line and then the column data.

.TB title
Sets the title for a table.

.TE
Ends a table.

.TH n c[s] [fc] [fl] [hc] [o] [a]
Begins a new reference page and sets the page title. Also sets up headers and footers for printed output pages and sets up all defaults and traps. The title appears as a header on all pages of the formatted reference page. The n argument is the reference page name. The c argument is the primary section number or letter. The s argument is the subsection, if any. The fc argument is optional and specifies the text for the page foot center. The fl argument is optional and specifies the text for the page foot left. The hc argument is optional and specifies the text for the page head center. The o argument is optional and can be used for “origin” information; for example, “Digital,” “OSF,” or “MIT.” The a argument is optional and can be used to specify the machine architecture, for example “RISC.”

Fields n, c, and s appear together at the top of each output page (see the top of this page for an example). These fields are displayed at both the top left and right of the screen, or printed page. Fields fc and fl are in effect only with the man.page macro package, or when using a ∗troff formatter. Field hc appears at the top center of each output page. Field o, the “origin” label, appears under the reference page name and section number, at the top left and right sides of the screen, or printed page. Field a appears under the “origin” label, or under the reference page name and section number if there is no “origin” label, at the top left and right sides of the screen, or printed page.

The last five fields are optional. To skip a field, specify a pair of quotation marks ("") in the field to be skipped.

.TS
Starts a table.

.VL indent
Starts a two-column list. Specify the indent for the list in i inches, c centimeters, or in m ems. Follow the .VL macro with the list item (.LI) macro. Place the left-column entry on the same line as the .LI macro, surrounded by double quotes (" "). If the left-column entry is a phrase, code a backslash before each space to prevent the formatter from using the spaces when it calculates the justification for the first line. If the left-column entry is longer than the specified indent, code the .nL macro on the line following the .LI macro to force the right-column entry onto a new line. Place the right-column entry starting on the line below the .LI macro, or on the line below the .nL macro, if used.

Meaningful Text Markup

The following describes the text markup that can be used in a source file to change the font for conveying the semantic meaning of the text.

Markup	Semantic Meaning	Examples	Font Produced
\∗L	Literal text	User command input, command names, glossary term in text	Bold
\∗V	Variable text	User-supplied term	Italic
\∗O	Ordinary text	Returns the font to normal; use after a font change	Roman font
\∗C	Computer output	System output, file listing	Constant width
\∗E	Emphasized text	Book title, emphasized term	Italic
\∗A	Alphabetic constant	Error constant	Constant width
\∗N	Numeric constant	Error constant	Constant width

Macros That Need Text Lines

The following macros affect the following line of text if they are specified in the input without arguments:

.SH

.SS

Defaults

For a list of defaults, see the man(5) reference page.

RESTRICTIONS

Using the man macros described in the man(5) reference page in the same source file with the RSML macros may give undesirable results.

For a list of predefined registers, reserved registers, predefined strings, and reserved strings and macros for the man and man.page macro packages, see the man(5) reference page.

In addition, the following sections describe the RSML reserved registers, reserved strings, internal macros, and macro names reserved for future use.

RSML Reserved Registers

The following registers are reserved for internal use by the RSML macro package:

%n	#n	Ll	$A	$M	$U
\|A	\|B	\|Q	!x	!+	!%

Predefined Strings

The following strings are predefined for the RSML macro package and should not be changed:

lq" if nroff, “ if ∗troff

rq" if nroff, ” if ∗troff

RSML Reserved Strings and Macros

The following string and macro names are reserved for internal use by the RSML macro package:

.e:

.e;

.e,

.P#

.SP

.!~

.)F

The following string names are reserved for RSML users:

RSML Macro Names Reserved for Future Use

The following RSML macro names are reserved for future use:

.aE

.aS

.lE

.lS

.P!

.pI

.pM

.tH

.wH

.TH Macro Restrictions

Section numbers should only be those listed in the man(1) reference page as recognized by the man(1) command.

Sections 5, 6, and the single-letter sections listed in the man(1) reference page normally do not have subsections, so none should be specified.

Subsections “.z” and “.Z” are not valid and should never be used.

For nroff output, keep the size of the reference page name, including its section and subsection, to a maximum of 38 characters to prevent overprinting in the reference page header. Similarly, restrict the size of the o and a fields to a maximum of 38 characters. If the hc field is used, reduce the size of the name, section, and subsection fields by the size of the hc field + 1.

The maximum sizes for the reference page name, o and a fields, are much shorter if the reference page is formatted with a ∗troff formatter.

The NAME Section

The catman(1) command assumes the NAME section of a reference page has the following format:

name[, name, name ...] - explanatory text

There should be at least one space after any comma and only one space following the “hyphen” (-). A “backslash hyphen” (\-) may also be used to produce a longer dash. Avoid using macros or other markup to code information in the NAME section. The explanatory text should be brief. The catman(1) command combines information in the NAME section with parameters of the .TH macro to create an entry in a database searched by the apropos(1), man(1), and whatis(1) commands.

FILES

/usr/share/lib/tmac/rsml
RSML supplementary macros

/usr/share/lib/tmac/sml
Generic SML supplementary macros

RELATED INFORMATION

Commands: catman(1), checkeq(1), man(1), neqn(1), nroff(1), tbl(1)

Functions: man(5)

Museum

Related Articles