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

  man pages->OpenBSD man pages -> mdoc (7)              



NAME    [Toc]    [Back]

     mdoc - quick reference guide for the -mdoc macro package

SYNOPSIS    [Toc]    [Back]

     nroff -TNAME -mandoc file

DESCRIPTION    [Toc]    [Back]

     The -mdoc package is a set of content-based and domain-based
macros used
     to  format  the  BSD  man  pages.  The macro names and their
meanings are
     listed below for quick reference; for a detailed explanation
on using the
     package, see the tutorial sampler mdoc.samples(7).

     The  macros are described in two groups.  The first includes
the structural
 and physical page layout macros.  The second  contains
the manual
     and general text domain macros which differentiate the -mdoc
package from
     other troff(1) formatting packages.


   Title Macros
     To create a valid manual page, these three macros,  in  this
order, are required:

     .Dd   Month day, year                       Document date.
     .Dt    DOCUMENT_TITLE [section] [volume]     Title, in upper
     .Os   OPERATING_SYSTEM [version/release]    Operating system

   Page Layout Macros    [Toc]    [Back]
     Section headers, paragraph breaks, lists and displays.
     .Sh    Section Headers.  Valid headers, in the order of presentation:
           NAME           Name section.  Should include the `.Nm'
or `.Fn' and
                          the `.Nd' macros.
           SYNOPSIS        Usage.  All `.Nm' macros must be given
an argument.
           DESCRIPTION    General description, including any  options,
                          operands, or other parameters.
           RETURN  VALUES  Sections two, three, and nine function
           ENVIRONMENT    Describe environment variables.
           FILES          Files associated with the subject, with
short descriptions.

           EXAMPLES       Examples and suggestions.
           DIAGNOSTICS     Sections one, four, six, and eight diagnostics.
           ERRORS         Sections two, three, and nine error and
signal handling.

           SEE ALSO       Cross references and citations.
           STANDARDS      Conformance to standards if applicable.
           HISTORY        A brief history of the subject, including where support
 first appeared.
           AUTHORS         Credit  to  the  person or persons who
wrote the code
                          and/or documentation.
           CAVEATS        Explanations of common  misuses,  i.e.,
security considerations
  for  certain library functions.
           BUGS           Gotchas and caveats.
           other          Customized headers may be added at  the
author's discretion.

     .Ss   Subsection Headers.
     .Pp   Paragraph Break.  Vertical space (one line).
     .D1    (D-one) Display-one Indent and display one text line.
     .Dl   (D-ell) Display-one literal.  Indent and  display  one
line of literal
     .Bd   Begin-display block.  Display options:
           -ragged          Unjustified (ragged edges).
           -unfilled        Unfilled, unjustified.
           -filled           Filled, and if troff(1), also justified.
           -literal         Literal text or code.
           -file NAME       Read in named file and display.
           -offset string   Offset  display.   Acceptable  string
                            left         Align block on left (default).
                            center      Approximate  center  margin.
                            indent      Six constant width spaces
(a tab).
                            indent-two  Two tabs.
                            right       Left aligns block 2 inches from right.
                            xxn         Where xx is a number from
4n to 99n.
                            Aa          Where Aa  is  a  callable
macro name.
                            string       The  width  of string is
     .Ed   End-display (matches .Bd).
     .Bl   Begin-list.  Create lists or columns.  Options:
                 -bullet     Bullet Item List
                 -dash       Dash Item List
                 -hyphen     (as per -dash)
                 -item       Unlabeled List
                 -enum       Enumerated List
                 -tag        Tag Labeled List
                 -diag       Diagnostic List
                 -hang       Hanging Labeled List
                 -ohang      Overhanging Labeled List
                 -inset      Inset or Run-on Labeled List
                 -column     Multiple Columns
                 -offset    (All lists.) See `.Bd'  begin-display
                 -width      (-tag  and  -hang lists only.)  This
parameter is
                            effectively required for -tag  lists.
                 -compact   (All lists.)  Suppresses blank lines.
     .El   End-list.
     .It   List item.


     The manual and general text domain  macros  are  special  in
that most of
     them are parsed for callable macros for example:

           .Op Fl s Ar file   Produces [-s file]

     In this example, the option enclosure macro `.Op' is parsed,
