mdoc man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]

MDOC(7)			   OpenBSD Reference Manual		       MDOC(7)

NAME
     mdoc - mdoc language reference

DESCRIPTION
     The mdoc language is used to format BSD UNIX manuals.  This reference
     document describes its syntax, structure, and usage.  The reference
     implementation is mandoc(1); the COMPATIBILITY section describes
     compatibility with other troff -mdoc implementations.

     An mdoc document follows simple rules: lines beginning with the control
     character `.' are parsed for macros.  Other lines are interpreted within
     the scope of prior macros:

	   .Sh Macro lines change control state.
	   Other lines are interpreted within the current state.

LANGUAGE SYNTAX
     mdoc documents may contain only graphable 7-bit ASCII characters, the
     space character, and, in certain circumstances, the tab character.

     If the first character of a line is a space, that line is printed with a
     leading newline.

   Comments
     Text following a `\"', whether in a macro or free-form text line, is
     ignored to the end of line.  A macro line with only a control character
     and comment escape, `.\"', is also ignored.  Macro lines with only a
     control character and optional whitespace are stripped from input.

   Reserved Characters
     Within a macro line, the following characters are reserved:

	   .	   (period)
	   ,	   (comma)
	   :	   (colon)
	   ;	   (semicolon)
	   (	   (left-parenthesis)
	   )	   (right-parenthesis)
	   [	   (left-bracket)
	   ]	   (right-bracket)
	   ?	   (question)
	   !	   (exclamation)
	   |	   (vertical bar)

     Use of reserved characters is described in MACRO SYNTAX.  For general use
     in macro lines, these characters can either be escaped with a non-
     breaking space (`\&') or, if applicable, an appropriate escape sequence
     can be used.

   Special Characters
     Special characters may occur in both macro and free-form lines.
     Sequences begin with the escape character `\' followed by either an open-
     parenthesis `(' for two-character sequences; an open-bracket `[' for n-
     character sequences (terminated at a close-bracket `]'); or a single one
     character sequence.  See mandoc_char(7) for a complete list.  Examples
     include `\(em' (em-dash) and `\e' (back-slash).

   Text Decoration
     Terms may be text-decorated using the `\f' escape followed by an
     indicator: B (bold), I (italic), R (Roman), or P (revert to previous
     mode):

	   \fBbold\fR \fIitalic\fP

     A numerical representation 3, 2, or 1 (bold, italic, and Roman,
     respectively) may be used instead.	 A text decoration is valid within the
     current font scope only: if a macro opens a font scope alongside its own
     scope, such as Bf Sy, in-scope invocations of `\f' are only valid within
     the font scope of the macro.  If `\f' is specified outside of any font
     scope, such as in unenclosed, free-form text, it will affect the
     remainder of the document.

     Note this form is not recommended for mdoc, which encourages semantic
     annotation.

   Predefined Strings
     Historically, troff also defined a set of package-specific ``predefined
     strings'', which, like Special Characters, mark special output characters
     and strings by way of input codes.	 Predefined strings are escaped with
     the slash-asterisk, `\*': single-character `\*X', two-character `\*(XX',
     and N-character `\*[N]'.  See mandoc_char(7) for a complete list.
     Examples include `\*(Am' (ampersand) and `\*(Ba' (vertical bar).

   Whitespace
     Whitespace consists of the space character.  In free-form lines,
     whitespace is preserved within a line; unescaped trailing spaces are
     stripped from input (unless in a literal context).	 Blank free-form
     lines, which may include whitespace, are only permitted within literal
     contexts.

     In macro lines, whitespace delimits arguments and is discarded.  If
     arguments are quoted, whitespace within the quotes is retained.

   Quotation
     Macro arguments may be quoted with double-quotes to group space-delimited
     terms or to retain blocks of whitespace.  A quoted argument begins with a
     double-quote preceded by whitespace.  The next double-quote not pairwise
     adjacent to another double-quote terminates the literal, regardless of
     surrounding whitespace.

     Note that any quoted text, even if it would cause a macro invocation when
     unquoted, is considered literal text.  Thus, the following produces `[Fl
     a]':

	   .Op "Fl a"

     In free-form mode, quotes are regarded as opaque text.

   Dates
     There are several macros in mdoc that require a date argument.  The
     canonical form for dates is the American format:

	   Month Day, Year

     The Day value is an optionally zero-padded numeral.  The Month value is
     the full month name.  The Year value is the full four-digit year.

     Reduced form dates are broken-down canonical form dates:

	   Month, Year
	   Year

     Some examples of valid dates follow:

	   May, 2009 (reduced form)
	   2009 (reduced form)
	   May 20, 2009 (canonical form)

   Scaling Widths
     Many macros support scaled widths for their arguments, such as
     stipulating a two-inch list indentation with the following:

	   .Bl -tag -width 2i

     The syntax for scaled widths is `[+-]?[0-9]*.[0-9]*[:unit:]', where a
     decimal must be preceded or proceeded by at least one digit.  Negative
     numbers, while accepted, are truncated to zero.  The following scaling
     units are accepted:

	   c	   centimetre
	   i	   inch
	   P	   pica (~1/6 inch)
	   p	   point (~1/72 inch)
	   f	   synonym for `u'
	   v	   default vertical span
	   m	   width of rendered `m' (em) character
	   n	   width of rendered `n' (en) character
	   u	   default horizontal span
	   M	   mini-em (~1/100 em)

     Using anything other than `m', `n', `u', or `v' is necessarily non-
     portable across output media.  See COMPATIBILITY.

   Sentence Spacing
     When composing a manual, make sure that sentences end at the end of a
     line.  By doing so, front-ends will be able to apply the proper amount of
     spacing after the end of sentence (unescaped) period, exclamation mark,
     or question mark followed by zero or more non-sentence closing delimiters
     (`)', `]', `'', `"').

     The proper spacing is also intelligently preserved if a sentence ends at
     the boundary of a macro line.  For example:

	   Xr mandoc 1 .
	   Fl T Ns Cm ascii .

MANUAL STRUCTURE
     A well-formed mdoc document consists of a document prologue followed by
     one or more sections.

     The prologue, which consists of the Dd, Dt, and Os macros in that order,
     is required for every document.

     The first section (sections are denoted by Sh) must be the NAME section,
     consisting of at least one Nm followed by Nd.

     Following that, convention dictates specifying at least the SYNOPSIS and
     DESCRIPTION sections, although this varies between manual sections.

     The following is a well-formed skeleton mdoc file:

	   .Dd $Mdocdate$
	   .Dt mdoc 7
	   .Os
	   .Sh NAME
	   .Nm foo
	   .Nd a description goes here
	   .\" .Sh LIBRARY
	   .\" For sections 2, 3, & 9 only.
	   .\" Not used in OpenBSD.
	   .Sh SYNOPSIS
	   .Nm foo
	   .Op Fl options
	   .Ar
	   .Sh DESCRIPTION
	   The
	   .Nm
	   utility processes files ...
	   .\" .Sh IMPLEMENTATION NOTES
	   .\" Not used in OpenBSD.
	   .\" .Sh RETURN VALUES
	   .\" For sections 2, 3, & 9 only.
	   .\" .Sh ENVIRONMENT
	   .\" For sections 1, 6, 7, & 8 only.
	   .\" .Sh FILES
	   .\" .Sh EXIT STATUS
	   .\" For sections 1, 6, & 8 only.
	   .\" .Sh EXAMPLES
	   .\" .Sh DIAGNOSTICS
	   .\" For sections 1, 4, 6, 7, & 8 only.
	   .\" .Sh ERRORS
	   .\" For sections 2, 3, & 9 only.
	   .\" .Sh SEE ALSO
	   .\" .Xr foobar 1
	   .\" .Sh STANDARDS
	   .\" .Sh HISTORY
	   .\" .Sh AUTHORS
	   .\" .Sh CAVEATS
	   .\" .Sh BUGS
	   .\" .Sh SECURITY CONSIDERATIONS
	   .\" Not used in OpenBSD.

     The sections in an mdoc document are conventionally ordered as they
     appear above.  Sections should be composed as follows:

       NAME
       The name(s) and a one line description of the documented material.  The
       syntax for this as follows:

	     .Nm name0 ,
	     .Nm name1 ,
	     .Nm name2
	     .Nd a one line description

       The Nm macro(s) must precede the Nd macro.

       See Nm and Nd.

       LIBRARY
       The name of the library containing the documented material, which is
       assumed to be a function in a section 2, 3, or 9 manual.	 The syntax
       for this is as follows:

	     .Lb libarm

       See Lb.

       SYNOPSIS
       Documents the utility invocation syntax, function call syntax, or
       device configuration.

       For the first, utilities (sections 1, 6, and 8), this is generally
       structured as follows:

	     .Nm foo
	     .Op Fl v
	     .Op Fl o Ar file
	     .Op Ar
	     .Nm bar
	     .Op Fl v
	     .Op Fl o Ar file
	     .Op Ar

       For the second, function calls (sections 2, 3, 9):

	     .In header.h
	     .Vt extern const char *global;
	     .Ft "char *"
	     .Fn foo "const char *src"
	     .Ft "char *"
	     .Fn bar "const char *src"

       And for the third, configurations (section 4):

	     .Cd "it* at isa? port 0x2e"
	     .Cd "it* at isa? port 0x4e"

       Manuals not in these sections generally don't need a SYNOPSIS.

       Some macros are displayed differently in the SYNOPSIS section,
       particularly Nm, Cd, Fd, Fn, Fo, In, Vt, and Ft.	 All of these macros
       are output on their own line.  If two such dissimilar macros are
       pairwise invoked (except for Ft before Fo or Fn), they are separated by
       a vertical space, unless in the case of Fo, Fn, and Ft, which are
       always separated by vertical space.

       When text and macros following an Nm macro starting an input line span
       multiple output lines, all output lines but the first will be indented
       to align with the text immediately following the Nm macro, up to the
       next Nm, Sh, or Ss macro or the end of an enclosing block, whichever
       comes first.

       DESCRIPTION
       This expands upon the brief, one line description in NAME.  It usually
       contains a breakdown of the options (if documenting a command), such
       as:

	     The arguments are as follows:
	     .Bl -tag -width Ds
	     .It Fl v
	     Print verbose information.
	     .El

       Manuals not documenting a command won't include the above fragment.

       IMPLEMENTATION NOTES
       Implementation-specific notes should be kept here.  This is useful when
       implementing standard functions that may have side effects or notable
       algorithmic implications.

       RETURN VALUES
       This section documents the return values of functions in sections 2, 3,
       and 9.

       See Rv.

       ENVIRONMENT
       Lists the environment variables used by the utility, and explains the
       syntax and semantics of their values.  The environ(7) manual provides
       examples of typical content and formatting.

       See Ev.

       FILES
       Documents files used.  It's helpful to document both the file name and
       a short description of how the file is used (created, modified, etc.).

       See Pa.

       EXIT STATUS
       This section documents the command exit status for section 1, 6, and 8
       utilities.  Historically, this information was described in
       DIAGNOSTICS, a practise that is now discouraged.

       See Ex.

       EXAMPLES
       Example usages.	This often contains snippets of well-formed, well-
       tested invocations.  Make sure that examples work properly!

       DIAGNOSTICS
       Documents error conditions.  This is most useful in section 4 manuals.
       Historically, this section was used in place of EXIT STATUS for manuals
       in sections 1, 6, and 8; however, this practise is discouraged.

       See Bl -diag.

       ERRORS
       Documents error handling in sections 2, 3, and 9.

       See Er.

       SEE ALSO
       References other manuals with related topics.  This section should
       exist for most manuals.	Cross-references should conventionally be
       ordered first by section, then alphabetically.

       See Xr.

       STANDARDS
       References any standards implemented or used.  If not adhering to any
       standards, the HISTORY section should be used instead.

       See St.

       HISTORY
       A brief history of the subject, including where support first appeared.

       AUTHORS
       Credits to the person or persons who wrote the code and/or
       documentation.  Authors should generally be noted by both name and
       email address.

       See An.

       CAVEATS
       Common misuses and misunderstandings should be explained in this
       section.

       BUGS
       Known bugs, limitations, and work-arounds should be described in this
       section.

       SECURITY CONSIDERATIONS
       Documents any security precautions that operators should consider.

MACRO SYNTAX
     Macros are one to three three characters in length and begin with a
     control character, `.', at the beginning of the line.  An arbitrary
     amount of whitespace may sit between the control character and the macro
     name.  Thus, the following are equivalent:

	   .Pp
	   .   Pp

     The syntax of a macro depends on its classification.  In this section,
     `-arg' refers to macro arguments, which may be followed by zero or more
     `parm' parameters; `Yo' opens the scope of a macro; and if specified,
     `Yc' closes it out.

     The Callable column indicates that the macro may also be called by
     passing its name as an argument to another macro.	If a macro is not
     callable but its name appears as an argument to another macro, it is
     interpreted as opaque text.  For example, `.Fl Sh' produces `-Sh'.

     The Parsed column indicates whether the macro may call other macros by
     receiving their names as arguments.  If a macro is not parsed but the
     name of another macro appears as an argument, it is interpreted as opaque
     text.

     The Scope column, if applicable, describes closure rules.

   Block full-explicit
     Multi-line scope closed by an explicit closing macro.  All macros
     contains bodies; only Bf contains a head.

	   .Yo [-arg [parm...]] [head...]
	   [body...]
	   .Yc

	   Macro     Callable	  Parsed     Scope
	   Bd	     No		  No	     closed by Ed
	   Bf	     No		  No	     closed by Ef
	   Bk	     No		  No	     closed by Ek
	   Bl	     No		  No	     closed by El
	   Ed	     No		  No	     opened by Bd
	   Ef	     No		  No	     opened by Bf
	   Ek	     No		  No	     opened by Bk
	   El	     No		  No	     opened by Bl

   Block full-implicit
     Multi-line scope closed by end-of-file or implicitly by another macro.
     All macros have bodies; some (It -bullet, -hyphen, -dash, -enum, -item)
     don't have heads; only one (It in Bl -column) has multiple heads.

	   .Yo [-arg [parm...]] [head... [Ta head...]]
	   [body...]

	   Macro     Callable	  Parsed     Scope
	   It	     No		  Yes	     closed by It, El
	   Nd	     No		  No	     closed by Sh
	   Nm	     No		  Yes	     closed by Nm, Sh, Ss
	   Sh	     No		  No	     closed by Sh
	   Ss	     No		  No	     closed by Sh, Ss

     Note that the Nm macro is a Block full-implicit macro only when invoked
     as the first macro in a SYNOPSIS section line, else it is In-line.

   Block partial-explicit
     Like block full-explicit, but also with single-line scope.	 Each has at
     least a body and, in limited circumstances, a head (Fo, Eo) and/or tail
     (Ec).

	   .Yo [-arg [parm...]] [head...]
	   [body...]
	   .Yc [tail...]

	   .Yo [-arg [parm...]] [head...] [body...] Yc [tail...]

	   Macro     Callable	  Parsed     Scope
	   Ac	     Yes	  Yes	     opened by Ao
	   Ao	     Yes	  Yes	     closed by Ac
	   Bc	     Yes	  Yes	     closed by Bo
	   Bo	     Yes	  Yes	     opened by Bc
	   Brc	     Yes	  Yes	     opened by Bro
	   Bro	     Yes	  Yes	     closed by Brc
	   Dc	     Yes	  Yes	     opened by Do
	   Do	     Yes	  Yes	     closed by Dc
	   Ec	     Yes	  Yes	     opened by Eo
	   Eo	     Yes	  Yes	     closed by Ec
	   Fc	     Yes	  Yes	     opened by Fo
	   Fo	     No		  No	     closed by Fc
	   Oc	     Yes	  Yes	     closed by Oo
	   Oo	     Yes	  Yes	     opened by Oc
	   Pc	     Yes	  Yes	     closed by Po
	   Po	     Yes	  Yes	     opened by Pc
	   Qc	     Yes	  Yes	     opened by Oo
	   Qo	     Yes	  Yes	     closed by Oc
	   Re	     No		  No	     opened by Rs
	   Rs	     No		  No	     closed by Re
	   Sc	     Yes	  Yes	     opened by So
	   So	     Yes	  Yes	     closed by Sc
	   Xc	     Yes	  Yes	     opened by Xo
	   Xo	     Yes	  Yes	     closed by Xc

   Block partial-implicit
     Like block full-implicit, but with single-line scope closed by Reserved
     Characters or end of line.

	   .Yo [-arg [val...]] [body...] [res...]

	   Macro     Callable	  Parsed
	   Aq	     Yes	  Yes
	   Bq	     Yes	  Yes
	   Brq	     Yes	  Yes
	   D1	     No		  Yes
	   Dl	     No		  Yes
	   Dq	     Yes	  Yes
	   Op	     Yes	  Yes
	   Pq	     Yes	  Yes
	   Ql	     Yes	  Yes
	   Qq	     Yes	  Yes
	   Sq	     Yes	  Yes
	   Vt	     Yes	  Yes

     Note that the Vt macro is a Block partial-implicit only when invoked as
     the first macro in a SYNOPSIS section line, else it is In-line.

   In-line
     Closed by Reserved Characters, end of line, fixed argument lengths,
     and/or subsequent macros.	In-line macros have only text children.	 If a
     number (or inequality) of arguments is (n), then the macro accepts an
     arbitrary number of arguments.

	   .Yo [-arg [val...]] [args...] [res...]

	   .Yo [-arg [val...]] [args...] Yc...

	   .Yo [-arg [val...]] arg0 arg1 argN

	   Macro     Callable	  Parsed     Arguments
	   %A	     No		  No	     >0
	   %B	     No		  No	     >0
	   %C	     No		  No	     >0
	   %D	     No		  No	     >0
	   %I	     No		  No	     >0
	   %J	     No		  No	     >0
	   %N	     No		  No	     >0
	   %O	     No		  No	     >0
	   %P	     No		  No	     >0
	   %Q	     No		  No	     >0
	   %R	     No		  No	     >0
	   %T	     No		  No	     >0
	   %U	     No		  No	     >0
	   %V	     No		  No	     >0
	   Ad	     Yes	  Yes	     >0
	   An	     Yes	  Yes	     >0
	   Ap	     Yes	  Yes	     0
	   Ar	     Yes	  Yes	     n
	   At	     Yes	  Yes	     1
	   Bsx	     Yes	  Yes	     n
	   Bt	     No		  No	     0
	   Bx	     Yes	  Yes	     n
	   Cd	     Yes	  Yes	     >0
	   Cm	     Yes	  Yes	     >0
	   Db	     No		  No	     1
	   Dd	     No		  No	     n
	   Dt	     No		  No	     n
	   Dv	     Yes	  Yes	     >0
	   Dx	     Yes	  Yes	     n
	   Em	     Yes	  Yes	     >0
	   En	     No		  No	     0
	   Er	     Yes	  Yes	     >0
	   Es	     No		  No	     0
	   Ev	     Yes	  Yes	     >0
	   Ex	     No		  No	     n
	   Fa	     Yes	  Yes	     >0
	   Fd	     No		  No	     >0
	   Fl	     Yes	  Yes	     n
	   Fn	     Yes	  Yes	     >0
	   Fr	     No		  No	     n
	   Ft	     Yes	  Yes	     >0
	   Fx	     Yes	  Yes	     n
	   Hf	     No		  No	     n
	   Ic	     Yes	  Yes	     >0
	   In	     No		  No	     n
	   Lb	     No		  No	     1
	   Li	     Yes	  Yes	     >0
	   Lk	     Yes	  Yes	     >0
	   Lp	     No		  No	     0
	   Ms	     Yes	  Yes	     >0
	   Mt	     Yes	  Yes	     >0
	   Nm	     Yes	  Yes	     n
	   No	     Yes	  Yes	     0
	   Ns	     Yes	  Yes	     0
	   Nx	     Yes	  Yes	     n
	   Os	     No		  No	     n
	   Ot	     No		  No	     n
	   Ox	     Yes	  Yes	     n
	   Pa	     Yes	  Yes	     n
	   Pf	     Yes	  Yes	     1
	   Pp	     No		  No	     0
	   Rv	     No		  No	     n
	   Sm	     No		  No	     1
	   St	     No		  Yes	     1
	   Sx	     Yes	  Yes	     >0
	   Sy	     Yes	  Yes	     >0
	   Tn	     Yes	  Yes	     >0
	   Ud	     No		  No	     0
	   Ux	     Yes	  Yes	     n
	   Va	     Yes	  Yes	     n
	   Vt	     Yes	  Yes	     >0
	   Xr	     Yes	  Yes	     >0
	   br	     No		  No	     0
	   sp	     No		  No	     1

REFERENCE
     This section is a canonical reference of all macros, arranged
     alphabetically.  For the scoping of individual macros, see MACRO SYNTAX.

   %A
     Author name of an Rs block.  Multiple authors should each be accorded
     their own %A line.	 Author names should be ordered with full or
     abbreviated forename(s) first, then full surname.

   %B
     Book title of an Rs block.	 This macro may also be used in a non-
     bibliographic context when referring to book titles.

   %C
     Publication city or location of an Rs block.

   %D
     Publication date of an Rs block.  This should follow the reduced or
     canonical form syntax described in Dates.

   %I
     Publisher or issuer name of an Rs block.

   %J
     Journal name of an Rs block.

   %N
     Issue number (usually for journals) of an Rs block.

   %O
     Optional information of an Rs block.

   %P
     Book or journal page number of an Rs block.

   %Q
     Institutional author (school, government, etc.) of an Rs block.  Multiple
     institutional authors should each be accorded their own %Q line.

   %R
     Technical report name of an Rs block.

   %T
     Article title of an Rs block.  This macro may also be used in a non-
     bibliographical context when referring to article titles.

   %U
     URI of reference document.

   %V
     Volume number of an Rs block.

   Ac
     Close an Ao block.	 Does not have any tail arguments.

   Ad
     Memory address.  Do not use this for postal addresses.

     Examples:
	   .Ad [0,$]
	   .Ad 0x00000000

   An
     Author name.  Requires either the name of an author or one of the
     following arguments:

	   -split     Start a new output line before each subsequent
		      invocation of An.
	   -nosplit   The opposite of -split.

     The default is -nosplit.  The effect of selecting either of the -split
     modes ends at the beginning of the AUTHORS section.  In the AUTHORS
     section, the default is -nosplit for the first author listing and -split
     for all other author listings.

     Examples:
	   .An -nosplit
	   .An Kristaps Dzonsons Aq kristaps@bsd.lv

   Ao
     Begin a block enclosed by angle brackets.	Does not have any head
     arguments.

     Examples:
	   .Fl -key= Ns Ao Ar val Ac

     See also Aq.

   Ap
     Inserts an apostrophe without any surrounding whitespace.	This is
     generally used as a grammatical device when referring to the verb form of
     a function.

     Examples:
	   .Fn execve Ap d

   Aq
     Encloses its arguments in angle brackets.

     Examples:
	   .Fl -key= Ns Aq Ar val

     Remarks: this macro is often abused for rendering URIs, which should
     instead use Lk or Mt, or to note pre-processor ``#include'' statements,
     which should use In.

     See also Ao.

   Ar
     Command arguments.	 If an argument is not provided, the string ``file
     ...'' is used as a default.

     Examples:
	   .Fl o Ns Ar file1
	   .Ar
	   .Ar arg1, arg2.

   At
     Formats an AT&T version.  Accepts one optional argument:

	   v[1-7] | 32v	  A version of AT&T UNIX.
	   V[.[1-4]]?	  A version of AT&T System V UNIX.

     Note that these arguments do not begin with a hyphen.

     Examples:
	   .At
	   .At V.1

     See also Bsx, Bx, Dx, Fx, Nx, Ox, and Ux.

   Bc
     Close a Bo block.	Does not have any tail arguments.

   Bd
     Begin a display block.  Its syntax is as follows:

	   .Bd -type [-offset width] [-compact]

     Display blocks are used to select a different indentation and
     justification than the one used by the surrounding text.  They may
     contain both macro lines and free-form text lines.	 By default, a display
     block is preceded by a vertical space.

     The type must be one of the following:

	   -centered	  Centre-justify each line.  Using this display type
			  is not recommended; many mdoc implementations render
			  it poorly.

	   -filled	  Left- and right-justify the block.

	   -literal	  Do not justify the block at all.  Preserve white
			  space as it appears in the input.

	   -ragged	  Only left-justify the block.

	   -unfilled	  An alias for -literal.

     The type must be provided first.  Additional arguments may follow:

	   -offset width  Indent the display by the width, which may be one of
			  the following:

			  One of the pre-defined strings indent, the width of
			  standard indentation; indent-two, twice indent;
			  left, which has no effect; right, which justifies to
			  the right margin; or center, which aligns around an
			  imagined centre axis.

			  A macro invocation, which selects a predefined width
			  associated with that macro.  The most popular is the
			  imaginary macro Ds, which resolves to 6n.

			  A width using the syntax described in Scaling
			  Widths.

			  An arbitrary string, which indents by the length of
			  this string.

			  When the argument is missing, -offset is ignored.

	   -compact	  Do not assert vertical space before the display.

     Examples:

	   .Bd -literal -offset indent -compact
	      Hello	  world.
	   .Ed

     See also D1 and Dl.

   Bf
     Change the font mode for a scoped block of text.  Its syntax is as
     follows:

	   .Bf [-emphasis | -literal | -symbolic | Em | Li | Sy]

     The -emphasis and Em argument are equivalent, as are -symbolic and Sy,
     and -literal and Li.  Without an argument, this macro does nothing.  The
     font mode continues until broken by a new font mode in a nested scope or
     Ef is encountered.

     See also Li, Ef, Em, and Sy.

   Bk
     Keep the output generated from each macro input line together on one
     single output line.  Line breaks in free-form text lines are unaffected.
     The syntax is as follows:

	   .Bk -words

     The -words argument is required; additional arguments are ignored.

     The following example will not break within each Op macro line:

	   .Bk -words
	   .Op Fl f Ar flags
	   .Op Fl o Ar output
	   .Ek

     Be careful in using over-long lines within a keep block!  Doing so will
     clobber the right margin.

   Bl
     Begin a list.  Lists consist of items specified using the It macro,
     containing a head or a body or both.  The list syntax is as follows:

	   .Bl -type [-width val] [-offset val] [-compact] [HEAD ...]

     The list type is mandatory and must be specified first.  The -width and
     -offset arguments accept Scaling Widths or use the length of the given
     string.  The -offset is a global indentation for the whole list,
     affecting both item heads and bodies.  For those list types supporting
     it, the -width argument requests an additional indentation of item
     bodies, to be added to the -offset.  Unless the -compact argument is
     specified, list entries are separated by vertical space.

     A list must specify one of the following list types:

	   -bullet	 No item heads can be specified, but a bullet will be
			 printed at the head of each item.  Item bodies start
			 on the same output line as the bullet and are
			 indented according to the -width argument.

	   -column	 A columnated list.  The -width argument has no
			 effect; instead, each argument specifies the width of
			 one column, using either the Scaling Widths syntax or
			 the string length of the argument.  If the first line
			 of the body of a -column list is not an It macro
			 line, It contexts spanning one input line each are
			 implied until an It macro line is encountered, at
			 which point items start being interpreted as
			 described in the It documentation.

	   -dash	 Like -bullet, except that dashes are used in place of
			 bullets.

	   -diag	 Like -inset, except that item heads are not parsed
			 for macro invocations.

	   -enum	 A numbered list.  Formatted like -bullet, except that
			 cardinal numbers are used in place of bullets,
			 starting at 1.

	   -hang	 Like -tag, except that the first lines of item bodies
			 are not indented, but follow the item heads like in
			 -inset lists.

	   -hyphen	 Synonym for -dash.

	   -inset	 Item bodies follow items heads on the same line,
			 using normal inter-word spacing.  Bodies are not
			 indented, and the -width argument is ignored.

	   -item	 No item heads can be specified, and none are printed.
			 Bodies are not indented, and the -width argument is
			 ignored.

	   -ohang	 Item bodies start on the line following item heads
			 and are not indented.	The -width argument is
			 ignored.

	   -tag		 Item bodies are indented according to the -width
			 argument.  When an item head fits inside the
			 indentation, the item body follows this head on the
			 same output line.  Otherwise, the body starts on the
			 output line following the head.

     See also El and It.

   Bo
     Begin a block enclosed by square brackets.	 Does not have any head
     arguments.

     Examples:
	   .Bo 1 ,
	   .Dv BUFSIZ Bc

     See also Bq.

   Bq
     Encloses its arguments in square brackets.

     Examples:
	   .Bq 1, Dv BUFSIZ

     Remarks: this macro is sometimes abused to emulate optional arguments for
     commands; the correct macros to use for this purpose are Op, Oo, and Oc.

     See also Bo.

   Brc
     Close a Bro block.	 Does not have any tail arguments.

   Bro
     Begin a block enclosed by curly braces.  Does not have any head
     arguments.

     Examples:
	   .Bro 1 , ... ,
	   .Va n Brc

     See also Brq.

   Brq
     Encloses its arguments in curly braces.

     Examples:
	   .Brq 1, ..., Va n

     See also Bro.

   Bsx
     Format the BSD/OS version provided as an argument, or a default value if
     no argument is provided.

     Examples:
	   .Bsx 1.0
	   .Bsx

     See also At, Bx, Dx, Fx, Nx, Ox, and Ux.

   Bt
     Prints ``is currently in beta test''.

   Bx
     Format the BSD version provided as an argument, or a default value if no
     argument is provided.

     Examples:
	   .Bx 4.4
	   .Bx

     See also At, Bsx, Dx, Fx, Nx, Ox, and Ux.

   Cd
     Kernel configuration declaration.	This denotes strings accepted by
     config(8).

     Examples:
	   .Cd device le0 at scode?

     Remarks: this macro is commonly abused by using quoted literals to retain
     whitespace and align consecutive Cd declarations.	This practise is
     discouraged.

   Cm
     Command modifiers.	 Useful when specifying configuration options or keys.

     Examples:
	   .Cm ControlPath
	   .Cm ControlMaster

     See also Fl.

   D1
     One-line indented display.	 This is formatted by the default rules and is
     useful for simple indented statements.  It is followed by a newline.

     Examples:
	   .D1 Fl abcdefgh

     See also Bd and Dl.

   Db
     Switch debugging mode.  Its syntax is as follows:

	   .Db on | off

     This macro is ignored by mandoc(1).

   Dc
     Close a Do block.	Does not have any tail arguments.

   Dd
     Document date.  This is the mandatory first macro of any mdoc manual.
     Its syntax is as follows:

	   .Dd [date]

     The date may be either $Mdocdate$, which signifies the current manual
     revision date dictated by cvs(1), or instead a valid canonical date as
     specified by Dates.  If a date does not conform or is empty, the current
     date is used.

     Examples:
	   .Dd $Mdocdate$
	   .Dd $Mdocdate: July 21 2007$
	   .Dd July 21, 2007

     See also Dt and Os.

   Dl
     One-line intended display.	 This is formatted as literal text and is
     useful for commands and invocations.  It is followed by a newline.

     Examples:
	   .Dl % mandoc mdoc.7 \(ba less

     See also Bd and D1.

   Do
     Begin a block enclosed by double quotes.  Does not have any head
     arguments.

     Examples:
	   .Do
	   April is the cruellest month
	   .Dc
	   \(em T.S. Eliot

     See also Dq.

   Dq
     Encloses its arguments in ``typographic'' double-quotes.

     Examples:
	   .Dq April is the cruellest month
	   \(em T.S. Eliot

     See also Qq, Sq, and Do.

   Dt
     Document title.  This is the mandatory second macro of any mdoc file.
     Its syntax is as follows:

	   .Dt [title [section [volume | arch]]]

     Its arguments are as follows:

       title   The document's title (name), defaulting to ``UNKNOWN'' if
	       unspecified.  It should be capitalised.

       section
	       The manual section.  This may be one of 1 (utilities), 2
	       (system calls), 3 (libraries), 3p (Perl libraries), 4
	       (devices), 5 (file formats), 6 (games), 7 (miscellaneous), 8
	       (system utilities), 9 (kernel functions), X11 (X Window
	       System), X11R6 (X Window System), unass (unassociated), local
	       (local system), draft (draft manual), or paper (paper).	It
	       should correspond to the manual's filename suffix and defaults
	       to ``1'' if unspecified.

       volume  This overrides the volume inferred from section.	 This field is
	       optional, and if specified, must be one of USD (users'
	       supplementary documents), PS1 (programmers' supplementary
	       documents), AMD (administrators' supplementary documents), SMM
	       (system managers' manuals), URM (users' reference manuals), PRM
	       (programmers' reference manuals), KM (kernel manuals), IND
	       (master index), MMI (master index), LOCAL (local manuals), LOC
	       (local manuals), or CON (contributed manuals).

       arch    This specifies a specific relevant architecture.	 If volume is
	       not provided, it may be used in its place, else it may be used
	       subsequent that.	 It, too, is optional.	It must be one of
	       alpha, amd64, amiga, arc, arm, armish, aviion, hp300, hppa,
	       hppa64, i386, landisk, loongson, luna88k, mac68k, macppc,
	       mips64, mvme68k, mvme88k, mvmeppc, pmax, sgi, socppc, sparc,
	       sparc64, sun3, vax, or zaurus.

     Examples:
	   .Dt FOO 1
	   .Dt FOO 4 KM
	   .Dt FOO 9 i386

     See also Dd and Os.

   Dv
     Defined variables such as preprocessor constants.

     Examples:
	   .Dv BUFSIZ
	   .Dv STDOUT_FILENO

     See also Er.

   Dx
     Format the DragonFly BSD version provided as an argument, or a default
     value if no argument is provided.

     Examples:
	   .Dx 2.4.1
	   .Dx

     See also At, Bsx, Bx, Fx, Nx, Ox, and Ux.

   Ec
     Close a scope started by Eo.  Its syntax is as follows:

	   .Ec [TERM]

     The TERM argument is used as the enclosure tail, for example, specifying
     \(rq will emulate Dc.

   Ed
     End a display context started by Bd.

   Ef
     End a font mode context started by Bf.

   Ek
     End a keep context started by Bk.

   El
     End a list context started by Bl.

     See also Bl and It.

   Em
     Denotes text that should be emphasised.  Note that this is a presentation
     term and should not be used for stylistically decorating technical terms.

     Examples:
	   .Em Warnings!
	   .Em Remarks:

     See also Bf, Sy, and Li.

   En
     This macro is obsolete and not implemented in mandoc(1).

   Eo
     An arbitrary enclosure.  Its syntax is as follows:

	   .Eo [TERM]

     The TERM argument is used as the enclosure head, for example, specifying
     \(lq will emulate Do.

   Er
     Display error constants.

     Examples:
	   .Er EPERM
	   .Er ENOENT

     See also Dv.

   Es
     This macro is obsolete and not implemented.

   Ev
     Environmental variables such as those specified in environ(7).

     Examples:
	   .Ev DISPLAY
	   .Ev PATH

   Ex
     Insert a standard sentence regarding exit values.	Its syntax is as
     follows:

	   .Ex -std [utility]

     When utility is not specified, the document's name set by Nm is used.

     See also Rv.

   Fa
     Function argument.	 Its syntax is as follows:

	   .Fa [argtype] argname

     This may be invoked for names with or without the corresponding type.  It
     is also used to specify the field name of a structure.  Most often, the
     Fa macro is used in the SYNOPSIS within Fo section when documenting
     multi-line function prototypes.  If invoked with multiple arguments, the
     arguments are separated by a comma.  Furthermore, if the following macro
     is another Fa, the last argument will also have a trailing comma.

     Examples:
	   .Fa "const char *p"
	   .Fa "int a" "int b" "int c"
	   .Fa foo

     See also Fo.

   Fc
     End a function context started by Fo.

   Fd
     Historically used to document include files.  This usage has been
     deprecated in favour of In.  Do not use this macro.

     See also MANUAL STRUCTURE and In.

   Fl
     Command-line flag.	 Used when listing arguments to command-line
     utilities.	 Prints a fixed-width hyphen `-' directly followed by each
     argument.	If no arguments are provided, a hyphen is printed followed by
     a space.  If the argument is a macro, a hyphen is prefixed to the
     subsequent macro output.

     Examples:
	   .Fl a b c
	   .Fl Pf a b
	   .Fl
	   .Op Fl o Ns Ar file

     See also Cm.

   Fn
     A function name.  Its syntax is as follows:

	   .Fn [functype] funcname [[argtype] argname]

     Function arguments are surrounded in parenthesis and are delimited by
     commas.  If no arguments are specified, blank parenthesis are output.

     Examples:
	   .Fn int funcname int arg0 int arg1
	   .Fn funcname int arg0
	   .Fn funcname arg0
	   .Ft functype
	   .Fn funcname

     When referring to a function documented in another manual page, use Xr
     instead.  See also MANUAL STRUCTURE and Ft.

   Fo
     Begin a function block.  This is a multi-line version of Fn.  Its syntax
     is as follows:

	   .Fo funcname

     Invocations usually occur in the following context:

	   .Ft functype
	   .Fo funcname
	   .Fa [argtype] argname
	   ...
	   .Fc

     A Fo scope is closed by

     See also MANUAL STRUCTURE, Fa, Fc, and Ft.

   Ft
     A function type.  Its syntax is as follows:

	   .Ft functype

     Examples:
	   .Ft int
	   .Ft functype
	   .Fn funcname

     See also MANUAL STRUCTURE, Fn, and Fo.

   Fx
     Format the FreeBSD version provided as an argument, or a default value if
     no argument is provided.

     Examples:
	   .Fx 7.1
	   .Fx

     See also At, Bsx, Bx, Dx, Nx, Ox, and Ux.

   Hf
     This macro is obsolete and not implemented.

   Ic
     Designate an internal or interactive command.  This is similar to Cm but
     used for instructions rather than values.

     Examples:
	   .Ic hash
	   .Ic alias

     Note that using Bd -literal or D1 is preferred for displaying code; the
     Ic macro is used when referring to specific instructions.

   In
     An ``include'' file.  In the SYNOPSIS section (only if invoked as the
     line macro), the first argument is preceded by ``#include'', the
     arguments is enclosed in angle brackets.

     Examples:
	   .In sys/types

     See also MANUAL STRUCTURE.

   It
     A list item.  The syntax of this macro depends on the list type.

     Lists of type -hang, -ohang, -inset, and -diag have the following syntax:

	   .It args

     Lists of type -bullet, -dash, -enum, -hyphen and -item have the following
     syntax:

	   .It

     with subsequent lines interpreted within the scope of the It until either
     a closing El or another It.

     The -tag list has the following syntax:

	   .It [args]

     Subsequent lines are interpreted as with -bullet and family.  The line
     arguments correspond to the list's left-hand side; body arguments
     correspond to the list's contents.

     The -column list is the most complicated.	Its syntax is as follows:

	   .It [args]

     The args are phrases, a mix of macros and text corresponding to a line
     column, delimited by tabs or the special `Ta' pseudo-macro.  Lines
     subsequent the It are interpreted within the scope of the last phrase.
     Calling the pseudo-macro `Ta' will open a new phrase scope (this must
     occur on a macro line to be interpreted as a macro).  Note that the tab
     phrase delimiter may only be used within the It line itself.  Subsequent
     this, only the `Ta' pseudo-macro may be used to delimit phrases.
     Furthermore, note that quoted sections propagate over tab-delimited
     phrases on an It, for example,

	   .It "col1; <TAB> col2 ;" ;

     will preserve the semicolon whitespace except for the last.

     See also Bl.

   Lb
     Specify a library.	 The syntax is as follows:

	   .Lb library

     The library parameter may be a system library, such as libz or libpam, in
     which case a small library description is printed next to the linker
     invocation; or a custom library, in which case the library name is
     printed in quotes.	 This is most commonly used in the SYNOPSIS section as
     described in MANUAL STRUCTURE.

     Examples:
	   .Lb libz
	   .Lb mdoc

   Li
     Denotes text that should be in a literal font mode.  Note that this is a
     presentation term and should not be used for stylistically decorating
     technical terms.

     See also Bf, Sy, and Em.

   Lk
     Format a hyperlink.  Its syntax is as follows:

	   .Lk uri [name]

     Examples:
	   .Lk http://bsd.lv "The BSD.lv Project"
	   .Lk http://bsd.lv

     See also Mt.

   Lp
     Synonym for Pp.

   Ms
     Display a mathematical symbol.  Its syntax is as follows:

	   .Ms symbol

     Examples:
	   .Ms sigma
	   .Ms aleph

   Mt
     Format a ``mailto:'' hyperlink.  Its syntax is as follows:

	   .Mt address

     Examples:
	   .Mt discuss@manpages.bsd.lv

   Nd
     A one line description of the manual's content.  This may only be invoked
     in the SYNOPSIS section subsequent the Nm macro.

     Examples:
	   .Sx Nd mdoc language reference
	   .Sx Nd format and display UNIX manuals

     The Nd macro technically accepts child macros and terminates with a
     subsequent Sh invocation.	Do not assume this behaviour: some whatis(1)
     database generators are not smart enough to parse more than the line
     arguments and will display macros verbatim.

     See also Nm.

   Nm
     The name of the manual page, or -- in particular in section 1, 6, and 8
     pages -- of an additional command or feature documented in the manual
     page.  When first invoked, the Nm macro expects a single argument, the
     name of the manual page.  Usually, the first invocation happens in the
     NAME section of the page.	The specified name will be remembered and used
     whenever the macro is called again without arguments later in the page.
     The Nm macro uses Block full-implicit semantics when invoked as the first
     macro on an input line in the SYNOPSIS section; otherwise, it uses
     ordinary In-line semantics.

     Examples:

	   .Sh SYNOPSIS
	   .Nm cat
	   .Op Fl benstuv
	   .Op Ar

     In the SYNOPSIS of section 2, 3 and 9 manual pages, use the Fn macro
     rather than Nm to mark up the name of the manual page.

   No
     A ``noop'' macro used to terminate prior macro contexts.

     Examples:
	   .Sx Fl ab No cd Fl ef

   Ns
     Suppress a space.	Following invocation, text is interpreted as free-form
     text until a macro is encountered.

     This has no effect when invoked at the start of a macro line.

     Examples:
	   .Fl o Ns Ar output

     See also No and Sm.

   Nx
     Format the NetBSD version provided as an argument, or a default value if
     no argument is provided.

     Examples:
	   .Nx 5.01
	   .Nx

     See also At, Bsx, Bx, Dx, Fx, Ox, and Ux.

   Oc
     Close multi-line Oo context.

   Oo
     Multi-line version of Op.

     Examples:
	   .Oo
	   .Op Fl flag Ns Ar value
	   .Oc

   Op
     Command-line option.  Used when listing options to command-line
     utilities.	 Prints the argument(s) in brackets.

     Examples:
	   .Op Fl a Ar b
	   .Op Ar a | b

     See also Oo.

   Os
     Document operating system version.	 This is the mandatory third macro of
     any mdoc file.  Its syntax is as follows:

	   .Os [system [version]]

     The optional system parameter specifies the relevant operating system or
     environment.  Left unspecified, it defaults to the local operating system
     version.  This is the suggested form.

     Examples:
	   .Os
	   .Os KTH/CSC/TCS
	   .Os BSD 4.3

     See also Dd and Dt.

   Ot
     Unknown usage.

     Remarks: this macro has been deprecated.

   Ox
     Format the OpenBSD version provided as an argument, or a default value if
     no argument is provided.

     Examples:
	   .Ox 4.5
	   .Ox

     See also At, Bsx, Bx, Dx, Fx, Nx, and Ux.

   Pa
     A file-system path.  If an argument is not provided, the string ``~'' is
     used as a default.

     Examples:
	   .Pa /usr/bin/mandoc
	   .Pa /usr/share/man/man7/mdoc.7

     See also Lk.

   Pc
     Close parenthesised context opened by Po.

   Pf
     Removes the space (``prefix'') between its arguments.  Its syntax is as
     follows:

	   .Pf prefix suffix

     The suffix argument may be a macro.

     Examples:
	   .Pf \. Sx Pf Cm prefix suffix

   Po
     Multi-line version of Pq.

   Pp
     Break a paragraph.	 This will assert vertical space between prior and
     subsequent macros and/or text.

   Pq
     Parenthesised enclosure.

     See also Po.

   Qc
     Close quoted context opened by Qo.

   Ql
     Format a single-quoted literal.  See also Qq and Sq.

   Qo
     Multi-line version of Qq.

   Qq
     Encloses its arguments in ``typewriter'' double-quotes.  Consider using
     Dq.

     See also Dq, Sq, and Qo.

   Re
     Close an Rs block.	 Does not have any tail arguments.

   Rs
     Begin a bibliographic (``reference'') block.  Does not have any head
     arguments.	 The block macro may only contain %A, %B, %C, %D, %I, %J, %N,
     %O, %P, %Q, %R, %T, %U, and %V child macros (at least one must be
     specified).

     Examples:
	   .Rs
	   .%A J. E. Hopcroft
	   .%A J. D. Ullman
	   .%B Introduction to Automata Theory, Languages, and Computation
	   .%I Addison-Wesley
	   .%C Reading, Massachusettes
	   .%D 1979
	   .Re

     If an Rs block is used within a SEE ALSO section, a vertical space is
     asserted before the rendered output, else the block continues on the
     current line.

   Rv
     Inserts text regarding a function call's return value.  This macro must
     consist of the -std argument followed by an optional function.  If
     function is not provided, the document's name as stipulated by the first
     Nm is provided.

     See also Ex.

   Sc
     Close single-quoted context opened by So.

   Sh
     Begin a new section.  For a list of conventional manual sections, see
     MANUAL STRUCTURE.	These sections should be used unless it's absolutely
     necessary that custom sections be used.

     Section names should be unique so that they may be keyed by Sx.

     See also Pp, Ss, and Sx.

   Sm
     Switches the spacing mode for output generated from macros.  Its syntax
     is as follows:

	   .Sm on | off

     By default, spacing is on.	 When switched off, no white space is inserted
     between macro arguments and between the output generated from adjacent
     macros, but free-form text lines still get normal spacing between words
     and sentences.

   So
     Multi-line version of Sq.

   Sq
     Encloses its arguments in ``typewriter'' single-quotes.

     See also Dq, Qq, and So.

   Ss
     Begin a new sub-section.  Unlike with Sh, there's no convention for sub-
     sections.	Conventional sections, as described in MANUAL STRUCTURE,
     rarely have sub-sections.

     Sub-section names should be unique so that they may be keyed by Sx.

     See also Pp, Sh, and Sx.

   St
     Replace an abbreviation for a standard with the full form.	 The following
     standards are recognised:

     -p1003.1-88      IEEE Std 1003.1-1988 (``POSIX'')
     -p1003.1-90      IEEE Std 1003.1-1990 (``POSIX'')
     -p1003.1-96      ISO/IEC 9945-1:1996 (``POSIX'')
     -p1003.1-2001    IEEE Std 1003.1-2001 (``POSIX'')
     -p1003.1-2004    IEEE Std 1003.1-2004 (``POSIX'')
     -p1003.1-2008    IEEE Std 1003.1-2008 (``POSIX'')
     -p1003.1	      IEEE Std 1003.1 (``POSIX'')
     -p1003.1b	      IEEE Std 1003.1b (``POSIX'')
     -p1003.1b-93     IEEE Std 1003.1b-1993 (``POSIX'')
     -p1003.1c-95     IEEE Std 1003.1c-1995 (``POSIX'')
     -p1003.1g-2000   IEEE Std 1003.1g-2000 (``POSIX'')
     -p1003.1i-95     IEEE Std 1003.1i-1995 (``POSIX.1'')
     -p1003.2-92      IEEE Std 1003.2-1992 (``POSIX.2'')
     -p1003.2a-92     IEEE Std 1003.2a-1992 (``POSIX.2'')
     -p1387.2-95      IEEE Std 1387.2-1995 (``POSIX.7.2'')
     -p1003.2	      IEEE Std 1003.2 (``POSIX.2'')
     -p1387.2	      IEEE Std 1387.2 (``POSIX.7.2'')
     -isoC	      ISO/IEC 9899:1990 (``ISO C90'')
     -isoC-90	      ISO/IEC 9899:1990 (``ISO C90'')
     -isoC-amd1	      ISO/IEC 9899/AMD1:1995 (``ISO C90'')
     -isoC-tcor1      ISO/IEC 9899/TCOR1:1994 (``ISO C90'')
     -isoC-tcor2      ISO/IEC 9899/TCOR2:1995 (``ISO C90'')
     -isoC-99	      ISO/IEC 9899:1999 (``ISO C99'')
     -iso9945-1-90    ISO/IEC 9945-1:1990 (``POSIX.1'')
     -iso9945-1-96    ISO/IEC 9945-1:1996 (``POSIX.1'')
     -iso9945-2-93    ISO/IEC 9945-2:1993 (``POSIX.2'')
     -ansiC	      ANSI X3.159-1989 (``ANSI C'')
     -ansiC-89	      ANSI X3.159-1989 (``ANSI C'')
     -ansiC-99	      ANSI/ISO/IEC 9899-1999 (``ANSI C99'')
     -ieee754	      IEEE Std 754-1985
     -iso8802-3	      ISO 8802-3: 1989
     -ieee1275-94     IEEE Std 1275-1994 (``Open Firmware'')
     -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'') X/Open
		      Portability Guide Issue 4.3 (``XPG4.3'')
     -xbd5	      X/Open System Interface Definitions Issue 5 (``XBD5'')
     -xcu5	      X/Open Commands and Utilities Issue 5 (``XCU5'')
     -xsh5	      X/Open System Interfaces and Headers Issue 5 (``XSH5'')
     -xns5	      X/Open Networking Services Issue 5 (``XNS5'')
     -xns5.2	      X/Open Networking Services Issue 5.2 (``XNS5.2'')
     -xns5.2d2.0      X/Open Networking Services Issue 5.2 Draft 2.0
		      (``XNS5.2D2.0'')
     -xcurses4.2      X/Open Curses Issue 4 Version 2 (``XCURSES4.2'')
     -susv2	      Version 2 of the Single UNIX Specification
     -susv3	      Version 3 of the Single UNIX Specification
     -svid4	      System V Interface Definition, Fourth Edition
		      (``SVID4'')

   Sx
     Reference a section or sub-section.  The referenced section or sub-
     section name must be identical to the enclosed argument, including
     whitespace.

     Examples:
	   .Sx MANUAL STRUCTURE

     See also Sh and Ss.

   Sy
     Format enclosed arguments in symbolic (``boldface'').  Note that this is
     a presentation term and should not be used for stylistically decorating
     technical terms.

     See also Bf, Li, and Em.

   Tn
     Format a tradename.

     Examples:
	   .Tn IBM

   Ud
     Prints out ``currently under development''.

   Ux
     Format the UNIX name.  Accepts no argument.

     Examples:
	   .Ux

     See also At, Bsx, Bx, Dx, Fx, Nx, and Ox.

   Va
     A variable name.

     Examples:
	   .Va foo
	   .Va const char *bar;

   Vt
     A variable type.  This is also used for indicating global variables in
     the SYNOPSIS section, in which case a variable name is also specified.
     Note that it accepts Block partial-implicit syntax when invoked as the
     first macro in the SYNOPSIS section, else it accepts ordinary In-line
     syntax.

     Note that this should not be confused with Ft, which is used for function
     return types.

     Examples:
	   .Vt unsigned char
	   .Vt extern const char * const sys_signame[] ;

     See also MANUAL STRUCTURE and Va.

   Xc
     Close a scope opened by Xo.

   Xo
     Extend the header of an It macro or the body of a partial-implicit block
     macro beyond the end of the input line.  This macro originally existed to
     work around the 9-argument limit of historic roff(7).

   Xr
     Link to another manual ("cross-reference").  Its syntax is as follows:

	   .Xr name section

     The name and section are the name and section of the linked manual.  If
     section is followed by non-punctuation, an Ns is inserted into the token
     stream.  This behaviour is for compatibility with GNU troff.

     Examples:
	   .Xr mandoc 1
	   .Xr mandoc 1 ;
	   .Xr mandoc 1 Ns s behaviour

   br
     Emits a line-break.  This macro should not be used; it is implemented for
     compatibility with historical manuals.

     Consider using Pp in the event of natural paragraph breaks.

   sp
     Emits vertical space.  This macro should not be used; it is implemented
     for compatibility with historical manuals.	 Its syntax is as follows:

	   .sp [height]

     The height argument must be formatted as described in Scaling Widths.  If
     unspecified, sp asserts a single vertical space.

COMPATIBILITY
     This section documents compatibility between mandoc and other other troff
     implementations, at this time limited to GNU troff ("groff").  The term
     "historic groff" refers to groff versions before 1.17, which featured a
     significant update of the doc.tmac file.

     Heirloom troff, the other significant troff implementation accepting
     -mdoc, is similar to historic groff.

     The following problematic behaviour is found in groff:

     -	 Display macros (Bd, Dl, and D1) may not be nested.  (Historic groff
	 only.)
     -	 At with unknown arguments produces no output at all.  (Historic groff
	 only.)	 Newer groff and mandoc print "AT&T UNIX" and the arguments.
     -	 Bd -column does not recognize trailing punctuation characters when
	 they immediately precede tabulator characters, but treats them as
	 normal text and outputs a space before them.
     -	 Bd -ragged -compact does not start a new line.	 (Historic groff
	 only.)
     -	 Dd without an argument prints ``Epoch''.  In mandoc, it resolves to
	 the current date.
     -	 Fl does not print a dash for an empty argument.  (Historic groff
	 only.)
     -	 Fn does not start a new line unless invoked as the line macro in the
	 SYNOPSIS section.  (Historic groff only.)
     -	 Fo with non-Fa children causes inconsistent spacing between
	 arguments.  In mandoc, a single space is always inserted between
	 arguments.
     -	 Ft in the SYNOPSIS causes inconsistent vertical spacing, depending on
	 whether a prior Fn has been invoked.  See Ft and Fn for the
	 normalised behaviour in mandoc.
     -	 In ignores additional arguments and is not treated specially in the
	 SYNOPSIS.  (Historic groff only.)
     -	 It sometimes requires a -nested flag.	(Historic groff only.)	In new
	 groff and mandoc, any list may be nested by default and -enum lists
	 will restart the sequence only for the sub-list.
     -	 Li followed by a reserved character is incorrectly used in some
	 manuals instead of properly quoting that character, which sometimes
	 works with historic groff.
     -	 Lk only accepts a single link-name argument; the remainder is
	 misformatted.
     -	 Pa does not format its arguments when used in the FILES section under
	 certain list types.
     -	 Ta can only be called by other macros, but not at the beginning of a
	 line.
     -	 %C is not implemented.
     -	 Historic groff only allows up to eight or nine arguments per macro
	 input line, depending on the exact situation.	Providing more
	 arguments causes garbled output.  The number of arguments on one
	 input line is not limited with mandoc.
     -	 Historic groff has many un-callable macros.  Most of these (excluding
	 some block-level macros) are callable in new groff and mandoc.
     -	 `|' (vertical bar) is not fully supported as a delimiter.  (Historic
	 groff only.)
     -	 `\f' (font face) and `\f' (font family face) Text Decoration escapes
	 behave irregularly when specified within line-macro scopes.
     -	 Negative scaling units return to prior lines.	Instead, mandoc
	 truncates them to zero.

     The following features are unimplemented in mandoc:

     -	 Bd -file file.
     -	 Bd -offset center and -offset right.  Groff does not implement
	 centered and flush-right rendering either, but produces large
	 indentations.
     -	 The `\h' (horizontal position), `\v' (vertical position), `\m' (text
	 colour), `\M' (text filling colour), `\z' (zero-length character),
	 `\w' (string length), `\k' (horizontal position marker), `\o' (text
	 overstrike), and `\s' (text size) escape sequences are all discarded
	 in mandoc.
     -	 The `\f' scaling unit is accepted by mandoc, but rendered as the
	 default unit.
     -	 In quoted literals, groff allows pairwise double-quotes to produce a
	 standalone double-quote in formatted output.  This is not supported
	 by mandoc.

SEE ALSO
     man(1), mandoc(1), man(7), mandoc_char(7), mdoc.samples(7), roff(7),
     tbl(7)

HISTORY
     The mdoc language first appeared as a troff macro package in 4.4BSD.  It
     was later significantly updated by Werner Lemberg and Ruslan Ermilov in
     groff-1.17.  The standalone implementation that is part of the mandoc(1)
     utility written by Kristaps Dzonsons appeared in OpenBSD 4.6.

AUTHORS
     The mdoc reference was written by Kristaps Dzonsons <kristaps@bsd.lv>.

OpenBSD 4.9		       February 7, 2011			   OpenBSD 4.9
[top]

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net