mansun - macros to format Reference Manual pages


     nroff -mansun filename...

     troff -mansun filename...


     These macros are used to lay out the reference pages in this
     manual.  Note:  if  filename  contains  format  input  for a
     preprocessor, the commands shown above must be piped through
     the  appropriate preprocessor. This is handled automatically
     by man(1).  See the ``Conventions'' section.

     Any text argument t may be zero to six words. Quotes may  be
     used  to include <SPACE> characters in a "word".  If text is
     empty, the special treatment is applied to  the  next  input
     line  with text to be printed. In this way .I may be used to
     italicize a whole line, or .SB may be  used  to  make  small
     bold letters.

     A prevailing indent distance is remembered  between  succes-
     sive indented paragraphs, and is reset to default value upon
     reaching  a  non-indented  paragraph.   Default  units   for
     indents i are ens.

     Type font and size are reset to default values  before  each
     paragraph,  and  after processing font and size setting mac-

     These strings are predefined by -mansun:

     \*R   `O', `(Reg)' in nroff.

     \*S   Change to default type size.

     * n.t.l. = next text line; p.i. = prevailing indent

     Request         Cause        If no        Explanation
                     Break        Argument
     .B t            no           t=n.t.l.*    Text is in bold font.
     .BI t           no           t=n.t.l.     Join  words,  alternating  bold
                                               and italic.
     .BR t           no           t=n.t.l.     Join  words,  alternating  bold
                                               and Roman.
     .DT             no           .5i 1i...    Restore default tabs.
     .HP i           yes          i=p.i.*      Begin  paragraph  with  hanging
                                               indent.   Set prevailing indent
                                               to i.
     .I t            no           t=n.t.l.     Text is italic.
     .IB t           no           t=n.t.l.     Join words, alternating  italic
                                               and bold.
     .IP x i         yes          x=""         Same as .TP with tag x.
     .IR t           no           t=n.t.l.     Join words, alternating  italic
                                               and Roman.
     .IX t           no           -            Index macro, for SunSoft inter-
                                               nal use.
     .LP             yes          -            Begin  left-aligned  paragraph.
                                               Set prevailing indent to .5i.
     .P              yes          -            Same as .LP.
     .PD d           no           d=.4v        Set vertical  distance  between
     .PP             yes          -            Same as .LP.
     .RE             yes          -            End   of    relative    indent.
                                               Restores prevailing indent.
     .RB t           no           t=n.t.l.     Join words,  alternating  Roman
                                               and bold.
     .RI t           no           t=n.t.l.     Join words,  alternating  Roman
                                               and italic.
     .RS i           yes          i=p.i.       Start relative indent, increase
                                               indent  by  i.  Sets prevailing
                                               indent  to   .5i   for   nested
     .SB t           no           -            Reduce size of text by 1 point,
                                               make text bold.
     .SH t           yes          -            Section Heading.
     .SM t           no           t=n.t.l.     Reduce size of text by 1 point.
     .SS t           yes          t=n.t.l.     Section Subheading.
     .TH n s d f m   yes          -            Begin reference page n,  of  of
                                               section s; d is the date of the
                                               most   recent    change.     If
                                               present,  f  is  the  left page
                                               footer;  m  is  the  main  page
                                               (center) header.  Sets prevail-
                                               ing indent and tabs to .5i.
     .TP i           yes          i=p.i.       Begin indented paragraph,  with
                                               the  tag given on the next text
                                               line.  Set prevailing indent to
     .TX t p         no           -            Resolve the title  abbreviation
                                               t; join to punctuation mark (or
                                               text) p.

     When formatting a manual page,  mansun  examines  the  first
     line  to  determine  whether it requires special processing.
     For example a first line consisting of:

          '\" t

     indicates that the manual  page  must  be  run  through  the
     tbl(1) preprocessor.

     A typical manual page for a command or function is laid  out
     as follows:

     .TH title [1-8]
           The name of the command or function, which  serves  as
           the title of the manual page.  This is followed by the
           number of the section in which it appears.

     .SH NAME
           The name, or list of names, by which  the  command  is
           called, followed by a dash and then a one-line summary
           of the action performed. All in Roman font, this  sec-
           tion  contains no troff(1) commands or escapes, and no
           macro requests. It is  used  to  generate  the  windex
           database, which is used by the  whatis(1) command.


                 The syntax of the command and its arguments,  as
                 typed  on the command line.  When in boldface, a
                 word must be typed exactly as printed.  When  in
                 italics, a word can be replaced with an argument
                 that you supply. References to  bold  or  itali-
                 cized  items  are  not capitalized in other sec-
                 tions, even when they begin a sentence.

                 Syntactic symbols appear in Roman face:

                 [ ]   An argument, when surrounded  by  brackets
                       is optional.

                 |     Arguments separated by a vertical bar  are
                       exclusive.  You  can  supply only one item
                       from such a list.

                 ...   Arguments followed by an ellipsis  can  be
                       repeated.   When  an  ellipsis  follows  a
                       bracketed set, the expression  within  the
                       brackets can be repeated.

           If required, the data declaration, or #include  direc-
           tive,  is  shown  first,  followed  by  the   function
           declaration. Otherwise, the  function  declaration  is

           A narrative overview  of  the  command  or  function's
           external behavior. This includes how it interacts with
           files or data, and how it handles the standard  input,
           standard  output  and  standard  error.  Internals and
           implementation details are normally omitted. This sec-
           tion attempts to provide a succinct overview in answer
           to the question, "what does it do?"

           Literal text from the  synopsis  appears  in  constant
           width, as do literal filenames and references to items
           that appear elsewhere in the  reference manuals. Argu-
           ments are italicized.

           If a command interprets either subcommands or an input
           grammar,  its  command  interface  or input grammar is
           normally described in a USAGE section,  which  follows
           the  OPTIONS  section.   The  DESCRIPTION section only
           describes the behavior of the command itself, not that
           of subcommands.

           The list of options along with a  description  of  how
           each affects the command's operation.

     .SH FILES
           A list of files associated with the command  or  func-

           A comma-separated list of related manual  pages,  fol-
           lowed by references to other published materials.

           A list of diagnostic messages and  an  explanation  of

     .SH BUGS
           A description of limitations, known defects, and  pos-
           sible  problems  associated  with the command or func-





     man(1), nroff(1), troff(1), whatis(1)

     Dale Dougherty and Tim O'Reilly, Unix Text Processing

Man(1) output converted with man2html