LinuxGuruz
  • Last 5 Forum Topics
    Replies
    Views
    Last post


The Web Only This Site
  • BOOKMARK

  • ADD TO FAVORITES

  • REFERENCES


  • MARC

    Mailing list ARChives
    - Search by -
     Subjects
     Authors
     Bodies





    FOLDOC

    Computing Dictionary




  • Text Link Ads






  • LINUX man pages
  • Linux Man Page Viewer


    The following form allows you to view linux man pages.

    Command:

    groff_mdoc

    
    
    
    

    DESCRIPTION

         A complete reference for writing UNIX manual pages with the -mdoc macro
         package; a content-based and domain-based formatting package for GNU
         troff(1).  Its predecessor, the -man(7) package, addressed page layout
         leaving the manipulation of fonts and other typesetting details to the
         individual author.  In -mdoc, page layout macros make up the page
         structure domain which consists of macros for titles, section headers,
         displays and lists - essentially items which affect the physical position
         of text on a formatted page.  In addition to the page structure domain,
         there are two more domains, the manual domain and the general text
         domain.  The general text domain is defined as macros which perform tasks
         such as quoting or emphasizing pieces of text.  The manual domain is
         defined as macros that are a subset of the day to day informal language
         used to describe commands, routines and related UNIX files.  Macros in
         the manual domain handle command names, command line arguments and
         options, function names, function parameters, pathnames, variables, cross
         references to other manual pages, and so on.  These domain items have
         value for both the author and the future user of the manual page.  Hope-
         fully, the consistency gained across the manual set will provide easier
         translation to future documentation tools.
    
         Throughout the UNIX manual pages, a manual entry is simply referred to as
         a man page, regardless of actual length and without sexist intention.
    
    
    

    GETTING STARTED

         The material presented in the remainder of this document is outlined as
         follows:
    
               1.   TROFF IDIOSYNCRASIES
                    Macro Usage
                    Passing Space Characters in an Argument
                    Trailing Blank Space Characters
                    Escaping Special Characters
                    Other Possible Pitfalls
    
               2.   A MANUAL PAGE TEMPLATE
    
               3.   CONVENTIONS
    
               4.   TITLE MACROS
    
               5.   INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS
                    What's in a Name...
                    General Syntax
    
               6.   MANUAL DOMAIN
                    Addresses
                    Author Name
                    Arguments
                    Configuration Declarations (Section Four Only)
                    Command Modifiers
                    Options
                    Pathnames
                    Standards
                    Variable Types
                    Variables
                    Manual Page Cross References
    
               7.   GENERAL TEXT DOMAIN
                    AT&T Macro
                    BSD Macro
                    NetBSD Macro
                    FreeBSD Macro
                    OpenBSD Macro
                    BSD/OS Macro
                    UNIX Macro
                    Emphasis Macro
                    Font Mode
                    Enclosure and Quoting Macros
                    No-Op or Normal Text Macro
                    No-Space Macro
                    Section Cross References
                    Symbolics
                    Mathematical Symbols
                    References and Citations
                    Trade Names (or Acronyms and Type Names)
                    Extended Arguments
    
               8.   PAGE STRUCTURE DOMAIN
                    Section Headers
                    Subsection Headers
                    Paragraphs and Line Spacing
                    Keeps
                    Examples and Displays
                    Lists and Columns
    
               9.   MISCELLANEOUS MACROS
    
               10.  PREDEFINED STRINGS
    
               11.  DIAGNOSTICS
    
               12.  FORMATTING WITH GROFF, TROFF, AND NROFF
    
               13.  FILES
    
               14.  SEE ALSO
    
               15.  BUGS
    
    
    

    TROFF IDIOSYNCRASIES

         The -mdoc package attempts to simplify the process of writing a man page.
         Theoretically, one should not have to learn the tricky details of GNU
         with the '\&' escape sequence which translates literally to a zero-width
         space, and is never displayed in the output.
    
         In general, GNU troff(1) macros accept an unlimited number of arguments
         (contrary to other versions of troff which can't handle more than nine
         arguments).  In limited cases, arguments may be continued or extended on
         the next line (See Extended Arguments below).  Almost all macros handle
         quoted arguments (see Passing Space Characters in an Argument below).
    
         Most of the -mdoc general text domain and manual domain macros are spe-
         cial in that their argument lists are parsed for callable macro names.
         This means an argument on the argument list which matches a general text
         or manual domain macro name (and which is defined to be callable) will be
         executed or called when it is processed.  In this case the argument,
         although the name of a macro, is not preceded by a '.' (dot).  This makes
         it possible to nest macros; for example the option macro, '.Op', may call
         the flag and argument macros, 'Fl' and 'Ar', to specify an optional flag
         with an argument:
    
               [-s bytes]  is produced by '.Op Fl s Ar bytes'
    
         To prevent a string from being interpreted as a macro name, precede the
         string with the escape sequence '\&':
    
               [Fl s Ar bytes]  is produced by '.Op \&Fl s \&Ar bytes'
    
         Here the strings 'Fl' and 'Ar' are not interpreted as macros.  Macros
         whose argument lists are parsed for callable arguments are referred to as
         parsed and macros which may be called from an argument list are referred
         to as callable throughout this document.  This is a technical faux pas as
         almost all of the macros in -mdoc are parsed, but as it was cumbersome to
         constantly refer to macros as being callable and being able to call other
         macros, the term parsed has been used.
    
         In the following, we call an -mdoc macro which starts a line (with a
         leading dot) a command if this distinction is necessary.
    
       Passing Space Characters in an Argument
         Sometimes it is desirable to give as an argument a string containing one
         or more blank space characters, say, to specify arguments to commands
         which expect particular arrangement of items in the argument list.  Addi-
         tionally, it makes -mdoc working faster.  For example, the function com-
         mand '.Fn' expects the first argument to be the name of a function and
         any remaining arguments to be function parameters.  As ANSI C stipulates
         the declaration of function parameters in the parenthesized parameter
         list, each parameter is guaranteed to be at minimum a two word string.
         For example, int foo.
    
         There are two possible ways to pass an argument which contains an embed-
         ded space.  One way of passing a string containing blank spaces is to use
         the hard or unpaddable space character '\ ', that is, a blank space pre-
         ceded by the escape character '\'.  This method may be used with any
    
         If the '\' before the space in the first example or double quotes in the
         second example were omitted, '.Fn' would see three arguments, and the
         result would be:
    
               fetch(char, *str)
    
       Trailing Blank Space Characters
         Troff can be confused by blank space characters at the end of a line.  It
         is a wise preventive measure to globally remove all blank spaces from
         <blank-space><end-of-line> character sequences.  Should the need arise to
         use a blank character at the end of a line, it may be forced with an
         unpaddable space and the '\&' escape character.  For example,
         'string\ \&'.
    
       Escaping Special Characters
         Special characters like the newline character '\n' are handled by replac-
         ing the '\' with '\e' (e.g. '\en') to preserve the backslash.
    
       Other Possible Pitfalls
         A warning is emitted when an empty input line is found outside of dis-
         plays (see below).  Use '.sp' instead.  (Well, it is even better to use
         -mdoc macros to avoid the usage of low-level commands.)
    
         Leading spaces will cause a break and are output directly.  Avoid this
         behaviour if possible.  Similarly, do not use more than one space charac-
         ter between words in an ordinary text line; contrary to other text for-
         matters, they are not replaced with a single space.
    
         You can't pass '"' directly as an argument.  Use '\*[q]' (or '\*q')
         instead.
    
         By default, troff(1) inserts two space characters after a punctuation
         mark closing a sentence; characters like ')' or ''' are treated transpar-
         ently, not influencing the sentence-ending behaviour.  To change this,
         insert '\&' before or after the dot:
    
               The
               .Ql .
               character.
               .Pp
               The
               .Ql \&.
               character.
               .Pp
               .No test .
               test
               .Pp
               .No test.
               test
    
         gives
         A comment in the source file of a man page can be either started with
         '.\"' on a single line, '\"' after some input, or '\#' anywhere (the lat-
         ter is a GNU troff(1) extension); the rest of such a line is ignored.
    
    
    

    A MANUAL PAGE TEMPLATE

         The body of a man page is easily constructed from a basic template:
    
               .\" The following commands are required for all man pages.
               .Dd Month day, year
               .Os [OPERATING_SYSTEM] [version/release]
               .Dt DOCUMENT_TITLE [section number] [architecture/volume]
               .Sh NAME
               .Nm name
               .Nd one line description of name
               .\" This next command is for sections 2 and 3 only.
               .\" .Sh LIBRARY
               .Sh SYNOPSIS
               .Sh DESCRIPTION
               .\" The following commands should be uncommented and
               .\" used where appropriate.
               .\" .Sh IMPLEMENTATION NOTES
               .\" This next command is for sections 2, 3 and 9 function
               .\" return values only.
               .\" .Sh RETURN VALUES
               .\" This next command is for sections 1, 6, 7 and 8 only.
               .\" .Sh ENVIRONMENT
               .\" .Sh FILES
               .\" .Sh EXAMPLES
               .\" This next command is for sections 1, 6, 7, 8 and 9 only
               .\"     (command return values (to shell) and
               .\"     fprintf/stderr type diagnostics).
               .\" .Sh DIAGNOSTICS
               .\" .Sh COMPATIBILITY
               .\" This next command is for sections 2, 3 and 9 error
               .\"     and signal handling only.
               .\" .Sh ERRORS
               .\" .Sh SEE ALSO
               .\" .Sh STANDARDS
               .\" .Sh HISTORY
               .\" .Sh AUTHORS
               .\" .Sh BUGS
    
         The first items in the template are the commands '.Dd', '.Os', and '.Dt';
         the document date, the operating system the man page or subject source is
         developed or modified for, and the man page title (in upper case) along
         with the section of the manual the page belongs in.  These commands iden-
         tify the page and are discussed below in TITLE MACROS.
    
         The remaining items in the template are section headers (.Sh); of which
         NAME, SYNOPSIS, and DESCRIPTION are mandatory.  The headers are discussed
         in PAGE STRUCTURE DOMAIN, after presentation of MANUAL DOMAIN.  Several
         content macros are used to demonstrate page layout macros; reading about
         Except stated explicitly, all macros are parsed and callable.
    
         Note that a macro takes effect up to the next nested macro.  For example,
         '.Ic foo Aq bar' doesn't produce 'foo <bar>' but 'foo <bar>'.  Conse-
         quently, a warning message is emitted for most commands if the first
         argument is a macro itself since it cancels the effect of the calling
         command completely.  Another consequence is that quoting macros never
         insert literal quotes; 'foo <bar>' has been produced by '.Ic "foo
         <bar>"'.
    
         Most macros have a default width value which can be used to specify a
         label width (-width) or offset (-offset) for the '.Bl' and '.Bd' macros.
         It is recommended not to use this rather obscure feature to avoid depen-
         dencies on local modifications of the -mdoc package.
    
    
    

    TITLE MACROS

         The title macros are part of the page structure domain but are presented
         first and separately for someone who wishes to start writing a man page
         yesterday.  Three header macros designate the document title or manual
         page title, the operating system, and the date of authorship.  These
         macros are called once at the very beginning of the document and are used
         to construct headers and footers only.
    
         .Dt [<document title>] [<section number>] [<volume>]
                 The document title is the subject of the man page and must be in
                 CAPITALS due to troff limitations.  If omitted, 'UNTITLED' is
                 used.  The section number may be a number in the range 1, ..., 9
                 or 'unass', 'draft', or 'paper'.  If it is specified, and no vol-
                 ume name is given, a default volume name is used.
    
                 Under BSD, the following sections are defined:
    
                       1        BSD General Commands Manual
                       2        BSD System Calls Manual
                       3        BSD Library Functions Manual
                       4        BSD Kernel Interfaces Manual
                       5        BSD File Formats Manual
                       6        BSD Games Manual
                       7        BSD Miscellaneous Information Manual
                       8        BSD System Manager's Manual
                       9        BSD Kernel Developer's Manual
    
                 A volume name may be arbitrary or one of the following:
    
                       USD      User's Supplementary Documents
                       PS1      Programmer's Supplementary Documents
                       AMD      Ancestral Manual Documents
                       SMM      System Manager's Manual
                       URM      User's Reference Manual
                       PRM      Programmer's Manual
                       KM       Kernel Manual
                       IND      Manual Master Index
                       sparc64, sun3, tahoe, vax, x68k
    
                 In the following examples, the left (which is identical to the
                 right) and the middle part of the manual page header strings are
                 shown.
    
                       .Dt FOO 7       'FOO(7)' 'BSD Miscellaneous Information
                                       Manual'
                       .Dt FOO 2 i386  'FOO(2)' 'BSD/i386 System Calls Manual'
                       .Dt FOO "" bar  'FOO' 'bar'
    
                 Local, OS-specific additions might be found in the file
                 mdoc.local; look for strings named 'volume-ds-XXX' (for the for-
                 mer type) and 'volume-as-XXX' (for the latter type); 'XXX' then
                 denotes the keyword to be used with the '.Dt' macro.
    
                 This macro is neither callable nor parsed.
    
         .Os [<operating system>] [<release>]
                 If the first parameter is empty, the default 'BSD' is used.  This
                 may be overridden in the local configuration file, mdoc.local.
                 In general, the name of the operating system should be the common
                 acronym, e.g. BSD or ATT.  The release should be the standard
                 release nomenclature for the system specified.  In the following
                 table, the possible second arguments for some predefined operat-
                 ing systems are listed.  Similar to '.Dt', local additions might
                 be defined in mdoc.local; look for strings named
                 'operating-system-XXX-YYY', where 'XXX' is the acronym for the
                 operating system and 'YYY' the release ID.
    
                       ATT      7th, 7, III, 3, V, V.2, V.3, V.4
    
                       BSD      3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4
    
                       NetBSD   0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a,
                                1.2b, 1.2c, 1.2d, 1.2e, 1.3, 1.3a, 1.4, 1.5, 1.6
    
                       FreeBSD  1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5,
                                2.1.6, 2.1.7, 2.2, 2.2.1, 2.2.2, 2.2.5, 2.2.6,
                                2.2.7, 2.2.8, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 4.0,
                                4.1, 4.2, 4.3, 4.4, 4.5, 5.0
    
                 For ATT, an unknown second parameter will be replaced with the
                 string UNIX; for the other predefined acronyms it will be ignored
                 and a warning message emitted.  Unrecognized arguments are dis-
                 played as given in the page footer.  For instance, a typical
                 footer might be:
    
                       .Os BSD 4.3
    
                 giving '4.3 Berkeley Distribution', or for a locally produced set
    
                       .Dd January 25, 2001
    
                 Otherwise, the current date is used, ignoring the parameters.
    
                 This macro is neither callable nor parsed.
    
    
    

    INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS

       What's in a Name...
         The manual domain macro names are derived from the day to day informal
         language used to describe commands, subroutines and related files.
         Slightly different variations of this language are used to describe the
         three different aspects of writing a man page.  First, there is the
         description of -mdoc macro command usage.  Second is the description of a
         UNIX command with -mdoc macros, and third, the description of a command
         to a user in the verbal sense; that is, discussion of a command in the
         text of a man page.
    
         In the first case, troff(1) macros are themselves a type of command; the
         general syntax for a troff command is:
    
               .Xx argument1 argument2 ...
    
         '.Xx' is a macro command, and anything following it are arguments to be
         processed.  In the second case, the description of a UNIX command using
         the content macros is a bit more involved; a typical SYNOPSIS command
         line might be displayed as:
    
               filter [-flag] <infile> <outfile>
    
         Here, filter is the command name and the bracketed string -flag is a flag
         argument designated as optional by the option brackets.  In -mdoc terms,
         <infile> and <outfile> are called meta arguments; in this example, the
         user has to replace the meta expressions given in angle brackets with
         real file names.  Note that in this document meta arguments are used to
         describe -mdoc commands; in most man pages, meta variables are not
         specifically written with angle brackets.  The macros which formatted the
         above example:
    
               .Nm filter
               .Op Fl flag
               .Ao Ar infile Ac Ao Ar outfile Ac
    
         In the third case, discussion of commands and command syntax includes
         both examples above, but may add more detail.  The arguments <infile> and
         <outfile> from the example above might be referred to as operands or file
         arguments.  Some command line argument lists are quite long:
    
               make  [-eiknqrstv] [-D variable] [-d flags] [-f makefile] [-I
                     directory] [-j max_jobs] [variable=value] [target ...]
    
         Here one might talk about the command make and qualify the argument,
         makefile, as an argument to the flag, -f, or discuss the optional file
               .Bk
               .Op Ar target ...
               .Ek
    
         The '.Bk' and '.Ek' macros are explained in Keeps.
    
       General Syntax
         The manual domain and general text domain macros share a similar syntax
         with a few minor deviations; most notably, '.Ar', '.Fl', '.Nm', and '.Pa'
         differ only when called without arguments; and '.Fn' and '.Xr' impose an
         order on their argument lists.  All content macros are capable of recog-
         nizing and properly handling punctuation, provided each punctuation char-
         acter is separated by a leading space.  If a command is given:
    
               .Ar sptr, ptr),
    
         The result is:
    
               sptr, ptr),
    
         The punctuation is not recognized and all is output in the font used by
         '.Ar'.  If the punctuation is separated by a leading white space:
    
               .Ar sptr , ptr ) ,
    
         The result is:
    
               sptr, ptr),
    
         The punctuation is now recognized and output in the default font distin-
         guishing it from the argument strings.  To remove the special meaning
         from a punctuation character escape it with '\&'.
    
         Troff is limited as a macro language, and has difficulty when presented
         with a string containing a member of the mathematical, logical or quota-
         tion set:
    
                     {+,-,/,*,%,<,>,<=,>=,=,==,&,',',"}
    
         The problem is that troff may assume it is supposed to actually perform
         the operation or evaluation suggested by the characters.  To prevent the
         accidental evaluation of these characters, escape them with '\&'.  Typi-
         cal syntax is shown in the first content macro displayed below, '.Ad'.
    
    
    

    MANUAL DOMAIN

       Addresses
         The address macro identifies an address construct.
    
               Usage: .Ad <address> ...
    
                        .Ad addr1           addr1
                        .Ad addr1 .         addr1.
                        .An "Joe Author" ,      Joe Author,
    
                        .An "Joe Author" Aq nobody@FreeBSD.org
                                                Joe Author <nobody@FreeBSD.org>
    
                        .An "Joe Author" ) ) ,  Joe Author)),
    
         The default width is 12n.
    
         In the AUTHORS section, the '.An' command causes a line break allowing
         each new name to appear on its own line.  If this is not desirable,
    
               .An -nosplit
    
         call will turn this off.  To turn splitting back on, write
    
               .An -split
    
       Arguments
         The .Ar argument macro may be used whenever an argument is referenced.
         If called without arguments, the 'file ...' string is output.
    
               Usage: .Ar [<argument>] ...
    
                        .Ar              file ...
                        .Ar file1        file1
                        .Ar file1 .      file1.
                        .Ar file1 file2  file1 file2
                        .Ar f1 f2 f3 :   f1 f2 f3:
                        .Ar file ) ) ,   file)),
    
         The default width is 12n.
    
       Configuration Declaration (Section Four Only)
         The '.Cd' macro is used to demonstrate a config(8) declaration for a
         device interface in a section four manual.
    
               Usage: .Cd <argument> ...
    
                        .Cd "device le0 at scode?"  device le0 at scode?
    
         In the SYNOPSIS section a '.Cd' command causes a line break before and
         after its arguments are printed.
    
         The default width is 12n.
    
       Command Modifiers
         The command modifier is identical to the '.Fl' (flag) command with the
         exception that the '.Cm' macro does not assert a dash in front of every
         argument.  Traditionally flags are marked by the preceding dash, however,
         some commands or subsets of commands do not use them.  Command modifiers
         may also be specified in conjunction with interactive commands such as
    
       Errno's
         The '.Er' errno macro specifies the error return value for section 2, 3,
         and 9 library routines.  The second example below shows '.Er' used with
         the '.Bq' general text domain macro, as it would be used in a section two
         manual page.
    
               Usage: .Er <errno type> ...
    
                        .Er ENOENT      ENOENT
                        .Er ENOENT ) ;  ENOENT);
                        .Bq Er ENOTDIR  [ENOTDIR]
    
         The default width is 17n.
    
       Environment Variables
         The '.Ev' macro specifies an environment variable.
    
               Usage: .Ev <argument> ...
    
                        .Ev DISPLAY        DISPLAY
                        .Ev PATH .         PATH.
                        .Ev PRINTER ) ) ,  PRINTER)),
    
         The default width is 15n.
    
       Flags
         The '.Fl' macro handles command line flags.  It prepends a dash, '-', to
         the flag.  For interactive command flags, which are not prepended with a
         dash, the '.Cm' (command modifier) macro is identical, but without the
         dash.
    
               Usage: .Fl <argument> ...
    
                        .Fl          -
                        .Fl cfv      -cfv
                        .Fl cfv .    -cfv.
                        .Cm cfv .    cfv.
                        .Fl s v t    -s -v -t
                        .Fl - ,      --,
                        .Fl xyz ) ,  -xyz),
                        .Fl |        - |
    
         The '.Fl' macro without any arguments results in a dash representing
         stdin/stdout.  Note that giving '.Fl' a single dash will result in two
         dashes.
    
         The default width is 12n.
    
       Function Declarations
         The '.Fd' macro is used in the SYNOPSIS section with section two or three
         functions.  It is neither callable nor parsed.
               Usage: .In <header file>
    
                        .In stdio.h  #include <stdio.h>
    
       Function Types
         This macro is intended for the SYNOPSIS section.  It may be used anywhere
         else in the man page without problems, but its main purpose is to present
         the function type in kernel normal form for the SYNOPSIS of sections two
         and three (it causes a line break, allowing the function name to appear
         on the next line).
    
               Usage: .Ft <type> ...
    
                        .Ft struct stat  struct stat
    
       Functions (Library Routines)
         The '.Fn' macro is modeled on ANSI C conventions.
    
               Usage: .Fn <function> [<parameter>] ...
    
                        .Fn getchar              getchar()
                        .Fn strlen ) ,           strlen()),
                        .Fn align "char *ptr" ,  align(char *ptr),
    
         Note that any call to another macro signals the end of the '.Fn' call (it
         will insert a closing parenthesis at that point).
    
         For functions with many parameters (which is rare), the macros '.Fo'
         (function open) and '.Fc' (function close) may be used with '.Fa' (func-
         tion argument).
    
         Example:
    
               .Ft int
               .Fo res_mkquery
               .Fa "int op"
               .Fa "char *dname"
               .Fa "int class"
               .Fa "int type"
               .Fa "char *data"
               .Fa "int datalen"
               .Fa "struct rrec *newrr"
               .Fa "char *buf"
               .Fa "int buflen"
               .Fc
    
         Produces:
    
               int res_mkquery(int op, char *dname, int class, int type,
               char *data, int datalen, struct rrec *newrr, char *buf, int buflen)
    
         In the SYNOPSIS section, the function will always begin at the beginning
               Usage: .Fa <function argument> ...
    
                        .Fa d_namlen ) ) ,  d_namlen)),
                        .Fa iov_len         iov_len
    
         The default width is 12n.
    
       Return Values
         The '.Rv' macro generates text for use in the RETURN VALUES section.
    
               Usage: .Rv [-std] [<function> ...]
    
         For example, '.Rv -std atexit' produces:
    
                The atexit() function returns the value 0 if successful; otherwise
                the value -1 is returned and the global variable errno is set to
                indicate the error.
    
         The -std option is valid only for manual page sections 2 and 3.  Cur-
         rently, this macro does nothing if used without the -std flag.
    
       Exit Status
         The '.Ex' macro generates text for use in the DIAGNOSTICS section.
    
               Usage: .Ex [-std] [<utility> ...]
    
         For example, '.Ex -std cat' produces:
    
                The cat utility exits 0 on success, and >0 if an error occurs.
    
         The -std option is valid only for manual page sections 1, 6 and 8.  Cur-
         rently, this macro does nothing if used without the -std flag.
    
       Interactive Commands
         The '.Ic' macro designates an interactive or internal command.
    
               Usage: .Ic <argument> ...
    
                        .Ic :wq                :wq
                        .Ic "do while {...}"   do while {...}
                        .Ic setenv , unsetenv  setenv, unsetenv
    
         The default width is 12n.
    
       Library Names
         The '.Lb' macro is used to specify the library where a particular func-
         tion is compiled in.
    
               Usage: .Lb <argument> ...
    
         Available arguments to '.Lb' and their results are:
    
               libtermcap   Termcap Access Library (libtermcap, -ltermcap)
               libutil      System Utilities Library (libutil, -lutil)
               libz         Compression Library (libz, -lz)
    
         Local, OS-specific additions might be found in the file mdoc.local; look
         for strings named 'str-Lb-XXX'.  'XXX' then denotes the keyword to be
         used with the '.Lb' macro.
    
       Literals
         The '.Li' literal macro may be used for special characters, variable con-
         stants, etc. -- anything which should be displayed as it would be typed.
    
               Usage: .Li <argument> ...
    
                        .Li \en          \n
                        .Li M1 M2 M3 ;   M1 M2 M3;
                        .Li cntrl-D ) ,  cntrl-D),
                        .Li 1024 ...     1024 ...
    
         The default width is 16n.
    
       Names
         The '.Nm' macro is used for the document title or subject name.  It has
         the peculiarity of remembering the first argument it was called with,
         which should always be the subject name of the page.  When called without
         arguments, '.Nm' regurgitates this initial name for the sole purpose of
         making less work for the author.  Note: A section two or three document
         function name is addressed with the '.Nm' in the NAME section, and with
         '.Fn' in the SYNOPSIS and remaining sections.  For interactive commands,
         such as the 'while' command keyword in csh(1), the '.Ic' macro should be
         used.  While '.Ic' is nearly identical to '.Nm', it can not recall the
         first argument it was invoked with.
    
               Usage: .Nm [<argument>] ...
    
                        .Nm groff_mdoc  groff_mdoc
                        .Nm \-mdoc      -mdoc
                        .Nm foo ) ) ,   foo)),
                        .Nm :           groff_mdoc:
    
         The default width is 10n.
    
       Options
         The '.Op' macro places option brackets around any remaining arguments on
         the command line, and places any trailing punctuation outside the brack-
         ets.  The macros '.Oo' and '.Oc' (which produce an opening and a closing
         option bracket respectively) may be used across one or more lines or to
         specify the exact position of the closing parenthesis.
    
               Usage: .Op [<option>] ...
    
                        .Op                                []
    
               .Op Fl c Ar count
               .Oc
    
         Produces:
    
               [[-k kilobytes] [-i interval] [-c count]]
    
         The default width values of '.Op' and '.Oo' are 14n and 10n, respec-
         tively.
    
       Pathnames
         The '.Pa' macro formats path or file names.  If called without arguments,
         the '~' string is output, which represents the current user's home direc-
         tory.
    
               Usage: .Pa [<pathname>] ...
    
                        .Pa                    ~
                        .Pa /usr/share         /usr/share
                        .Pa /tmp/fooXXXXX ) .  /tmp/fooXXXXX).
    
         The default width is 32n.
    
       Standards
         The '.St' macro replaces standard abbreviations with their formal names.
    
               Usage: .St <abbreviation> ...
    
         Available pairs for "Abbreviation/Formal Name" are:
    
         ANSI/ISO C
    
               -ansiC         ANSI X3.159-1989 ("ANSI C")
               -ansiC-89      ANSI X3.159-1989 ("ANSI C")
               -isoC          ISO/IEC 9899:1990 ("ISO C89")
               -isoC-99       ISO/IEC 9899:1999 ("ISO C99")
    
         POSIX Part 1: System API
    
               -iso9945-1-90   ISO/IEC 9945-1:1990 ("POSIX.1")
               -iso9945-1-96   ISO/IEC 9945-1:1996 ("POSIX.1")
               -p1003.1        IEEE Std 1003.1 ("POSIX.1")
               -p1003.1-88     IEEE Std 1003.1-1988 ("POSIX.1")
               -p1003.1-90     ISO/IEC 9945-1:1990 ("POSIX.1")
               -p1003.1-96     ISO/IEC 9945-1:1996 ("POSIX.1")
               -p1003.1b-93    IEEE Std 1003.1b-1993 ("POSIX.1")
               -p1003.1c-95    IEEE Std 1003.1c-1995 ("POSIX.1")
               -p1003.1g-2000  IEEE Std 1003.1g-2000 ("POSIX.1")
               -p1003.1i-95    IEEE Std 1003.1i-1995 ("POSIX.1")
    
         POSIX Part 2: Shell and Utilities
    
               -xcurses4.2     X/Open Curses Issue 4.2 ("XCURSES4.2")
               -xns5           X/Open Networking Services Issue 5 ("XNS5")
               -xns5.2         X/Open Networking Services Issue 5.2 ("XNS5.2")
               -xpg3           X/Open Portability Guide Issue 3 ("XPG3")
               -xpg4           X/Open Portability Guide Issue 4 ("XPG4")
               -xpg4.2         X/Open Portability Guide Issue 4.2 ("XPG4.2")
               -xsh5           X/Open System Interfaces and Headers Issue 5
                               ("XSH5")
    
         Miscellaneous
    
               -ieee754        IEEE Std 754-1985
               -iso8802-3      ISO/IEC 8802-3:1989
    
       Variable Types
         The '.Vt' macro may be used whenever a type is referenced.  In the
         SYNOPSIS section, it causes a line break (useful for old style variable
         declarations).
    
               Usage: .Vt <type> ...
    
                        .Vt extern char *optarg ;  extern char *optarg;
                        .Vt FILE *                 FILE *
    
       Variables
         Generic variable reference.
    
               Usage: .Va <variable> ...
    
                        .Va count             count
                        .Va settimer ,        settimer,
                        .Va "int *prt" ) :    int *prt):
                        .Va "char s" ] ) ) ,  char s])),
    
         The default width is 12n.
    
       Manual Page Cross References
         The '.Xr' macro expects the first argument to be a manual page name.  The
         optional second argument, if a string (defining the manual section), is
         put into parentheses.
    
               Usage: .Xr <man page name> [<section>] ...
    
                        .Xr mdoc        mdoc
                        .Xr mdoc ,      mdoc,
                        .Xr mdoc 7      mdoc(7)
                        .Xr xinit 1x ;  xinit(1x);
    
         The default width is 10n.
    
    
    

    GENERAL TEXT DOMAIN

       AT&T Macro
                        .Bx 4.3 .   4.3BSD.
                        .Bx -devel  BSD (currently under development)
    
         <version> will be prepended to the string 'BSD'.  The following values
         for <release> are possible:
    
               Reno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2
    
       NetBSD Macro
               Usage: .Nx [<version>] ...
    
                        .Nx        NetBSD
                        .Nx 1.4 .  NetBSD 1.4.
    
         For possible values of <version> see the description of the '.Os' command
         above in section TITLE MACROS.
    
       FreeBSD Macro
               Usage: .Fx [<version>] ...
    
                        .Fx        FreeBSD
                        .Fx 2.2 .  FreeBSD 2.2.
    
         For possible values of <version> see the description of the '.Os' command
         above in section TITLE MACROS.
    
       OpenBSD Macro
               Usage: .Ox [<version>] ...
    
                        .Ox 1.0  OpenBSD 1.0
    
       BSD/OS Macro
               Usage: .Bsx [<version>] ...
    
                        .Bsx 1.0  BSD/OS 1.0
    
       UNIX Macro
               Usage: .Ux ...
    
                        .Ux  UNIX
    
       Emphasis Macro
         Text may be stressed or emphasized with the '.Em' macro.  The usual font
         for emphasis is italic.
    
               Usage: .Em <argument> ...
    
                        .Em does not          does not
                        .Em exceed 1024 .     exceed 1024.
                        .Em vide infra ) ) ,  vide infra)),
    
         The default width is 10n.
                               block of text.
               Sy | -symbolic  Same as if the '.Sy' macro was used for the entire
                               block of text.
    
         Both macros are neither callable nor parsed.
    
       Enclosure and Quoting Macros
         The concept of enclosure is similar to quoting.  The object being to
         enclose one or more strings between a pair of characters like quotes or
         parentheses.  The terms quoting and enclosure are used interchangeably
         throughout this document.  Most of the one-line enclosure macros end in
         small letter 'q' to give a hint of quoting, but there are a few irregu-
         larities.  For each enclosure macro there is also a pair of open and
         close macros which end in small letters 'o' and 'c' respectively.
    
             Quote   Open    Close  Function                  Result
             .Aq     .Ao     .Ac    Angle Bracket Enclosure   <string>
             .Bq     .Bo     .Bc    Bracket Enclosure         [string]
             .Brq    .Bro    .Brc   Brace Enclosure           {string}
             .Dq     .Do     .Dc    Double Quote              "string"
             .Eq     .Eo     .Ec    Enclose String (in XX)    XXstringXX
             .Pq     .Po     .Pc    Parenthesis Enclosure     (string)
             .Ql                    Quoted Literal            'string' or string
             .Qq     .Qo     .Qc    Straight Double Quote     "string"
             .Sq     .So     .Sc    Single Quote              'string'
    
         All macros ending with 'q' and 'o' have a default width value of 12n.
    
         .Eo, .Ec  These macros expect the first argument to be the opening and
                   closing strings respectively.
    
         .Es, .En  Due to the nine-argument limit in the original troff program
                   two other macros have been implemented which are now rather
                   obsolete: '.Es' takes the first and second parameter as the
                   left and right enclosure string, which are then used to enclose
                   the arguments of '.En'.  The default width value is 12n for
                   both macros.
    
         .Eq       The first and second arguments of this macro are the opening
                   and closing strings respectively, followed by the arguments to
                   be enclosed.
    
         .Ql       The quoted literal macro behaves differently in troff and nroff
                   mode.  If formatted with nroff, a quoted literal is always
                   quoted.  If formatted with troff, an item is only quoted if the
                   width of the item is less than three constant width characters.
                   This is to make short strings more visible where the font
                   change to literal (constant width) is less noticeable.
    
                   The default width is 16n.
    
         .Pf       The prefix macro suppresses the whitespace between its first
               .Aq                      <>
               .Aq Pa ctype.h ) ,       <ctype.h>),
               .Bq                      []
               .Bq Em Greek , French .  [Greek, French].
               .Dq                      ""
               .Dq string abc .         "string abc".
               .Dq ?^[A-Z]?             "?^[A-Z]?"
               .Ql man mdoc             'man mdoc'
               .Qq                      ""
               .Qq string ) ,           "string"),
               .Qq string Ns ),         "string),"
               .Sq                      ''
               .Sq string               'string'
               .Em or Ap ing            or'ing
    
         For a good example of nested enclosure macros, see the '.Op' option
         macro.  It was created from the same underlying enclosure macros as those
         presented in the list above.  The '.Xo' and '.Xc' extended argument list
         macros are discussed below.
    
       No-Op or Normal Text Macro
         The '.No' macro can be used in a macro command line for parameters which
         should not be formatted.  Be careful to add '\&' to the word 'No' if you
         really want that English word (and not the macro) as a parameter.
    
               Usage: .No <argument> ...
    
                        .No test Ta with Ta tabs  test     with     tabs
    
         The default width is 12n.
    
       No-Space Macro
         The '.Ns' macro suppresses insertion of a space between the current posi-
         tion and its first parameter.  For example, it is useful for old style
         argument lists where there is no space between the flag and argument:
    
               Usage: ... <argument> Ns [<argument>] ...
                      .Ns <argument> ...
    
                        .Op Fl I Ns Ar directory  [-Idirectory]
    
         Note: The '.Ns' macro always invokes the '.No' macro after eliminating
         the space unless another macro name follows it.  If used as a command
         (i.e., the second form above in the 'Usage' line), '.Ns' is identical to
         '.No'.
    
       Section Cross References
         The '.Sx' macro designates a reference to a section header within the
         same document.
    
               Usage: .Sx <section reference> ...
    
       Mathematical Symbols
         Use this macro for mathematical symbols and similar things.
    
               Usage: .Ms <math symbol> ...
    
                        .Ms sigma  sigma
    
         The default width is 6n.
    
       References and Citations
         The following macros make a modest attempt to handle references.  At
         best, the macros make it convenient to manually drop in a subset of
         refer(1) style references.
    
               .Rs     Reference start (does not take arguments).  Causes a line
                       break in the SEE ALSO section and begins collection of ref-
                       erence information until the reference end macro is read.
               .Re     Reference end (does not take arguments).  The reference is
                       printed.
               .%A     Reference author name; one name per invocation.
               .%B     Book title.
               .%C     City/place (not implemented yet).
               .%D     Date.
               .%I     Issuer/publisher name.
               .%J     Journal name.
               .%N     Issue number.
               .%O     Optional information.
               .%P     Page number.
               .%Q     Corporate or foreign author.
               .%R     Report name.
               .%T     Title of article.
               .%V     Volume.
    
         Macros beginning with '%' are not callable but accept multiple arguments
         in the usual way.  Only the '.Tn' macro is handled properly as a parame-
         ter; other macros will cause strange output.  '.%B' and '.%T' can be used
         outside of the '.Rs/.Re' environment.
    
         Example:
    
               .Rs
               .%A "Matthew Bar"
               .%A "John Foo"
               .%T "Implementation Notes on foobar(1)"
               .%R "Technical Report ABC-DE-12-345"
               .%Q "Drofnats College, Nowhere"
               .%D "April 1991"
               .Re
    
         produces
    
               Matthew Bar and John Foo, Implementation Notes on foobar(1),
    
       Extended Arguments
         The .Xo and .Xc macros allow one to extend an argument list on a macro
         boundary for the '.It' macro (see below).  Note that .Xo and .Xc are
         implemented similarly to all other macros opening and closing an enclo-
         sure (without inserting characters, of course).  This means that the fol-
         lowing is true for those macros also.
    
         Here is an example of '.Xo' using the space mode macro to turn spacing
         off:
    
               .Sm off
               .It Xo Sy I Ar operation
               .No \en Ar count No \en
               .Xc
               .Sm on
    
         produces
    
               Ioperation\ncount\n
    
         Another one:
    
               .Sm off
               .It Cm S No / Ar old_pattern Xo
               .No / Ar new_pattern
               .No / Op Cm g
               .Xc
               .Sm on
    
         produces
    
               S/old_pattern/new_pattern/[g]
    
         Another example of '.Xo' and enclosure macros: Test the value of a vari-
         able.
    
               .It Xo
               .Ic .ifndef
               .Oo \&! Oc Ns Ar variable Oo
               .Ar operator variable ...
               .Oc Xc
    
         produces
    
               .ifndef [!]variable [operator variable ...]
    
    
    

    PAGE STRUCTURE DOMAIN

       Section Headers
         The following '.Sh' section header macros are required in every man page.
         The remaining section headers are recommended at the discretion of the
         author writing the manual page.  The '.Sh' macro is parsed but not gener-
         ally callable.  It can be used as an argument in a call to '.Sh' only; it
    
                            '.Nd' first prints '-', then all its arguments.
    
         .Sh LIBRARY        This section is for section two and three function
                            calls.  It should consist of a single '.Lb' macro
                            call; see Library Names.
    
         .Sh SYNOPSIS       The SYNOPSIS section describes the typical usage of
                            the subject of a man page.  The macros required are
                            either '.Nm', '.Cd', or '.Fn' (and possibly '.Fo',
                            '.Fc', '.Fd', and '.Ft').  The function name macro
                            '.Fn' is required for manual page sections 2 and 3;
                            the command and general name macro '.Nm' is required
                            for sections 1, 5, 6, 7, and 8.  Section 4 manuals
                            require a '.Nm', '.Fd' or a '.Cd' configuration device
                            usage macro.  Several other macros may be necessary to
                            produce the synopsis line as shown below:
    
                                  cat [-benstuv] [-] file ...
    
                            The following macros were used:
    
                                  .Nm cat
                                  .Op Fl benstuv
                                  .Op Fl
                                  .Ar
    
         .Sh DESCRIPTION    In most cases the first text in the DESCRIPTION sec-
                            tion is a brief paragraph on the command, function or
                            file, followed by a lexical list of options and
                            respective explanations.  To create such a list, the
                            '.Bl' (begin list), '.It' (list item) and '.El' (end
                            list) macros are used (see Lists and Columns below).
    
         .Sh IMPLEMENTATION NOTES
                            Implementation specific information should be placed
                            here.
    
         .Sh RETURN VALUES  Sections 2, 3 and 9 function return values should go
                            here.  The '.Rv' macro may be used to generate text
                            for use in the RETURN VALUES section for most section
                            2 and 3 library functions; see Return Values.
    
         The following '.Sh' section headers are part of the preferred manual page
         layout and must be used appropriately to maintain consistency.  They are
         listed in the order in which they would be used.
    
         .Sh ENVIRONMENT    The ENVIRONMENT section should reveal any related
                            environment variables and clues to their behavior
                            and/or usage.
    
         .Sh FILES          Files which are used or created by the man page sub-
         .Sh ERRORS         Specific error handling, especially from library func-
                            tions (man page sections 2, 3, and 9) should go here.
                            The '.Er' macro is used to specify an error (errno).
    
         .Sh SEE ALSO       References to other material on the man page topic and
                            cross references to other relevant man pages should be
                            placed in the SEE ALSO section.  Cross references are
                            specified using the '.Xr' macro.  Currently refer(1)
                            style references are not accommodated.
    
                            It is recommended that the cross references are sorted
                            on the section number, then alphabetically on the
                            names within a section, and placed in that order and
                            comma separated.  Example:
    
                            ls(1), ps(1), group(5), passwd(5)
    
         .Sh STANDARDS      If the command, library function or file adheres to a
                            specific implementation such as IEEE Std 1003.2
                            ("POSIX.2") or ANSI X3.159-1989 ("ANSI C") this should
                            be noted here.  If the command does not adhere to any
                            standard, its history should be noted in the HISTORY
                            section.
    
         .Sh HISTORY        Any command which does not adhere to any specific
                            standards should be outlined historically in this sec-
                            tion.
    
         .Sh AUTHORS        Credits should be placed here.  The '.An' macro should
                            be used to specify the name(s) of the person(s).
    
         .Sh BUGS           Blatant problems with the topic go here.
    
         User-specified '.Sh' sections may be added; for example, this section was
         set with:
    
                        .Sh "PAGE STRUCTURE DOMAIN"
    
       Subsection Headers
         Subsection headers have exactly the same syntax as section headers: '.Ss'
         is parsed but not generally callable.  It can be used as an argument in a
         call to '.Ss' only; it then reactivates the default font for '.Ss'.
    
         The default width is 8n.
    
       Paragraphs and Line Spacing
         .Pp  The '.Pp' paragraph command may be used to specify a line space
              where necessary.  The macro is not necessary after a '.Sh' or '.Ss'
              macro or before a '.Bl' or '.Bd' macro (which both assert a vertical
              distance unless the -compact flag is given).
    
              The macro is neither callable nor parsed and takes no arguments; an
    
         option should be added.
    
       Examples and Displays
         There are seven types of displays.
    
         .D1  (This is D-one.)  Display one line of indented text.  This macro is
              parsed but not callable.
    
                    -ldghfstru
    
              The above was produced by: .D1 Fl ldghfstru.
    
         .Dl  (This is D-ell.)  Display one line of indented literal text.  The
              '.Dl' example macro has been used throughout this file.  It allows
              the indentation (display) of one line of text.  Its default font is
              set to constant width (literal).  '.Dl' is parsed but not callable.
    
                    % ls -ldg /usr/local/bin
    
              The above was produced by: .Dl % ls -ldg /usr/local/bin.
    
         .Bd  Begin display.  The '.Bd' display must be ended with the '.Ed'
              macro.  It has the following syntax:
    
                    .Bd {-literal | -filled | -unfilled | -ragged | -centered}
                         [-offset <string>] [-file <file name>] [-compact]
    
              -ragged            Fill, but do not adjust the right margin (only
                                 left-justify).
              -centered          Center lines between the current left and right
                                 margin.  Note that each single line is centered.
              -unfilled          Do not fill; display a block of text as typed,
                                 using line breaks as specified by the user.  This
                                 can produce overlong lines without warning mes-
                                 sages.
              -filled            Display a filled block.  The block of text is
                                 formatted (i.e., the text is justified on both
                                 the left and right side).
              -literal           Display block with literal font (usually fixed-
                                 width).  Useful for source code or simple tabbed
                                 or spaced text.
              -file <file name>  The file whose name follows the -file flag is
                                 read and displayed before any data enclosed with
                                 '.Bd' and '.Ed', using the selected display type.
                                 Any troff/-mdoc commands in the file will be pro-
                                 cessed.
              -offset <string>   If -offset is specified with one of the following
                                 strings, the string is interpreted to indicate
                                 the level of indentation for the forthcoming
                                 block of text:
    
                                 left        Align block on the current left mar-
                                 indent-two  Indent two times the default indent
                                             value.
                                 right       This left aligns the block about two
                                             inches from the right side of the
                                             page.  This macro needs work and per-
                                             haps may never do the right thing
                                             within troff.
    
                                 If <string> is a valid numeric expression instead
                                 (with a scale indicator other than 'u'), use that
                                 value for indentation.  The most useful scale
                                 indicators are 'm' and 'n', specifying the so-
                                 called Em and En square.  This is approximately
                                 the width of the letters 'm' and 'n' respectively
                                 of the current font (for nroff output, both scale
                                 indicators give the same values).  If <string>
                                 isn't a numeric expression, it is tested whether
                                 it is an -mdoc macro name, and the default offset
                                 value associated with this macro is used.
                                 Finally, if all tests fail, the width of <string>
                                 (typeset with a fixed-width font) is taken as the
                                 offset.
              -compact           Suppress insertion of vertical space before begin
                                 of display.
    
         .Ed  End display (takes no arguments).
    
       Lists and Columns
         There are several types of lists which may be initiated with the '.Bl'
         begin-list macro.  Items within the list are specified with the '.It'
         item macro, and each list must end with the '.El' macro.  Lists may be
         nested within themselves and within displays.  The use of columns inside
         of lists or lists inside of columns is unproven.
    
         In addition, several list attributes may be specified such as the width
         of a tag, the list offset, and compactness (blank lines between items
         allowed or disallowed).  Most of this document has been formatted with a
         tag style list (-tag).
    
         It has the following syntax forms:
    
               .Bl {-hang | -ohang | -tag | -diag | -inset} [-width <string>]
                    [-offset <string>] [-compact]
               .Bl -column [-offset <string>] <string1> <string2> ...
               .Bl {-item | -enum [-nested] | -bullet | -hyphen | -dash} [-offset
                    <string>] [-compact]
    
         And now a detailed description of the list types.
    
         -bullet  A bullet list.
    
                        .Bl -bullet -offset indent -compact
                        .Bl -dash -offset indent -compact
                        .It
                        Dash one goes here.
                        .It
                        Dash two here.
                        .El
    
                  Produces:
    
                        -   Dash one goes here.
                        -   Dash two here.
    
         -enum    An enumerated list.
    
                        .Bl -enum -offset indent -compact
                        .It
                        Item one goes here.
                        .It
                        And item two here.
                        .El
    
                  The result:
    
                        1.   Item one goes here.
                        2.   And item two here.
    
                  If you want to nest enumerated lists, use the -nested flag
                  (starting with the second-level list):
    
                        .Bl -enum -offset indent -compact
                        .It
                        Item one goes here
                        .Bl -enum -nested -compact
                        .It
                        Item two goes here.
                        .It
                        And item three here.
                        .El
                        .It
                        And item four here.
                        .El
    
                  Result:
    
                        1.   Item one goes here.
                             1.1.   Item two goes here.
                             1.2.   And item three here.
                        2.   And item four here.
    
         -item    A list of type -item without list markers.
    
                        .Bl -item -offset indent
    
                        Item two here.  Item two here.  Item two here.
    
         -tag     A list with tags.  Use -width to specify the tag width.
    
                        SL    sleep time of the process (seconds blocked)
                        PAGEIN
                              number of disk I/O's resulting from references by
                              the process to pages not loaded in core.
                        UID   numerical user-id of process owner
                        PPID  numerical id of parent of process priority (non-pos-
                              itive when in non-interruptible wait)
    
                  The raw text:
    
                        .Bl -tag -width "PPID" -compact -offset indent
                        .It SL
                        sleep time of the process (seconds blocked)
                        .It PAGEIN
                        number of disk
                        .Tn I/O Ns 's
                        resulting from references by the process
                        to pages not loaded in core.
                        .It UID
                        numerical user-id of process owner
                        .It PPID
                        numerical id of parent of process priority
                        (non-positive when in non-interruptible wait)
                        .El
    
         -diag    Diag lists create section four diagnostic lists and are similar
                  to inset lists except callable macros are ignored.  The -width
                  flag is not meaningful in this context.
    
                  Example:
    
                        .Bl -diag
                        .It You can't use Sy here.
                        The message says all.
                        .El
    
                  produces
    
                  You can't use Sy here.  The message says all.
    
         -hang    A list with hanging tags.
    
                        Hanged  labels appear similar to tagged lists when the
                                label is smaller than the label width.
    
                        Longer hanged list labels blend into the paragraph unlike
                                tagged paragraph labels.
    
                        SL
                        sleep time of the process (seconds blocked)
    
                        PAGEIN
                        number of disk I/O's resulting from references by the pro-
                        cess to pages not loaded in core.
    
                        UID
                        numerical user-id of process owner
    
                        PPID
                        numerical id of parent of process priority (non-positive
                        when in non-interruptible wait)
    
                  The raw text:
    
                        .Bl -ohang -offset indent
                        .It Sy SL
                        sleep time of the process (seconds blocked)
                        .It Sy PAGEIN
                        number of disk
                        .Tn I/O Ns 's
                        resulting from references by the process
                        to pages not loaded in core.
                        .It Sy UID
                        numerical user-id of process owner
                        .It Sy PPID
                        numerical id of parent of process priority
                        (non-positive when in non-interruptible wait)
                        .El
    
         -inset   Here is an example of inset labels:
    
                        Tag The tagged list (also called a tagged paragraph) is
                        the most common type of list used in the Berkeley manuals.
                        Use a -width attribute as described below.
    
                        Diag Diag lists create section four diagnostic lists and
                        are similar to inset lists except callable macros are
                        ignored.
    
                        Hang Hanged labels are a matter of taste.
    
                        Ohang Overhanging labels are nice when space is con-
                        strained.
    
                        Inset Inset labels are useful for controlling blocks of
                        paragraphs and are valuable for converting -mdoc manuals
                        to other formats.
    
                  Here is the source text which produced the above example:
                        .It Em Inset
                        Inset labels are useful for controlling blocks of
                        paragraphs and are valuable for converting
                        .Nm -mdoc
                        manuals to other formats.
                        .El
    
         -column  This list type generates multiple columns.  The number of
                  columns and the width of each column is determined by the argu-
                  ments to the -column list, <string1>, <string2>, etc.  If
                  <stringN> starts with a '.' (dot) immediately followed by a
                  valid -mdoc macro name, interpret <stringN> and use the width of
                  the result.  Otherwise, the width of <stringN> (typeset with a
                  fixed-width font) is taken as the Nth column width.
    
                  Each '.It' argument is parsed to make a row, each column within
                  the row is a separate argument separated by a tab or the '.Ta'
                  macro.
    
                  The table:
    
                        String    Nroff    Troff
                        <=        <=       <=
                        >=        >=       >=
    
                  was produced by:
    
                  .Bl -column -offset indent ".Sy String" ".Sy Nroff" ".Sy Troff"
                  .It Sy String Ta Sy Nroff Ta Sy Troff
                  .It Li <= Ta <= Ta \*(<=
                  .It Li >= Ta >= Ta \*(>=
                  .El
    
         Other keywords:
    
         -width <string>   If <string> starts with a '.' (dot) immediately fol-
                           lowed by a valid -mdoc macro name, interpret <string>
                           and use the width of the result.  Almost all lists in
                           this document use this option.
    
                           Example:
    
                                 .Bl -tag -width ".Fl test Ao Ar string Ac"
                                 .It Fl test Ao Ar string Ac
                                 This is a longer sentence to show how the
                                 .Fl width
                                 flag works in combination with a tag list.
                                 .El
    
                           gives:
    
                           -test <string>  This is a longer sentence to show how
                           for indentation.  The most useful scale indicators are
                           'm' and 'n', specifying the so-called Em and En square.
                           This is approximately the width of the letters 'm' and
                           'n' respectively of the current font (for nroff output,
                           both scale indicators give the same values).  If
                           <string> isn't a numeric expression, it is tested
                           whether it is an -mdoc macro name, and the default
                           width value associated with this macro is used.
                           Finally, if all tests fail, the width of <string>
                           (typeset with a fixed-width font) is taken as the
                           width.
    
                           If a width is not specified for the tag list type,
                           every time '.It' is invoked, an attempt is made to
                           determine an appropriate width.  If the first argument
                           to '.It' is a callable macro, the default width for
                           that macro will be used; otherwise, the default width
                           of '.No' is used.
    
         -offset <string>  If <string> is indent, a default indent value (normally
                           set to 6n, similar to the value used in '.Dl' or '.Bd')
                           is used.  If <string> is a valid numeric expression
                           instead (with a scale indicator other than 'u'), use
                           that value for indentation.  The most useful scale
                           indicators are 'm' and 'n', specifying the so-called Em
                           and En square.  This is approximately the width of the
                           letters 'm' and 'n' respectively of the current font
                           (for nroff output, both scale indicators give the same
                           values).  If <string> isn't a numeric expression, it is
                           tested whether it is an -mdoc macro name, and the
                           default offset value associated with this macro is
                           used.  Finally, if all tests fail, the width of
                           <string> (typeset with a fixed-width font) is taken as
                           the offset.
    
         -compact          Suppress insertion of vertical space before the list
                           and between list items.
    
    
    

    MISCELLANEOUS MACROS

         Here a list of the remaining macros which do not fit well into one of the
         above sections.  We couldn't find real examples for the following macros:
         '.Me' and '.Ot'.  They are documented here for completeness - if you know
         how to use them properly please send a mail to bug-groff@gnu.org (includ-
         ing an example).
    
         .Bt  prints
    
                    is currently in beta test.
    
              It is neither callable nor parsed and takes no arguments.
    
         .Fr
    
         .Lk  To be written.
    
         .Me  Exact usage unknown.  The documentation in the -mdoc source file
              describes it as a macro for "menu entries".
    
              Its default width is 6n.
    
         .Mt  To be written.
    
         .Ot  Exact usage unknown.  The documentation in the -mdoc source file
              describes it as "old function type (fortran)".
    
         .Sm  Activate (toggle) space mode.
    
                    Usage: .Sm [on | off] ...
    
              If space mode is off, no spaces between macro arguments are
              inserted.  If called without a parameter (or if the next parameter
              is neither 'on' nor 'off', '.Sm' toggles space mode.
    
         .Ud  prints
    
                    currently under development.
    
              It is neither callable nor parsed and takes no arguments.
    
    
    

    PREDEFINED STRINGS

         The following strings are predefined:
    
               String    Nroff       Troff     Meaning
               <=        <=          <=         less equal
               >=        >=          >=         greater equal
               Rq        ''          "         right double quote
               Lq        ''          "         left double quote
               ua        ^           ?         upwards arrow
               aa        ?           ?         acute accent
               ga        `           `         grave accent
               q         "           "         straight double quote
               Pi        pi          ?         greek pi
               Ne        !=          ?         not equal
               Le        <=          <=         less equal
               Ge        >=          >=         greater equal
               Lt        <           <         less than
               Gt        >           >         greater than
               Pm        +-          ?         plus minus
               If        infinity    ?         infinity
               Am        &           &         ampersand
               Na        NaN         NaN       not a number
               Ba        |           |         vertical bar
    
         The names of the columns Nroff and Troff are a bit misleading; Nroff
         to this macro package, making it both more robust and verbose.
    
         The only remaining debugging macro is '.Rd' which yields a register dump
         of all global registers and strings.  A normal user will never need it.
    
    
    

    FORMATTING WITH GROFF, TROFF, AND NROFF

         By default, the package inhibits page breaks, headers, and footers if
         displayed with a TTY device like 'latin1' or 'unicode' to make the manual
         more efficient for viewing on-line.  This behaviour can be changed (e.g.
         to create a hardcopy of the TTY output) by setting the register 'cR' to
         zero while calling groff:
    
               groff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt
    
         For double-sided printing, set register 'D' to 1:
    
               groff -Tps -rD1 -mdoc foo.man > foo.ps
    
         To change the document font size to 11pt or 12pt, set register 'S'
         accordingly:
    
               groff -Tdvi -rS11 -mdoc foo.man > foo.dvi
    
         Register 'S' is ignored for TTY devices.
    
         The line and title length can be changed by setting the registers 'LL'
         and 'LT', respectively:
    
               groff -Tutf8 -rLL=100n -rLT=100n -mdoc foo.man | less
    
         If not set, both registers default to 78n for TTY devices and 6.5i other-
         wise.
    
    
    

    FILES

         doc.tmac          The main manual macro package.
         mdoc.tmac         A wrapper file to call doc.tmac.
         mdoc/doc-common   Common strings, definitions, stuff related typographic
                           output.
         mdoc/doc-nroff    Definitions used for a TTY output device.
         mdoc/doc-ditroff  Definitions used for all other devices.
         mdoc.local        Local additions and customizations.
         andoc.tmac        This file checks whether the -mdoc or the -man package
                           should be used.
    
    
    

    SEE ALSO

         groff(1), man(1), troff(1), groff_man(7)
    
    
    

    BUGS

         Section 3f has not been added to the header routines.
    
         '.Nm' font should be changed in NAME section.
    
    
  • MORE RESOURCE


  • Linux

    The Distributions





    Linux

    The Software





    Linux

    The News



  • MARKETING






  • Toll Free

webmaster@linuxguruz.com
Copyright © 1999 - 2016 by LinuxGuruz