*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> man (5)              


 man(5)                                                               man(5)

 NAME    [Toc]    [Back]
      man - macros for formatting manpages

 SYNOPSIS    [Toc]    [Back]
      man file ...

      nroff -man [option]... [file]...

 DESCRIPTION    [Toc]    [Back]
      The man macros are used by the man and nroff commands (see man(1) and
      nroff(1)) - and are usable by troff (see third-party documentation) -
      to format the on-line versions of manpages found in HP-UX Reference
      and other related reference manuals.  The man command calls nroff.

    man and nroff Defaults
      The default page size is 85 characters by 66 lines (8.5x11 inches),
      with a 75-character by 60-line text area.  Hyphenation is turned off
      and paragraphs are left-adjusted, ragged-right.

    troff Defaults
      The default page size is 8.5x11 inches with a 6.5x10-inch text area.
      The type size is 10 points and the vertical line spacing is 12 points.
      Hyphenation is turned on and paragraphs are justified left and right.

    Other Defaults    [Toc]    [Back]
      Type font and size are reset to default values before each paragraph
      and after processing font- and size-setting macros such as .I, .RB,
      and .SM.  Tab stops are neither used nor set by any macro except .DT
      and .TH.  The .TH macro invokes .DT (see below).

    Options    [Toc]    [Back]
      The following options can be specified for nroff or troff.  They are
      not permitted for the man command.

      -rs1      Reduce the dimensions for troff to a page size of 6x9 inches
                with a 4.75x8.375-inch text area, the type size to 9 points,
                and the vertical line spacing to 10 points.  This option is
                ignored by nroff.

      -rV2      Set certain parameters to values appropriate for certain
                Versatec printers: line length to 82 characters (ens); page
                length to 84 lines; underlining inhibited.  Do not confuse
                this option with the -Tvp option of the man command, which
                is available on some operating systems, but not on HP-UX.

    Summary of Macros, Strings, and Numbers
      The defined man macros, strings, and numbers are summarized here and
      described in detail in the following subsections.

      .B        Set text in bold.

 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003

 man(5)                                                               man(5)

      .BC       Set words alternately in bold and constant-width.
      .BI       Set words alternately in bold and italics.
      .BR       Set words alternately in bold and roman.
      .C        Set text in constant-width.
      .CB       Set words alternately in constant-width and bold.
      .CD       Identify command name.
      .CI       Set words alternately in constant-width and italics.
      .CR       Set words alternately in constant-width and roman.
      .CT       Identify citation title.
      .DT       Restore default tab settings.
      .EM       Identify emphasis.
      .ER       Identify error name.
      .EV       Identify environment variable name.
      .GT       Identify glossary term.
      .HP       Begin paragraph with hanging indent.
      .I        Set text in italics.
      .IB       Set words alternately in italics and bold.
      .IC       Set words alternately in italics and constant-width.
      .IP       Begin indented paragraph with optional tag.
      .IR       Set words alternately in italics and roman.
      .KC       Identify keycap.
      .P        Begin normal paragraph.
      .PD       Set interparagraph spacing.
      .PM       Use Bell System proprietary subfooters.
      .PP       Begin normal paragraph.
      .RB       Set words alternately in roman and bold.
      .RC       Set words alternately in roman and constant-width.
      .RE       End relative margin indent.
      .RI       Set words alternately in roman and italics.
      .RS       Start relative margin indent.
      .RV       Identify return value.
      .S3       Insert third level header.
      .SC       Identify system constant name.
      .SH       Insert section header.
      .SM       Print text one point smaller.
      .SS       Insert subsection header.
      .TH       Start new manpage and define page headers and footers.
      .TP       Begin tagged paragraph.
      \*R       Registered trademark.
      \*S       Change to default type size.
      \*(Tm     Trademark.
      \n(IN     Left text margin; default margin indent and paragraph
      \n(LL     Line length, including \n(IN.
      \n(PD     Interparagraph distance.

    Macro Parameters    [Toc]    [Back]
      All macro parameters are positional and can be omitted, starting from
      the right.  Each parameter is a word, as described below.

 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003

 man(5)                                                               man(5)

      mi        Margin increment.  This is the amount by which the left text
                margin will be increased.  If it is omitted, it defaults to
                \n(IN basic units (u).  The default measure for mi is ens
                (n).  The left text margin's base value is \n(IN.

      in        Paragraph indent.  This is the amount by which indented
                lines of a paragraph will be indented.  If it is omitted, it
                defaults to the value that was established by the most
                recent paragraph macro: explicitly or default by .HP, .IP,
                or .TP; implicitly by .P, .PP, .RE, or .RS.  The default
                measure for in is ens (n).

      text      Consists of zero to six words.  If text is empty, the
                special treatment is applied to the next line containing
                text to be printed.  For example, .I can be used to
                italicize a whole line, or .SM followed by .B to make small
                bold text.

      word      A string of characters separated by spaces (not tabs).  Use
                quotation marks ("[word]") to include spaces in a word
                ("string string") or to specify a null word ("").  (The
                nonbreaking, nonpaddable space (\ ) is not a separating

    Header Macros    [Toc]    [Back]
      .TH  t1 s2 c3 n4 a5
                Set the title and entry heading.  t1, s2, c3, n4, and a5 are

                t1   Entry title.

                s2   Section number.  t1 is combined with s2 in parentheses
                     to form the top left- and righthand corners of the page

                c3   Extra commentary, such as "Optional Software Required".
                     It is placed at the center of the bottom line in the
                     two- or three-line page heading space.

                n4   Other notations, such as "Series 300/400 Only".  It is
                     centered between the title and section on the first
                     page heading line.

                a5   Support for alternate naming, such as a FORTRAN routine
                     name corresponding to a C function name specified in

 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003

 man(5)                                                               man(5)

                The resulting output is in the form:

                t1(s2)                       n4                       t1(s2)
                a5                                                        a5

      .SH text  Place section head text, such as SYNOPSIS, here.  Section
                headings start at the left margin.  Since they are normally
                all uppercase, they are printed a point-size smaller in

      .SS text  Place subsection head text, such as Options, here.
                Subsection headings start between the left margin and the
                normal text indent.

      .S3 text  Place third-level head text, such as subhead, here.  Thirdlevel
 headings start at the normal text indent.

    Paragraph Macros    [Toc]    [Back]
      .PP       Begin a block paragraph.  Reset in to \n(IN, "cancelling"
                any value set by previous .HP, .IP, and .TP macros.

      .HP in    Begin a paragraph with hanging indent.  The text begins at
                the current margin.  The second and following output lines
                are indented.

      .TP in    Begin an indented paragraph with hanging tag.  The next
                input line that contains text to be printed is taken as the
                tag.  The tag begins at the current margin.  If the tag fits
                in the indent, the paragraph text begins at the indent
                position on the same line.  If the tag does not fit in the
                indent, the paragraph text begins at the indent position on
                the next line.

      .IP t in  Same as .TP in with tag t.  Often used to get an indented
                paragraph without a tag.

      .RS mi    Increase the current left margin by mi.  If mi is omitted,
                it defaults to the current value of in.  Set the paragraph
                indent, in, for the new margin level to \n(IN.  You can
                specify up to nine .RS increment levels.  Margin increments
                can be backed out with the .RE macro and are reset to the
                base margin by the .TH, .SH, .SS, and .S3 header macros.

      .RE k     Return to the kth left margin setting (initially, k=1; k=0
                is equivalent to k=1).  If k is omitted, return to the
                previous margin value.  The paragraph indent, in, is

 Hewlett-Packard Company            - 4 -   HP-UX 11i Version 2: August 2003

 man(5)                                                               man(5)

                restored to the value it had prior to the corresponding .RS

      .PD pd    Set the interparagraph distance to pd vertical spaces.  If
                pd is omitted, set the interparagraph distance to the
                default value: 1 line in nroff.  0.4 line in troff.  The
                measure for pd is vertical line spaces (v).

    Font Macros    [Toc]    [Back]
      .B text   Set text in bold.

      .C text   Set text in constant-width font.  See the WARNINGS section.

      .I text   Set text in italic.

      (There is no .R (roman) macro, but you can use one of the .XY
      combinations if need be.)

      .XY a b   Concatenate a in font X with b in font Y and alternate these
                two fonts for up to six words.  The font letters X and Y can
                be B (bold), C (constant-width), I (italic), and R (roman),
                in the following combinations:

                           .CB   .IB   .RB
                     .BC         .IC   .RC
                     .BI   .CI         .RI
                     .BR   .CR   .IR

                For more about constant-width font, see the WARNINGS

      .SM text  Make text one point smaller than the default point size.
                This has no effect in nroff.

    Special Macros    [Toc]    [Back]
      These macros identify common text elements in manpages.  They aid in
      providing consistent font usage in the HP style and in improving
      conversion to other formatting systems.

      The first parameter is set in an appropriate font or format.  The
      second parameter, punctuation, is set in roman font and is provided
      for concatenated punctuation.  The two parameters are concatenated as
      with the font macros.

      .CD commandname punctuation
                commandname is a command name, usually defined in a section
                1 or 1M manpage, such as man.  It is displayed in constantwidth

      .CT citationtitle punctuation
                citationtitle is the name of a document, such as HP-UX

 Hewlett-Packard Company            - 5 -   HP-UX 11i Version 2: August 2003

 man(5)                                                               man(5)

                Reference.  It is displayed in italics.  (Use the standard
                .IR macro for manpage references.)

      .EM emphasis punctuation
                emphasis is a word or phrase that you want to emphasize,
                such as Do not.  Use emphasis sparingly.  It is displayed in
                italics.  (Use the standard .I macro for variable names.)

      .ER errorname punctuation
                errorname is an error name that corresponds to a value
                assigned to errno by a function and described in the ERRORS
                section of a manpage.  It is displayed in roman, enclosed in
                square brackets.  For example, .ER EIO . is displayed as

      .EV environvarname punctuation
                environvarname is the name of an environmental variable,
                such as PATH.  It is displayed in constant-width font.

      .GT glossterm punctuation
                glossterm is a glossary term, or a term that you are
                defining for later use in the manpage, such as path name.
                It is displayed in bold.

      .KC keycap punctuation
                keycap is the name of a keyboard key, such as Tab.  It is
                displayed in bold.

      .RV returnvalue punctuation
                returnvalue is a numerical return value of a function or
                exit status of a command, usually as defined in a RETURN
                VALUE or EXIT STATUS section.  It is generally used for
                number expressions, such as 0, >3, and <>0, but not for word
                descriptions, such as "nonzero".  It is displayed in
                constant-width font.

      .SC systemconstant punctuation
                systemconstant is an operating system constant name, such as
                PATH_MAX.  It is displayed in constant-width font.  See

    Other Macros    [Toc]    [Back]
      .DT       Restore default tab settings: every 5 ens in nroff; every
                3.6 ems in troff.

      .PM sf    Produce Bell System proprietary subfooters.

                sf   produces

                P    PRIVATE

 Hewlett-Packard Company            - 6 -   HP-UX 11i Version 2: August 2003

 man(5)                                                               man(5)

                N    NOTICE

    Strings    [Toc]    [Back]
      The following string references are defined:

      \*R       Registered Trademark symbol: displayed as (Reg.) in nroff,
                and using the \(rg inline macro in troff.

      \*S       Change to default type size.  This is executed as a \s
                inline macro.

      \*(Tm     Trademark indicator, TM, displayed as a superscript if

    Numbers    [Toc]    [Back]
      The following number references are defined:

      \n(IN     Left text margin indent relative to section heads and
                default value for mi and in: 5 ens in nroff; 3.6 ems in
                troff.  IN is expressed in basic units (u).

      \n(LL     Line length including \n(IN: 75 characters in nroff; 6.5
                inches in troff.  Also see the Options subsection.  LL is
                expressed in basic units (u).

      \n(PD     Current interparagraph distance.  Set by .PD.  PD is
                expressed in vertical line spaces (v).

    Measure    [Toc]    [Back]
      nroff and troff use a number of scale indicators to qualify horizontal
      and vertical measurements.  Many macro parameters have default units
      of measure.  Because all assignments to numeric variables are
      converted to basic units (u), it is important to take care in
      assigning and referencing values.

           Scale                                Basic Units
           Indicator   Measure               nroff      troff
           c           centimeter            240/2.54   D/2.54
           i           inch                  240        D
           m           em                    C          p*S
           n           en = em/2             C          p*S/2
           p           point = 1/72 inch     240/72     D/72
           P           pica = 1/6 inch       240/6      D/6
           u           basic unit            1          1
           v           vertical line space   V          V

 Hewlett-Packard Company            - 7 -   HP-UX 11i Version 2: August 2003

 man(5)                                                               man(5)

           C    Character width of output device.
           D    Dots per inch (dpi) of output device.
           S    Current type size in points.
           V    Current vertical line spacing in basic units.

    Font Conventions    [Toc]    [Back]
      Entries in the HP-UX Reference use the following font conventions:

           roman          Regular typeface.

           italic         Used for variables and other words that represent
                          an argument that may take on a user-defined or
                          variable value.  Also used for emphasis.

           boldface       Used primarily in headings and occasionally for
                          terms when first introduced or when being defined.

           constant-width Used for all literals that are typed exactly as
                          shown when used as keyboard commands or commandline
 options, in programs, etc.

    Page Footers    [Toc]    [Back]
      The strings used in the page footer are initialized by the .TH macro.
      )H defaults to a nonprinting (null) string.  ]W defaults to the date
      the manpage is formatted, as in Formatted:  July 5, 1995.  In HP
      manpages, )H is set to the company name, "Hewlett-Packard Company"; ]W
      is set to release information, as in "HP-UX Release 10.10: November

      This arrangement enables users and third-party software suppliers to
      directly control the contents of the left- and right-hand fields of
      the footer line for use in displaying company name, release version,
      etc., as desired when creating their own manual entries.  )H is
      printed on the left, ]W is printed on the right, and the page number
      is printed in the center.  These strings can be defined anywhere after
      the .TH macro call, provided they appear before the end of the first
      page.  For example, the following source file segment:

           .TH man 5
           .ds )H XYZ Company
           .ds ]W Release 2.3: May 1996

 Hewlett-Packard Company            - 8 -   HP-UX 11i Version 2: August 2003

 man(5)                                                               man(5)

      produces a footer with text in the form:

           XYZ Company                - 1 -       Release 2.3: May 1996

    Tables    [Toc]    [Back]
      The tbl preprocessor (see tbl(1)) can be used to insert tables in
      manpages.  The man macros allow you to use the standard tbl macros:
      .TS, .T&, and .TE.  They do not support the mm macro extensions, .TS H
      and .TH (see mm(5)).

      In general, avoid using the man macros within a table, particularly
      the font macros, which can produce peculiar and unpredictable results.
      Use the nroff/troff intrinsic macros instead.  For example, to specify
      bold type, use the in-line macro \fB, or, more generally, \f3.  To
      insert horizontal blank lines, you can use the .PP or .IP macro,
      depending on which one preceded the table, but you must then avoid
      using the center and expand table format specifications.  Otherwise,
      indentation will be erratic.

 WARNINGS    [Toc]    [Back]
      HP no longer uses the NAME section to prepare the Table of Contents
      and Index for the printed manual.  Instead, that information is coded
      as comments at the end of each manpage source file where it can be
      accessed by various tools and programs as desired.  The NAME section
      is still used for the whatis database, as described below.

      The macro package used to print the HP-UX Reference increases the
      interword spaces (to eliminate ambiguity) in the SYNOPSIS section of
      each entry.

      In addition to the macros, strings, and number registers mentioned
      above, a number of internal macros, strings, and number registers are
      defined.  These include

        +  The names predefined by the nroff/troff processor.

        +  The macro th,

        +  The number register :m,

        +  Macro, string, and number names in the forms )x, ]x, and }x,
           where x stands for some alphanumeric character,

        +  Macro, string, and number names in the form XY, where X and Y are
           capital letters.

    Fonts    [Toc]    [Back]
      nroff uses only three fonts: roman, italic, and bold, designated as

 Hewlett-Packard Company            - 9 -   HP-UX 11i Version 2: August 2003

 man(5)                                                               man(5)

      font positions 1, 2, and 3, respectively.  The constant-width font
      macros in the macro package (.C, .RC, .IC, .BC, .CR, .CI, .CB)
      simulate a constant-width font with the bold font, since all nroff
      output is constant width or typewriter format.

      To use a true constant-width font with troff, change the corresponding
      font 3 specification in each constant-width font macro to font 4 and
      mount a constant-width font in position 4 using a troff .fp request,
      as in:

           .fp 4 CW

    The whatis Database    [Toc]    [Back]
      The NAME section of each manpage is processed by catman (see
      catman(1M)) to create an entry in the whatis database, which is used
      by the -f and -k options of the man command.  catman processes the
      lines of the NAME section into a single line in the format:

           name[, name]... - explanatory-text

      Hyphens (typed as - or \-), en-dashes (\(mi), and em-dashes (\(em) are
      treated equivalently.  The last space-hyphen-space in the line becomes
      the dividing point between names and explanatory text.

 FILES    [Toc]    [Back]

           The man macros.


           Called by man.  Sources (.so) the macros in
           /usr/share/lib/macros/an.  Other macro files can be specified
           here to accommodate manpages with additional macro requirements.


           File of strings from manpage NAME sections, created by catman,
           and used by the man -k and -f options.

 SEE ALSO    [Toc]    [Back]
      col(1), man(1), neqn(1), nroff(1), tbl(1), catman(1M), mm(5).

 Hewlett-Packard Company           - 10 -   HP-UX 11i Version 2: August 2003
[ Back ]
 Similar pages
Name OS Title
me NetBSD macros for formatting papers
orig_me FreeBSD macros for formatting papers
me Tru64 Macros for formatting papers
ms Tru64 Text formatting macros
groff_me OpenBSD troff macros for formatting papers
me FreeBSD troff macros for formatting papers
me OpenBSD troff macros for formatting papers
groff_me FreeBSD troff macros for formatting papers
msg IRIX Text formatting macros for UNICOS and IRIX messages
sbuf_cpy FreeBSD safe string formatting
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service