rsml(5)rsml(5)NAME
rsml, sml - rsml and sml macro packages that support RSML-coded refer‐
ence pages
SYNOPSIS
tbl file... | neqn | nroff -h [options] -man | ...
tbl file... | neqn | nroff -h [options] -man.page | ...
OPTIONS
The following descriptions of options contain information about *troff
output. This is provided for completeness, only. We do not supply or
support any *troff formatters. Uses output tabs during horizontal
spacing to speed output and reduce output character count. Tab set‐
tings are assumed to be every eight nominal character widths. Numbers
the first generated page as N. Ignored by the *sml macros for nroff
output.
Ignored for *troff output unless -rpS is also specified. Turns
on line double-spacing mode if N is greater than 0. Numbers the
first generated page as N. Page numbers always print on the out‐
side end of the page footer.
Ignored by the *sml macros for nroff output. Sets 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 *sml macros for nroff output. Prints crop marks.
Only for use with *troff formatters.
DESCRIPTION
Reference pages that originate from the Open Software Foundation (OSF)
and those created for Tru64 UNIX are coded using RSML (Reference Seman‐
tic 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 unpagi‐
nated viewing or for printing on ASCII printers To process the refer‐
ence page for paginated ASCII output
Do not specify a 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.
The file argument in the command line is the name of the reference page
source file.
Macros
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. We do 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
macros are used in RSML markup but are implemented through the tmac.an
(man) macro package. Starts a numbered list. Use the macro to iden‐
tify the list items. Use the macro to end the list. Ends a comment
section. Begins a comment section. Text between a and a 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 and macros. Imbed the and macro pairs within
an region. Defines a string. The argument string is one or two char‐
acters. 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 speci‐
fied text in the output. Sets phrase in the font selected for empha‐
sis, generally italics. The phrase is followed by text set in the nor‐
mal 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 equa‐
tions. Sets the title argument as the caption for an example. Sets
the title argument as the caption for a figure. Ends a function defi‐
nition section. Starts a function definition section. Use the type
declaration macros (.dS/.dE) within the function definition macros
(.fS/.fE). Imbed the and macro pairs within an region. Ends a user
command input region. Starts a user command input region. When a sec‐
tion is designed to show user command input, use the 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 command to check for enough space on the current
page. The default font for an 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.
If used, the flags : or ; must appear last. The flag ! may be
used with [, :, or ; -- no other combination is meaningful.
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. 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. 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.
Ends a list started by Marks an item in a list started by or and
macro. The macro starts a two-column list; place the left-column
entry on the same line as the macro, surrounded by double quotes
(" "). Because the double quote character delimits the left-
column entry, you must enter four double quotes ("""") to print
any double quote character that is part of the left-column
entry. Place the right-column entry starting on the line below
the macro. Starts a marked list. Use the macro to identify the
list items. Use the macro to end the list. Starts a new page
if fewer than x number of lines remain on the current page.
Forces a line break. Forces a page break. Ends a system output
example region. Starts a system output example region. When a
section is designed to show system output or a file listing, use
the 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 command to
check for enough space on the current page. The default font for
an region is \*C. Ends a pic drawing. Starts a block para‐
graph. Sets the prevailing indent to .5i for nroff and four
picas for *troff text formatters. Starts a pic drawing; for use
with *troff text formatters only. Returns to the kth relative
right shift indent level. (Restores the left margin to the
position prior to the kth call). Specifying k=0 is equivalent
to specifying k=1. If k is omitted, restores the left margin to
the most recent previous position. When k=1 or 0, the default
indent increment is restored. Shifts the left margin to the
right (relatively) the amount of i ens. The macro calls can be
nested up to nine levels. If i is not specified for the first
call, the relative right shift increases .5 inch for nroff and
four picas for *troff text formatters. Nested calls increment
the relative indent by i ens, or by .2 inch for nroff, or by 2
picas for *troff text formatters. Ends a synopsis definition.
Creates a section header. Creates a subsection header. Starts
a synopsis definition. When coding function prototypes, imbed
the and macro pairs within an region. If you use the macros to
code a function prototype, imbed the macros within the region.
To code a command synopsis, start the synopsis with the macro,
code the command line with \*L, \*V, and \*O text markup, and
end the synopsis with the macro. Changes the format of columns
within a table. Follow the table continue request (.T&) with
the new format line and then the column data. Sets the title
for a table. Ends a table. 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 refer‐
ence 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 spec‐
ifies 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 ``ori‐
gin'' information; for example, ``Free Software Foundation'' or
``X11R5.'' The a argument is optional and can be used to specify
the machine architecture, for example ``Alpha AXP.''
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 sec‐
tion 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. Starts
a table. Starts a two-column list. Specify the indent for the
list in i inches, c centimeters, or in m ems. Follow the macro
with the list item (.LI) macro. Place the left-column entry on
the same line as the 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 macro
on the line following the macro to force the right-column entry
onto a new line. Place the right-column entry starting on the
line below the macro, or on the line below the 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 Bold
input, command
names, glossary
term in text
\*V Variable text User-supplied Italic
term
\*O Ordinary text Returns the font Roman font
to normal; use
after a font
change
\*C Computer output System output, Constant width
file listing
\*E Emphasized text Book title, Italic
emphasized term
\*A Alphabetic con‐ Error constant Constant width
stant
\*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 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 RSML reserved regis‐
ters, reserved strings, internal macros, and macro names reserved for
future use.
RSML Reserved Registers
The following registers are reserved for internal use by the macro
packages for RSML:
%n #n Ll $A $M $U
|A |B |Q !x !+ !%
Predefined Strings
The following strings are predefined for RSML markup and should not be
changed: "if nroff, `` if *troff " if nroff, '' if *troff
RSML Reserved Strings and Macros
The following string and macro names are reserved for internal use by
the macro packages that implement RSML:
%n #n .e: .e; .e, .P# .SP .!~ .)F
The following string names are reserved for RSML users:
A C E L N O U V
RSML Macro Names Reserved for Future Use
The following macro names are reserved for future use by RSML users:
.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) ref‐
erence page normally do not have subsections, so none should be speci‐
fied.
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 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 sec‐
tion entry. The explanatory text in this entry should be brief. The
catman command combines information in the NAME section with parameters
of the
() ()
macro to create an entry in a database searched by the apropos, man -k,
and whatis commands. Unrecognized markup, use of the wildcard character
(*), or unexpected Return characters in the NAME section cause errors
or incorrect results when the whatis database is created or searched.
FILES
RSML macros SML macros man macros for unpaginated output man macros for
paginated output
SEE ALSO
Commands: checkeq(1), man(1), neqn(1), nroff(1), tbl(1), catman(8)
Files: man(5)
()
