 |
Index for
Section 5 |
|
 |
Alphabetical
listing for R |
|
 |
Bottom of
page |
|
rsml(5)
NAME
rsml, sml - rsml and sml macro packages that support RSML-coded reference
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.
-h 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.
-nN Numbers the first generated page as N. Ignored by the *sml macros for
nroff output.
Ignored for *troff output unless -rpS is also specified.
-rlN
Turns on line double-spacing mode if N is greater than 0.
-rnN
Numbers the first generated page as N. Page numbers always print on the
outside end of the page footer.
Ignored by the *sml macros for nroff output.
-rpS
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.
-rv2
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 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:
-man To process the reference page for unpaginated viewing or for
printing on ASCII printers
-man.page
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.
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 .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.
.AL Starts a numbered list. Use the .LI macro to identify the list items.
Use the .LE macro to end the list.
.cE Ends a comment section.
.cS Begins a comment section. Text between a .cS and a .cE macro does not
appear in the output.
.dI subdocument
Includes a subdocument containing RSML markup.
.dE Ends 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 title
Sets 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 text
Sets text in the font selected for emphasis, generally italics.
.EN Ends a section containing one or more equations.
.EQ Starts a section containing one or more equations.
.EX title
Sets the title argument as the caption for an example.
.FG title
Sets the title argument as the caption for a figure.
.fE Ends a function definition section.
.fS 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.
.iE Ends a user command input region.
.iS 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.
.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.
.LE Ends 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
(" "). 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 .LI macro.
.ML Starts a marked list. Use the .LI macro to identify the list items.
Use the .LE macro to end the list.
.ne x
Starts a new page if fewer than x number of lines remain on the current
page.
.nL Forces a line break.
.nP Forces a page break.
.oE Ends a system output example region.
.oS Starts 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.
.PE Ends a pic drawing.
.PP Starts a block paragraph. Sets the prevailing indent to .5i for nroff
and four picas for *troff text formatters.
.PS Starts 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.
.sE Ends a synopsis definition.
.SH text
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, ``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 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 Bold
User command
input, command
names, glossary
term in text
\*V Variable text Italic
User-supplied
term
\*O Ordinary text Roman font
Returns the font
to normal; use
after a font
change
\*C Computer output Constant width
System output,
file listing
\*E Emphasized text Italic
Book title,
emphasized term
\*A Error constant Constant width
Alphabetic
constant
\*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 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 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:
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
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)
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 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 catman command combines
information in the NAME section with parameters of the .TH 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
/usr/share/lib/tmac/rsml
RSML macros
/usr/share/lib/tmac/sml
SML macros
/usr/share/lib/tmac/tmac.an
man macros for unpaginated output
/usr/share/lib/tmac/tmac.an.page
man macros for paginated output
SEE ALSO
Commands: checkeq(1), man(1), neqn(1), nroff(1), tbl(1), catman(8)
Files: man(5)
|
Index for
Section 5 |
|
|
Alphabetical
listing for R |
|
 |
Top of
page |
|