[BACK]Return to mdoc.7 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.137 and 1.138

version 1.137, 2010/07/19 10:48:36 version 1.138, 2010/07/19 15:28:11
Line 27  The
Line 27  The
 language is used to format  language is used to format
 .Bx  .Bx
 .Ux  .Ux
 manuals.  In this reference document, we describe its syntax, structure,  manuals.
 and usage.  Our reference implementation is mandoc; the  In this reference document, we describe its syntax, structure, and
   usage.
   Our reference implementation is mandoc; the
 .Sx COMPATIBILITY  .Sx COMPATIBILITY
 section describes compatibility with other troff \-mdoc implementations.  section describes compatibility with other troff \-mdoc implementations.
 .Pp  .Pp
Line 37  An
Line 39  An
 document follows simple rules: lines beginning with the control  document follows simple rules: lines beginning with the control
 character  character
 .Sq \.  .Sq \.
 are parsed for macros.  Other lines are interpreted within the scope of  are parsed for macros.
   Other lines are interpreted within the scope of
 prior macros:  prior macros:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Sh Macro lines change control state.  \&.Sh Macro lines change control state.
Line 46  Other lines are interpreted within the current state.
Line 49  Other lines are interpreted within the current state.
 .Sh LANGUAGE SYNTAX  .Sh LANGUAGE SYNTAX
 .Nm  .Nm
 documents may contain only graphable 7-bit ASCII characters, the space  documents may contain only graphable 7-bit ASCII characters, the space
 character, and, in certain circumstances, the tab character.  All  character, and, in certain circumstances, the tab character.
 manuals must have  All manuals must have
 .Ux  .Ux
 line terminators.  line terminators.
 .Ss Comments  .Ss Comments
 Text following a  Text following a
 .Sq \e\*q ,  .Sq \e\*q ,
 whether in a macro or free-form text line, is ignored to the end of  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,  line.
   A macro line with only a control character and comment escape,
 .Sq \&.\e\*q ,  .Sq \&.\e\*q ,
 is also ignored.  Macro lines with only a control character and optionally  is also ignored.
 whitespace are stripped from input.  Macro lines with only a control character and optionally whitespace are
   stripped from input.
 .Ss Reserved Characters  .Ss Reserved Characters
 Within a macro line, the following characters are reserved:  Within a macro line, the following characters are reserved:
 .Pp  .Pp
