rsml, sml - rsml and sml macro packages that support RSMLcoded
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. We do 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.
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 outside 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.
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 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 [Toc] [Back]
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 identify 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 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 and macro pairs within an 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 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 otherentry-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 paragraph.
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
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. 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 leftcolumn
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 [Toc] [Back]
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 [Toc] [Back]
The following macros affect the following line of text if
they are specified in the input without arguments:
.SH .SS
Defaults [Toc] [Back]
For a list of defaults, see the man(5) reference page.
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 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.
RSML macros SML macros man macros for unpaginated output
man macros for paginated output
Commands: checkeq(1), man(1), neqn(1), nroff(1), tbl(1),
catman(8)
Files: man(5)
()
[ Back ] |
