rsml, sml - rsml and sml macro packages that support RSML-coded reference pages
tbl file...|neqn|nroff -h [options] -man|...
tbl file...|neqn|nroff -h [options] -man.page|...
The following descriptions of options contain information about *troff output. This is provided for completeness, only. Digital does not supply or support any *troff formatters. Uses output tabs during horizontal spacing to speed output and reduce output character count. Tab settings are assumed to be every eight nominal character widths. Numbers the first generated page as N. Ignored by the *sml macros for nroff output.
Reference pages that originate from the Open Software Foundation (OSF) and those created for Tru64 UNIX are coded using RSML (Reference Semantic Markup Language). This markup is implemented through a combination of two macro packages, sml and rsml. In addition, certain macros and requests supported for RSML coding are defined in the tmac.an (man) macro package.
To use RSML coding in 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; some rsml macro definitions are intended to overwrite definitions in the sml and man macro sets. You can format a reference page manually using the command line shown in the SYNOPSIS section; specify one of the following options on your command line: To process the reference page for unpaginated viewing or for printing on ASCII printers To process the reference page for paginated ASCII output
Do not specify a .so entry in a reference page source file to include the tmac.an or tmac.an.page macros from the /usr/share/lib/tmac directory. The man and catman commands automatically specify the -man option to nroff when they process reference page source files; you should follow the same convention when formatting reference pages directly with *roff commands.
argument in the command line is
the name of the reference page source file.
This section describes the macros used to mark up reference pages in Reference Semantic Markup Language (RSML).
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 in the following macro descriptions can consist of more than one word. Use quotation marks (" ") to enclose an argument containing more than a single word.
Note that the .ds, .EN, .EQ, .ne, .PE, .PS, .T, .TE, and .TS macros are used in RSML markup but are implemented through the tmac.an (man) macro package. Starts a numbered list. Use the .LI macro to identify the list items. Use the .LE macro to end the list. Ends a comment section. Begins a comment section. Text between a .cS and a .cE macro does not appear in the output. Includes a subdocument containing RSML markup. Ends a type declaration section. 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. 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. 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. 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. Sets the title argument as the caption for an equation. 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. Sets text in the font selected for emphasis, generally italics. Ends a section containing one or more equations. Starts a section containing one or more equations. Sets the title argument as the caption for an example. Sets the title argument as the caption for a figure. Ends a function definition section. Starts 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. Ends a user command input region. Starts 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. 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.
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|
The following macros affect the following line of text if they are specified in the input without arguments:
For a list of defaults, see the
Using man macros not described in this reference page in the same source file with macros that are described in this reference page can 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
reserved registers, reserved strings, internal macros, and macro names reserved
for future use.
The following registers are reserved for internal use by the macro packages for RSML:
The following strings are predefined for
and should not be changed:
nroff, `` if
nroff, '' if
The following string and macro names are reserved for internal use by the macro packages that implement RSML:
The following string names are reserved for RSML users:
The following macro names are reserved for future use by RSML users:
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,
fields, are much shorter if the reference
page is formatted with a
The catman 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 Return characters, macros, or markup other
than \*L and \*O to code information in the NAME section entry. The explanatory
text in this entry should be brief. The
combines information in the NAME section with parameters of the
macro to create an entry in a database searched by the
commands. Unrecognized markup, use of the wildcard character
(*), or unexpected Return characters in the NAME section cause errors or incorrect
results when the
database is created or searched.
macros for unpaginated output
macros for paginated output
Commands: checkeq(1), man(1), neqn(1), nroff(1), tbl(1), catman(8)