Line 445  section, particularly
Line 450  section, particularly
 .Sx \&Vt ,  .Sx \&Vt ,
 and  and
 .Sx \&Ft .  .Sx \&Ft .
 All of these macros are output on their own line.  If two such  All of these macros are output on their own line.
 dissimilar macros are pair-wise invoked (except for  If two such dissimilar macros are pair-wise invoked (except for
 .Sx \&Ft  .Sx \&Ft
 before  before
 .Sx \&Fo  .Sx \&Fo
Line 858  For the scoping of individual macros, see
Line 863  For the scoping of individual macros, see
 .Ss \&%A  .Ss \&%A
 Author name of an  Author name of an
 .Sx \&Rs  .Sx \&Rs
 block.  Multiple authors should each be accorded their own  block.
   Multiple authors should each be accorded their own
 .Sx \%%A  .Sx \%%A
 line.  Author names should be ordered with full or abbreviated  line.
 forename(s) first, then full surname.  Author names should be ordered with full or abbreviated forename(s)
   first, then full surname.
 .Ss \&%B  .Ss \&%B
 Book title of an  Book title of an
 .Sx \&Rs  .Sx \&Rs
 block.  This macro may also be used in a non-bibliographic context when  block.
   This macro may also be used in a non-bibliographic context when
 referring to book titles.  referring to book titles.
 .Ss \&%C  .Ss \&%C
 Publication city or location of an  Publication city or location of an
Line 878  this macro is not implemented in
Line 886  this macro is not implemented in
 .Ss \&%D  .Ss \&%D
 Publication date of an  Publication date of an
 .Sx \&Rs  .Sx \&Rs
 block.  This should follow the reduced or canonical form syntax  block.
 described in  This should follow the reduced or canonical form syntax described in
 .Sx Dates .  .Sx Dates .
 .Ss \&%I  .Ss \&%I
 Publisher or issuer name of an  Publisher or issuer name of an
Line 904  block.
Line 912  block.
 .Ss \&%Q  .Ss \&%Q
 Institutional author (school, government, etc.) of an  Institutional author (school, government, etc.) of an
 .Sx \&Rs  .Sx \&Rs
 block.  Multiple institutional authors should each be accorded their own  block.
   Multiple institutional authors should each be accorded their own
 .Sx \&%Q  .Sx \&%Q
 line.  line.
 .Ss \&%R  .Ss \&%R
Line 914  block.
Line 923  block.
 .Ss \&%T  .Ss \&%T
 Article title of an  Article title of an
 .Sx \&Rs  .Sx \&Rs
 block.  This macro may also be used in a non-bibliographical context  block.
 when referring to article titles.  This macro may also be used in a non-bibliographical context when
   referring to article titles.
 .Ss \&%U  .Ss \&%U
 URI of reference document.  URI of reference document.
 .Ss \&%V  .Ss \&%V
Line 925  block.
Line 935  block.
 .Ss \&Ac  .Ss \&Ac
 Closes an  Closes an
 .Sx \&Ao  .Sx \&Ao
 block.  Does not have any tail arguments.  block.
   Does not have any tail arguments.
 .Ss \&Ad  .Ss \&Ad
 Address construct: usually in the context of an computational address in  Address construct: usually in the context of an computational address in
 memory, not a physical (post) address.  memory, not a physical (post) address.
Line 976  Examples:
Line 987  Examples:
 See also  See also
 .Sx \&Aq .  .Sx \&Aq .
 .Ss \&Ap  .Ss \&Ap
 Inserts an apostrophe without any surrounding white-space.  Inserts an apostrophe without any surrounding whitespace.
 This is generally used as a grammatical device when referring to the verb  This is generally used as a grammatical device when referring to the verb
 form of a function:  form of a function:
 .Bd -literal -offset indent  .Bd -literal -offset indent
Line 1040  and
Line 1051  and
 .Ss \&Bc  .Ss \&Bc
 Closes a  Closes a
 .Sx \&Bo  .Sx \&Bo
 block.  Does not have any tail arguments.  block.
   Does not have any tail arguments.
 .Ss \&Bd  .Ss \&Bd
 Begins a display block.  Begins a display block.
 Its syntax is as follows:  Its syntax is as follows:
Line 1289  The
Line 1301  The
 .Fl width  .Fl width
 argument is ignored.  argument is ignored.
 .It Fl tag  .It Fl tag
 A list offset by list entry heads.  List entry bodies are positioned  A list offset by list entry heads.
 after the head as specified by the  List entry bodies are positioned after the head as specified by the
 .Fl width  .Fl width
 argument.  argument.
 .El  .El
Line 1328  See also
Line 1340  See also
 .Ss \&Brc  .Ss \&Brc
 Closes a  Closes a
 .Sx \&Bro  .Sx \&Bro
 block.  Does not have any tail arguments.  block.
   Does not have any tail arguments.
 .Ss \&Bro  .Ss \&Bro
 Begins a block enclosed by curly braces.  Begins a block enclosed by curly braces.
 Does not have any head arguments.  Does not have any head arguments.
Line 1396  Examples:
Line 1409  Examples:
 .Pp  .Pp
 .Em Remarks :  .Em Remarks :
 this macro is commonly abused by using quoted literals to retain  this macro is commonly abused by using quoted literals to retain
 white-space and align consecutive  whitespace and align consecutive
 .Sx \&Cd  .Sx \&Cd
 declarations.  declarations.
 This practise is discouraged.  This practise is discouraged.
Line 1432  Its syntax is as follows:
Line 1445  Its syntax is as follows:
 .Ss \&Dc  .Ss \&Dc
 Closes a  Closes a
 .Sx \&Do  .Sx \&Do
 block.  Does not have any tail arguments.  block.
   Does not have any tail arguments.
 .Ss \&Dd  .Ss \&Dd
 Document date.  Document date.
 This is the mandatory first macro of any  This is the mandatory first macro of any
Line 1475  See also
Line 1489  See also
 and  and
 .Sx \&D1 .  .Sx \&D1 .
 .Ss \&Do  .Ss \&Do
 Begins a block enclosed by double quotes.  Does not have any head  Begins a block enclosed by double quotes.
 arguments.  Does not have any head arguments.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot  .D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot
Line 1484  Examples:
Line 1498  Examples:
 See also  See also
 .Sx \&Dq .  .Sx \&Dq .
 .Ss \&Dq  .Ss \&Dq
 Encloses its arguments in double quotes.  Encloses its arguments in
   .Dq typographic
   double-quotes.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent -compact  .Bd -literal -offset indent -compact
Line 1493  Examples:
Line 1509  Examples:
 .Ed  .Ed
 .Pp  .Pp
 See also  See also
   .Ss \&Qq ,
   .Ss \&Sq ,
   and
 .Sx \&Do .  .Sx \&Do .
 .Ss \&Dt  
 Document title.  Document title.
 This is the mandatory second macro of any  This is the mandatory second macro of any
 .Nm  .Nm
Line 1515  Its arguments are as follows:
Line 1533  Its arguments are as follows:
 .Bl -tag -width Ds -offset Ds  .Bl -tag -width Ds -offset Ds
 .It Cm title  .It Cm title
 The document's title (name), defaulting to  The document's title (name), defaulting to
 .Qq UNKNOWN  .Dq UNKNOWN
 if unspecified.  if unspecified.
 It should be capitalised.  It should be capitalised.
 .It Cm section  .It Cm section
Line 1555  or
Line 1573  or
 .Ar paper  .Ar paper
 .Pq paper .  .Pq paper .
 It should correspond to the manual's filename suffix and defaults to  It should correspond to the manual's filename suffix and defaults to
 .Qq 1  .Dq 1
 if unspecified.  if unspecified.
 .It Cm volume  .It Cm volume
 This overrides the volume inferred from  This overrides the volume inferred from
Line 1696  stylistically decorating technical terms.
Line 1714  stylistically decorating technical terms.
 Examples:  Examples:
 .D1 \&.Em Warnings!  .D1 \&.Em Warnings!
 .D1 \&.Em Remarks :  .D1 \&.Em Remarks :
   .Pp
   See also
   .Sx \&Bf ,
   .Sx \&Sy ,
   and
   .Sx \&Li .
 .Ss \&En  .Ss \&En
 This macro is obsolete and not implemented.  This macro is obsolete and not implemented.
 .Ss \&Eo  .Ss \&Eo
Line 1913  is preferred for displaying code; the
Line 1937  is preferred for displaying code; the
 macro is used when referring to specific instructions.  macro is used when referring to specific instructions.
 .Ss \&In  .Ss \&In
 An  An
 .Qq include  .Dq include
 file.  file.
 In the  In the
 .Em SYNOPSIS  .Em SYNOPSIS
 section (only if invoked as the line macro), the first argument is  section (only if invoked as the line macro), the first argument is
 preceded by  preceded by
 .Qq #include ,  .Dq #include ,
 the arguments is enclosed in angled braces.  the arguments is enclosed in angled braces.
 .Pp  .Pp
 Examples:  Examples:
Line 1991  are interpreted within the scope of the last phrase.
Line 2015  are interpreted within the scope of the last phrase.
 Calling the pseudo-macro  Calling the pseudo-macro
 .Sq \&Ta  .Sq \&Ta
 will open a new phrase scope (this must occur on a macro line to be  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  interpreted as a macro).
 used within the  Note that the tab phrase delimiter may only be used within the
 .Sx \&It  .Sx \&It
 line itself.  line itself.
 Subsequent this, only the  Subsequent this, only the
Line 2036  Examples:
Line 2060  Examples:
 Denotes text that should be in a literal font mode.  Denotes text that should be in a literal font mode.
 Note that this is a presentation term and should not be used for  Note that this is a presentation term and should not be used for
 stylistically decorating technical terms.  stylistically decorating technical terms.
   .Pp
   See also
   .Sx \&Bf ,
   .Sx \&Sy ,
   and
   .Sx \&Em .
 .Ss \&Lk  .Ss \&Lk
 Format a hyperlink.  Format a hyperlink.
 Its syntax is as follows:  Its syntax is as follows:
Line 2052  See also
Line 2082  See also
 Synonym for  Synonym for
 .Sx \&Pp .  .Sx \&Pp .
 .Ss \&Ms  .Ss \&Ms
   Display a mathematical symbol.
   .Pp
   Examples:
   .D1 \&.Ms sigma
   .D1 \&.Ms aleph
 .Ss \&Mt  .Ss \&Mt
 Format a  Format a
 .Qq mailto:  .Dq mailto:
 hyperlink.  hyperlink.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
Line 2125  macro rather than
Line 2160  macro rather than
 to mark up the name of the manual page.  to mark up the name of the manual page.
 .Ss \&No  .Ss \&No
 A  A
 .Qq noop  .Dq noop
 macro used to terminate prior macro contexts.  macro used to terminate prior macro contexts.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Sx \&Fl ab \&No cd \&Fl ef  .D1 \&.Sx \&Fl ab \&No cd \&Fl ef
 .Ss \&Ns  .Ss \&Ns
   Suppress a space.
   Following invocation, text is interpreted as free-form text until a
   macro is encountered.
   .Pp
   Examples:
   .D1 \&.Fl o \&Ns \&Ar output
   .Pp
   See also
   .Sx \&No
   and
   .Sx \&Sm .
 .Ss \&Nx  .Ss \&Nx
 Format the NetBSD version provided as an argument, or a default value if  Format the NetBSD version provided as an argument, or a default value if
 no argument is provided.  no argument is provided.
Line 2157  Multi-line version of
Line 2203  Multi-line version of
 .Sx \&Op .  .Sx \&Op .
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent -compact
 \&.Oo  \&.Oo
 \&.Op Fl flag Ns Ar value  \&.Op Fl flag Ns Ar value
 \&.Oc  \&.Oc
Line 2234  Close parenthesised context opened by
Line 2280  Close parenthesised context opened by
 .Sx \&Po .  .Sx \&Po .
 .Ss \&Pf  .Ss \&Pf
 Removes the space  Removes the space
 .Pq Qq prefix  .Pq Dq prefix
 between its arguments.  between its arguments.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
Line 2259  Parenthesised enclosure.
Line 2305  Parenthesised enclosure.
 See also  See also
 .Sx \&Po .  .Sx \&Po .
 .Ss \&Qc  .Ss \&Qc
   Close quoted context opened by
   .Sx \&Qo .
 .Ss \&Ql  .Ss \&Ql
   Format a single-quoted literal.
   See also
   .Sx \&Qq
   and
   .Sx \&Sq .
 .Ss \&Qo  .Ss \&Qo
   Multi-line version of
   .Sx \&Qq .
 .Ss \&Qq  .Ss \&Qq
   Encloses its arguments in
   .Dq typewriter
   double-quotes.
   Consider using
   .Sx \&Dq .
   .Pp
   See also
   .Sx \&Dq ,
   .Sx \&Sq ,
   and
   .Sx \&Qo .
 .Ss \&Re  .Ss \&Re
 Closes a  Closes a
 .Sx \&Rs  .Sx \&Rs
Line 2309  before the rendered output, else the block continues o
Line 2375  before the rendered output, else the block continues o
 line.  line.
 .Ss \&Rv  .Ss \&Rv
 .Ss \&Sc  .Ss \&Sc
   Close single-quoted context opened by
   .Sx \&So .
 .Ss \&Sh  .Ss \&Sh
   Begin a new section.
   For a list of conventional manual sections, see
   .Sx MANUAL STRUCTURE .
   These sections should be used unless it's absolutely necessary that
   custom sections be used.
   .Pp
   Section names should be unique so that they may be keyed by
   .Sx \&Sx .
   .Pp
   See also
   .Sx \&Pp ,
   .Sx \&Ss ,
   and
   .Sx \&Sx .
 .Ss \&Sm  .Ss \&Sm
 Switches the spacing mode for output generated from macros.  Switches the spacing mode for output generated from macros.
 Its syntax is as follows:  Its syntax is as follows:
Line 2324  no white space is inserted between macro arguments and
Line 2406  no white space is inserted between macro arguments and
 output generated from adjacent macros, but free-form text lines  output generated from adjacent macros, but free-form text lines
 still get normal spacing between words and sentences.  still get normal spacing between words and sentences.
 .Ss \&So  .Ss \&So
   Multi-line version of
   .Sx \&Sq .
 .Ss \&Sq  .Ss \&Sq
   Encloses its arguments in
   .Dq typewriter
   single-quotes.
   .Pp
   See also
   .Sx \&Dq ,
   .Sx \&Qq ,
   and
   .Sx \&So .
 .Ss \&Ss  .Ss \&Ss
   Begin a new sub-section.
   Unlike with
   .Sx \&Sh ,
   there's no convention for sub-sections.
   Conventional sections, as described in
   .Sx MANUAL STRUCTURE ,
   rarely have sub-sections.
   .Pp
   Sub-section names should be unique so that they may be keyed by
   .Sx \&Sx .
   .Pp
   See also
   .Sx \&Pp ,
   .Sx \&Sh ,
   and
   .Sx \&Sx .
 .Ss \&St  .Ss \&St
 .Ss \&Sx  .Ss \&Sx
   Reference a section or sub-section.
   The referenced section or sub-section name must be identical to the
   enclosed argument, including whitespace.
   .Pp
   Examples:
   .D1 \&.Sx MANUAL STRUCTURE
 .Ss \&Sy  .Ss \&Sy
   Format enclosed arguments in symbolic
   .Pq Dq boldface .
   Note that this is a presentation term and should not be used for
   stylistically decorating technical terms.
   .Pp
   See also
   .Sx \&Bf ,
   .Sx \&Li ,
   and
   .Sx \&Em .
 .Ss \&Tn  .Ss \&Tn
   Format a tradename.
   .Pp
   Examples:
   .D1 \&.Tn IBM .
 .Ss \&Ud  .Ss \&Ud
 Prints out  Prints out
 .Dq currently under development.  .Dq currently under development.
Line 2571  The
Line 2700  The
 .Nm  .Nm
 reference was written by  reference was written by
 .An Kristaps Dzonsons Aq kristaps@bsd.lv .  .An Kristaps Dzonsons Aq kristaps@bsd.lv .
 .\"  
 .\" XXX: this really isn't the place for these caveats.  
 .\" .  
 .\" .  
 .\" .Sh CAVEATS  
 .\" There are many ambiguous parts of mdoc.  
 .\" .  
 .\" .Pp  
 .\" .Bl -dash -compact  
 .\" .It  
 .\" .Sq \&Fa  
 .\" should be  
 .\" .Sq \&Va  
 .\" as function arguments are variables.  
 .\" .It  
 .\" .Sq \&Ft  
 .\" should be  
 .\" .Sq \&Vt  
 .\" as function return types are still types.  Furthermore, the  
 .\" .Sq \&Ft  
 .\" should be removed and  
 .\" .Sq \&Fo ,  
 .\" which ostensibly follows it, should follow the same convention as  
 .\" .Sq \&Va .  
 .\" .It  
 .\" .Sq \&Va  
 .\" should formalise that only one or two arguments are acceptable: a  
 .\" variable name and optional, preceding type.  
 .\" .It  
 .\" .Sq \&Fd  
 .\" is ambiguous.  It's commonly used to indicate an include file in the  
 .\" synopsis section.  
 .\" .Sq \&In  
 .\" should be used, instead.  
 .\" .It  
 .\" Only the  
 .\" .Sq \-literal  
 .\" argument to  
 .\" .Sq \&Bd  
 .\" makes sense.  The remaining ones should be removed.  
 .\" .It  
 .\" The  
 .\" .Sq \&Xo  
 .\" and  
 .\" .Sq \&Xc  
 .\" macros should be deprecated.  
 .\" .It  
 .\" The  
 .\" .Sq \&Dt  
 .\" macro lacks clarity.  It should be absolutely clear which title will  
 .\" render when formatting the manual page.  
 .\" .It  
 .\" A  
 .\" .Sq \&Lx  
 .\" should be provided for Linux (\(`a la  
 .\" .Sq \&Ox ,  
 .\" .Sq \&Nx  
 .\" etc.).  
 .\" .It  
 .\" There's no way to refer to references in  
 .\" .Sq \&Rs/Re  
 .\" blocks.  
 .\" .It  
 .\" The \-split and \-nosplit dictates via  
 .\" .Sq \&An  
 .\" are re-set when entering and leaving the AUTHORS section.  
 .\" .El  
 .\" .  

Legend:
Removed from v.1.137  
changed lines
  Added in v.1.138

CVSweb