and calls
     the callable content macro `Fl' which operates on the  argument `s' and
     then calls the callable content macro `Ar' which operates on
the argument
     `file'.  Some macros may be callable but are not parsed,  or
vice versa.
     These  macros  are  indicated  in  the  parsed  and callable
columns below.

     Unless stated, manual domain macros share a common syntax:

           .Va argument [ . , ; : ? ! ( ) [ ] argument ... ]

     Note: Opening and closing punctuation  characters  are  only
recognized as
     such  if  they are presented one at a time.  The string `),'
is not recognized
 as punctuation and  will  be  output  with  a  leading
whitespace and in
     whatever  font the calling macro uses.  The argument list `]
) ,' is recognized
 as three sequential closing  punctuation  characters
and a leading
     white  space  is  not  output between the characters and the
previous argument
 (if any).  The special meaning of a punctuation character may be escaped
 with the string `'.  For example the following string,

           .Ar file1 , file2 , file3 ) .   Produces file1, file2,

   Manual Domain Macros    [Toc]    [Back]
     NAME    Parsed    Callable    DESCRIPTION
     Ad       Yes        Yes          Address. (This macro may be
     An      Yes       No          Author name.
     Ar      Yes       Yes         Command line argument.
     Cd      No        No          Configuration declaration.
     Cm      Yes       Yes         Command line argument  modifier.
     Dv        Yes        Yes          Defined  variable  (source
     Er      Yes       Yes         Error number (source code).
     Ev      Yes       Yes         Environment variable.
     Ex      No        No          Exit values.
     Fa      Yes       Yes         Function argument.
     Fd      No        No          Function declaration.
     Fl      Yes       Yes         Flags.
     Fn      Yes       Yes         Function call  (also  .Fo  and
     Ft      Yes       Yes         Function type.
     Ic      Yes       Yes         Interactive command.
     In      No        No          Include header file.
     Li      Yes       Yes         Literal text.
     Nd      No        No          Command description.
     Nm      Yes       Yes         Command name.
     Op      Yes       Yes         Option (also .Oo and .Oc).
     Ot       Yes       Yes         Old style function type (Fortran only).
     Pa      Yes       Yes         Pathname or file name.
     Rv      No        No          Return values.
     St      Yes       Yes         Standards (see below).
     Va      Yes       Yes         Variable name.
     Vt      Yes       Yes         Variable type.
     Xr      Yes       Yes         Manual Page Cross Reference.

     The known standards for the St macro are:

         -p1003.1-88,  -p1003.1-90,  -p1003.1-96,  -p1003.1-2001,
         -p1003.1,    -p1003.1b,    -p1003.1b-93,   -p1003.1c-95,
         -p1003.2-92, -p1003.2-95, -p1003.2, -p1387.2,  -isoC-90,
         -isoC-tcor1,  -isoC-tcor2,  isoC-99,  -ansiC, -ansiC-89,
         -ieee754, -iso8802-3, -xpg3,  -xpg4,  -xpg4.2,  -xpg4.3,
-xbd5, -xcu5,
         -xsh5,  -xns5, -xns5.2d2.0, -xcurses4.2, -susv2, -susv3,
and -svid4.

   General Text Domain Macros    [Toc]    [Back]
     NAME    Parsed    Callable    DESCRIPTION
     %A      Yes       No          Reference author.
     %B      Yes       Yes         Reference book title.
     %D      No        No          Reference date.
     %I      Yes       Yes         Issuer/Publisher name.
     %J      Yes       Yes         Reference journal title.
     %N      No        No          Reference issue number.
     %O      No        No           Reference  optional  information.
     %P      No        No          Reference page number(s).
     %R      No        No          Reference report Name.
     %T      Yes       Yes         Reference article title.
     %V      No        No          Reference volume.
     Ac      Yes       Yes         Angle close quote.
     Ao      Yes       Yes         Angle open quote.
     Aq      Yes       Yes         Angle quote.
     At      No        No          AT&T UNIX.
     Bc      Yes       Yes         Bracket close quote.
     Bf      No        No          Begin font mode.
     Bo      Yes       Yes         Bracket open quote.
     Bq      Yes       Yes         Bracket quote.
     Bsx     Yes       No          BSDI BSD/OS.
     Bx      Yes       No          BSD.
     Db      No        No          Debug (default is "off").
     Dc      Yes       Yes         Double close quote.
     Do      Yes       Yes         Double open quote.
     Dq      Yes       Yes         Double quote.
     Ec      Yes       Yes         Enclose string close quote.
     Ef      No        No          End font mode.
     Em       Yes        Yes          Emphasis  (traditional  English).
     Eo      Yes       Yes         Enclose string open quote.
     Fx      No        No          FreeBSD.
     Ms      Yes       No          Mathematical symbol.
     No      Yes       Yes         Normal text (no-op).
     Ns      Yes       Yes         No space.
     Nx      No        No          NetBSD.
     Ox      No        No          OpenBSD.
     Pc      Yes       Yes         Parenthesis close quote.
     Pf      Yes       No          Prefix string.
     Po      Yes       Yes         Parenthesis open quote.
     Pq      Yes       Yes         Parentheses quote.
     Qc      Yes       Yes         Straight double close quote.
     Ql      Yes       Yes         Quoted literal.
     Qo      Yes       Yes         Straight double open quote.
     Qq      Yes       Yes         Straight double quote.
     Re      No        No          Reference end.
     Rs      No        No          Reference start.
     Sc      Yes       Yes         Single close quote.
     So      Yes       Yes         Single open quote.
     Sq      Yes       Yes         Single quote.
     Sm      No        No          Space mode (default is  "on").
     Sx      Yes       Yes         Section Cross Reference.
     Sy       Yes        Yes          Symbolic  (traditional  English).
     Tn      Yes       Yes          Trade  or  type  name  (small
     Ux      Yes       No          UNIX.
     Xc      Yes       Yes         Extend argument list close.
     Xo      Yes       Yes         Extend argument list open.

     Macro names ending in `q' quote remaining items on the argument list.
     Macro names ending in `o' begin a quote which may span  more
than one line
     of  input  and are close quoted with the matching macro name
ending in `c'.
     Enclosure macros may be nested and are limited to eight  arguments.

     Note:  the  extended argument list macros (`.Xo', `.Xc') and
the function
     enclosure macros (`.Fo', `.Fc') are irregular.  The extended
list macros
     are used when the number of macro arguments would exceed the
     limitation of nine arguments.

FILES    [Toc]    [Back]

     tmac.doc                       manual macro package
     tmac.doc-common                common structural macros  and
     tmac.doc-ditroff               site dependent troff(1) style
     tmac.doc-nroff                 site dependent nroff(1) style
     tmac.doc-syms                  special defines
     /usr/share/misc/mdoc.template   template  for  writing a man

SEE ALSO    [Toc]    [Back]

     groff(1), man(1), nroff(1), troff(1), mdoc.samples(7)

OpenBSD     3.6                        December     30,      1993
[ Back ]
 Similar pages
Name OS Title
mdoc FreeBSD reference for groff's mdoc implementation
groff_mdoc FreeBSD reference for groff's mdoc implementation
mdoc.samples FreeBSD reference for groff's mdoc implementation
man.page Tru64 The man macro packages for reference pages
man Tru64 The man macro packages for reference pages
sml Tru64 rsml and sml macro packages that support RSMLcoded reference pages
rsml Tru64 rsml and sml macro packages that support RSMLcoded reference pages
mm HP-UX the MM macro package for formatting documents
groff_trace FreeBSD groff macro package trace.tmac
mandoc.samples OpenBSD with -mdoc
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service