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

Diff for /mandoc/mdoc.7 between version 1.142 and 1.152

version 1.142, 2010/07/26 13:45:49 version 1.152, 2010/08/24 12:18:49
Line 28  language is used to format
Line 28  language is used to format
 .Bx  .Bx
 .Ux  .Ux
 manuals.  manuals.
 In this reference document, we describe its syntax, structure, and  This reference document describes its syntax, structure, and
 usage.  usage.
 Our reference implementation is mandoc; the  The reference implementation is
   .Xr mandoc 1 ;
   the
 .Sx COMPATIBILITY  .Sx COMPATIBILITY
 section describes compatibility with other troff \-mdoc implementations.  section describes compatibility with other troff \-mdoc implementations.
 .Pp  .Pp
Line 61  line.
Line 63  line.
 A macro line with only a control character and comment escape,  A macro line with only a control character and comment escape,
 .Sq \&.\e\*q ,  .Sq \&.\e\*q ,
 is also ignored.  is also ignored.
 Macro lines with only a control character and optionally whitespace are  Macro lines with only a control character and optional whitespace are
 stripped from input.  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:
Line 107  for two-character sequences; an open-bracket
Line 109  for two-character sequences; an open-bracket
 .Sq \&[  .Sq \&[
 for n-character sequences (terminated at a close-bracket  for n-character sequences (terminated at a close-bracket
 .Sq \&] ) ;  .Sq \&] ) ;
 or a single one-character sequence.  or a single one character sequence.
 See  See
 .Xr mandoc_char 7  .Xr mandoc_char 7
 for a complete list.  for a complete list.
Line 120  and
Line 122  and
 .Ss Text Decoration  .Ss Text Decoration
 Terms may be text-decorated using the  Terms may be text-decorated using the
 .Sq \ef  .Sq \ef
 escape followed by an indicator: B (bold), I, (italic), R (Roman), or P  escape followed by an indicator: B (bold), I (italic), R (Roman), or P
 (revert to previous mode):  (revert to previous mode):
 .Pp  .Pp
 .D1 \efBbold\efR \efIitalic\efP  .D1 \efBbold\efR \efIitalic\efP
Line 147  recommended for
Line 149  recommended for
 which encourages semantic annotation.  which encourages semantic annotation.
 .Ss Predefined Strings  .Ss Predefined Strings
 Historically,  Historically,
 .Xr groff 1  troff
 also defined a set of package-specific  also defined a set of package-specific
 .Dq predefined strings ,  .Dq predefined strings ,
 which, like  which, like
Line 172  and
Line 174  and
 .Pq vertical bar .  .Pq vertical bar .
 .Ss Whitespace  .Ss Whitespace
 Whitespace consists of the space character.  Whitespace consists of the space character.
 In free-form lines, whitespace is preserved within a line; un-escaped  In free-form lines, whitespace is preserved within a line; unescaped
 trailing spaces are stripped from input (unless in a literal context).  trailing spaces are stripped from input (unless in a literal context).
 Blank free-form lines, which may include whitespace, are only permitted  Blank free-form lines, which may include whitespace, are only permitted
 within literal contexts.  within literal contexts.
Line 183  If arguments are quoted, whitespace within the quotes 
Line 185  If arguments are quoted, whitespace within the quotes 
 Macro arguments may be quoted with double-quotes to group  Macro arguments may be quoted with double-quotes to group
 space-delimited terms or to retain blocks of whitespace.  space-delimited terms or to retain blocks of whitespace.
 A quoted argument begins with a double-quote preceded by whitespace.  A quoted argument begins with a double-quote preceded by whitespace.
 The next double-quote not pair-wise adjacent to another double-quote  The next double-quote not pairwise adjacent to another double-quote
 terminates the literal, regardless of surrounding whitespace.  terminates the literal, regardless of surrounding whitespace.
 .Pp  .Pp
 Note that any quoted text, even if it would cause a macro invocation  Note that any quoted text, even if it would cause a macro invocation
Line 276  is necessarily non-portable across output media.
Line 278  is necessarily non-portable across output media.
 See  See
 .Sx COMPATIBILITY .  .Sx COMPATIBILITY .
 .Ss Sentence Spacing  .Ss Sentence Spacing
 When composing a manual, make sure that your sentences end at the end of  When composing a manual, make sure that sentences end at the end of
 a line.  a line.
 By doing so, front-ends will be able to apply the proper amount of  By doing so, front-ends will be able to apply the proper amount of
 spacing after the end of sentence (unescaped) period, exclamation mark,  spacing after the end of sentence (unescaped) period, exclamation mark,
Line 288  delimiters (
Line 290  delimiters (
 .Sq \&" ) .  .Sq \&" ) .
 .Pp  .Pp
 The proper spacing is also intelligently preserved if a sentence ends at  The proper spacing is also intelligently preserved if a sentence ends at
 the boundary of a macro line, e.g.,  the boundary of a macro line.
   For example:
 .Pp  .Pp
 .D1 \&Xr mandoc 1 \.  .D1 \&Xr mandoc 1 \.
 .D1 \&Fl T \&Ns \&Cm ascii \.  .D1 \&Fl T \&Ns \&Cm ascii \.
Line 361  utility processes files ...
Line 364  utility processes files ...
 \&.\e\*q .Sh SECURITY CONSIDERATIONS  \&.\e\*q .Sh SECURITY CONSIDERATIONS
 .Ed  .Ed
 .Pp  .Pp
 The sections in a  The sections in an
 .Nm  .Nm
 document are conventionally ordered as they appear above.  document are conventionally ordered as they appear above.
 Sections should be composed as follows:  Sections should be composed as follows:
 .Bl -ohang -offset Ds  .Bl -ohang -offset Ds
 .It Em NAME  .It Em NAME
 The name(s) and a one-line description of the documented material.  The name(s) and a one line description of the documented material.
 The syntax for this as follows:  The syntax for this as follows:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Nm name0  \&.Nm name0 ,
 \&.Nm name1  \&.Nm name1 ,
 \&.Nm name2  \&.Nm name2
 \&.Nd a one-line description  \&.Nd a one line description
 .Ed  .Ed
 .Pp  .Pp
 The  The
Line 415  generally structured as follows:
Line 418  generally structured as follows:
 .Pp  .Pp
 For the second, function calls (sections 2, 3, 9):  For the second, function calls (sections 2, 3, 9):
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Vt extern const char *global;  
 \&.In header.h  \&.In header.h
   \&.Vt extern const char *global;
 \&.Ft "char *"  \&.Ft "char *"
 \&.Fn foo "const char *src"  \&.Fn foo "const char *src"
 \&.Ft "char *"  \&.Ft "char *"
Line 445  section, particularly
Line 448  section, particularly
 and  and
 .Sx \&Ft .  .Sx \&Ft .
 All of these macros are output on their own line.  All of these macros are output on their own line.
 If two such dissimilar macros are pair-wise invoked (except for  If two such dissimilar macros are pairwise invoked (except for
 .Sx \&Ft  .Sx \&Ft
 before  before
 .Sx \&Fo  .Sx \&Fo
Line 471  or
Line 474  or
 .Sx \&Ss  .Sx \&Ss
 macro or the end of an enclosing block, whichever comes first.  macro or the end of an enclosing block, whichever comes first.
 .It Em DESCRIPTION  .It Em DESCRIPTION
 This expands upon the brief, one-line description in  This expands upon the brief, one line description in
 .Em NAME .  .Em NAME .
 It usually contains a break-down of the options (if documenting a  It usually contains a breakdown of the options (if documenting a
 command), such as:  command), such as:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 The arguments are as follows:  The arguments are as follows:
Line 489  Implementation-specific notes should be kept here.
Line 492  Implementation-specific notes should be kept here.
 This is useful when implementing standard functions that may have side  This is useful when implementing standard functions that may have side
 effects or notable algorithmic implications.  effects or notable algorithmic implications.
 .It Em RETURN VALUES  .It Em RETURN VALUES
 This section is the dual of  This section documents the
 .Em EXIT STATUS ,  return values of functions in sections 2, 3, and 9.
 which is used for commands.  
 It documents the return values of functions in sections 2, 3, and 9.  
 .Pp  .Pp
 See  See
 .Sx \&Rv .  .Sx \&Rv .
Line 513  the file is used (created, modified, etc.).
Line 514  the file is used (created, modified, etc.).
 See  See
 .Sx \&Pa .  .Sx \&Pa .
 .It Em EXIT STATUS  .It Em EXIT STATUS
 Command exit status for section 1, 6, and 8 manuals.  This section documents the
 This section is the dual of  command exit status for section 1, 6, and 8 utilities.
 .Em RETURN VALUES ,  
 which is used for functions.  
 Historically, this information was described in  Historically, this information was described in
 .Em DIAGNOSTICS ,  .Em DIAGNOSTICS ,
 a practise that is now discouraged.  a practise that is now discouraged.
Line 526  See
Line 525  See
 .It Em EXAMPLES  .It Em EXAMPLES
 Example usages.  Example usages.
 This often contains snippets of well-formed, well-tested invocations.  This often contains snippets of well-formed, well-tested invocations.
 Make doubly sure that your examples work properly!  Make sure that examples work properly!
 .It Em DIAGNOSTICS  .It Em DIAGNOSTICS
 Documents error conditions.  Documents error conditions.
 This is most useful in section 4 manuals.  This is most useful in section 4 manuals.
Line 560  section should be used instead.
Line 559  section should be used instead.
 See  See
 .Sx \&St .  .Sx \&St .
 .It Em HISTORY  .It Em HISTORY
 The history of any manual without a  A brief history of the subject, including where support first appeared.
 .Em STANDARDS  
 section should be described in this section.  
 .It Em AUTHORS  .It Em AUTHORS
 Credits to authors, if applicable, should appear in this section.  Credits to the person or persons who wrote the code and/or documentation.
 Authors should generally be noted by both name and email address.  Authors should generally be noted by both name and email address.
 .Pp  .Pp
 See  See
Line 573  See
Line 570  See
 Common misuses and misunderstandings should be explained  Common misuses and misunderstandings should be explained
 in this section.  in this section.
 .It Em BUGS  .It Em BUGS
 Known bugs, limitations and work-arounds should be described  Known bugs, limitations, and work-arounds should be described
 in this section.  in this section.
 .It Em SECURITY CONSIDERATIONS  .It Em SECURITY CONSIDERATIONS
 Documents any security precautions that operators should consider.  Documents any security precautions that operators should consider.
Line 771  If a number (or inequality) of arguments is
Line 768  If a number (or inequality) of arguments is
 .Pq n ,  .Pq n ,
 then the macro accepts an arbitrary number of arguments.  then the macro accepts an arbitrary number of arguments.
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
   
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
   
Line 879  referring to book titles.
Line 876  referring to book titles.
 Publication city or location of an  Publication city or location of an
 .Sx \&Rs  .Sx \&Rs
 block.  block.
 .Pp  
 .Em Remarks :  
 this macro is not implemented in  
 .Xr groff 1 .  
 .Ss \&%D  .Ss \&%D
 Publication date of an  Publication date of an
 .Sx \&Rs  .Sx \&Rs
Line 1161  and
Line 1154  and
 argument are equivalent, as are  argument are equivalent, as are
 .Fl symbolic  .Fl symbolic
 and  and
 .Cm \&Sy,  .Cm \&Sy ,
 and  and
 .Fl literal  .Fl literal
 and  and
Line 1395  and
Line 1388  and
 .Sx \&Ux .  .Sx \&Ux .
 .Ss \&Bt  .Ss \&Bt
 Prints  Prints
 .Dq is currently in beta test.  .Dq is currently in beta test .
 .Ss \&Bx  .Ss \&Bx
 Format the BSD version provided as an argument, or a default value if no  Format the BSD version provided as an argument, or a default value if no
 argument is provided.  argument is provided.
Line 1927  See also
Line 1920  See also
 and  and
 .Sx \&Fo .  .Sx \&Fo .
 .Ss \&Fx  .Ss \&Fx
 Format the FreeBSD version provided as an argument, or a default value  Format the
   .Fx
   version provided as an argument, or a default value
 if no argument is provided.  if no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
Line 1956  Examples:
Line 1951  Examples:
 .D1 \&.Ic alias  .D1 \&.Ic alias
 .Pp  .Pp
 Note that using  Note that using
 .Sx \&Bd No Fl literal  .Sx \&Bd Fl literal
 or  or
 .Sx \&D1  .Sx \&D1
 is preferred for displaying code; the  is preferred for displaying code; the
Line 2100  Its syntax is as follows:
Line 2095  Its syntax is as follows:
 .D1 Pf \. Sx \&Lk Cm uri Op Cm name  .D1 Pf \. Sx \&Lk Cm uri Op Cm name
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Lk http://bsd.lv "The BSD.lv Project"  .D1 \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q
 .D1 \&.Lk http://bsd.lv  .D1 \&.Lk http://bsd.lv
 .Pp  .Pp
 See also  See also
Line 2128  Its syntax is as follows:
Line 2123  Its syntax is as follows:
 Examples:  Examples:
 .D1 \&.Mt discuss@manpages.bsd.lv  .D1 \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd  .Ss \&Nd
 A one-line description of the manual's content.  A one line description of the manual's content.
 This may only be invoked in the  This may only be invoked in the
 .Em SYNOPSIS  .Em SYNOPSIS
 section subsequent the  section subsequent the
Line 2208  See also
Line 2203  See also
 and  and
 .Sx \&Sm .  .Sx \&Sm .
 .Ss \&Nx  .Ss \&Nx
 Format the NetBSD version provided as an argument, or a default value if  Format the
   .Nx
   version provided as an argument, or a default value if
 no argument is provided.  no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
Line 2257  any
Line 2254  any
 file.  file.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Os Op Cm system  .D1 Pf \. Sx \&Os Op Cm system Op Cm version
 .Pp  .Pp
 The optional  The optional
 .Cm system  .Cm system
Line 2280  Unknown usage.
Line 2277  Unknown usage.
 .Em Remarks :  .Em Remarks :
 this macro has been deprecated.  this macro has been deprecated.
 .Ss \&Ox  .Ss \&Ox
 Format the OpenBSD version provided as an argument, or a default value  Format the
   .Ox
   version provided as an argument, or a default value
 if no argument is provided.  if no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
Line 2600  Examples:
Line 2599  Examples:
 .D1 \&.Tn IBM  .D1 \&.Tn IBM
 .Ss \&Ud  .Ss \&Ud
 Prints out  Prints out
 .Dq currently under development.  .Dq currently under development .
 .Ss \&Ux  .Ss \&Ux
 Format the UNIX name.  Format the UNIX name.
 Accepts no argument.  Accepts no argument.
Line 2673  is followed by non-punctuation, an
Line 2672  is followed by non-punctuation, an
 .Sx \&Ns  .Sx \&Ns
 is inserted into the token stream.  is inserted into the token stream.
 This behaviour is for compatibility with  This behaviour is for compatibility with
 .Xr groff 1 .  GNU troff.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Xr mandoc 1  .D1 \&.Xr mandoc 1
Line 2716  file re-write
Line 2715  file re-write
 Heirloom troff, the other significant troff implementation accepting  Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.  \-mdoc, is similar to historic groff.
 .Pp  .Pp
   The following problematic behaviour is found in groff:
   .ds hist (Historic groff only.)
   .Pp
 .Bl -dash -compact  .Bl -dash -compact
 .It  .It
 An empty  .Sx \&At
 .Sq \&Dd  with unknown arguments produces no output at all.
 macro in groff prints  \*[hist]
   Newer groff and mandoc print
   .Qq AT&T UNIX
   and the arguments.
   .It
   .Sx \&Bd Fl 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.
   .It
   .Sx \&Bd Fl ragged compact
   does not start a new line.
   \*[hist]
   .It
   .Sx \&Dd
   without an argument prints
 .Dq Epoch .  .Dq Epoch .
 In mandoc, it resolves to the current date.  In mandoc, it resolves to the current date.
 .It  .It
 The \es (font size), \em (font colour), and \eM (font filling colour)  .Sx \&Fl
 font decoration escapes are all discarded in mandoc.  does not print a dash for an empty argument.
   \*[hist]
 .It  .It
 Old groff fails to assert a newline before  .Sx \&Fn
 .Sx \&Bd Fl ragged compact .  does not start a new line unless invoked as the line macro in the
   .Em SYNOPSIS
   section.
   \*[hist]
 .It  .It
 groff behaves inconsistently when encountering  
 .Pf non- Sx \&Fa  
 children of  
 .Sx \&Fo  .Sx \&Fo
 regarding spacing between arguments.  with
 In mandoc, this is not the case: each argument is consistently followed  .Pf non- Sx \&Fa
 by a single space and the trailing  children causes inconsistent spacing between arguments.
 .Sq \&)  In mandoc, a single space is always inserted between arguments.
 suppresses prior spacing.  
 .It  .It
 groff behaves inconsistently when encountering  
 .Sx \&Ft  .Sx \&Ft
 and  
 .Sx \&Fn  
 in the  in the
 .Em SYNOPSIS :  .Em SYNOPSIS
 at times newline(s) are suppressed depending on whether a prior  causes inconsistent vertical spacing, depending on whether a prior
 .Sx \&Fn  .Sx \&Fn
 has been invoked.  has been invoked.
 In mandoc, this is not the case.  
 See  See
 .Sx \&Ft  .Sx \&Ft
 and  and
 .Sx \&Fn  .Sx \&Fn
 for the normalised behaviour.  for the normalised behaviour in mandoc.
 .It  .It
 Historic groff does not break before an  
 .Sx \&Fn  
 when not invoked as the line macro in the  
 .Em SYNOPSIS  
 section.  
 .It  
 Historic groff formats the  
 .Sx \&In  .Sx \&In
 badly: trailing arguments are trashed and  ignores additional arguments and is not treated specially in the
 .Em SYNOPSIS  .Em SYNOPSIS .
 is not specially treated.  \*[hist]
 .It  .It
 groff does not accept the  .Sx \&It
 .Sq \&Ta  sometimes requires a
 pseudo-macro as a line macro.  .Fl nested
 mandoc does.  flag.
   \*[hist]
   In new groff and mandoc, any list may be nested by default and
   .Fl enum
   lists will restart the sequence only for the sub-list.
 .It  .It
 The comment syntax  .Sx \&Li
 .Sq \e\."  followed by a reserved character is incorrectly used in some manuals
 is no longer accepted.  instead of properly quoting that character, which sometimes works with
   historic groff.
 .It  .It
 In groff, the  .Sx \&Lk
   only accepts a single link-name argument; the remainder is misformatted.
   .It
 .Sx \&Pa  .Sx \&Pa
 macro does not format its arguments when used in the FILES section under  does not format its arguments when used in the FILES section under
 certain list types.  certain list types.
 mandoc does.  
 .It  .It
 Historic groff does not print a dash for empty  .Sx \&Ta
 .Sx \&Fl  can only be called by other macros, but not at the beginning of a line.
 arguments.  
 mandoc and newer groff implementations do.  
 .It  .It
 groff behaves irregularly when specifying  .Sx \&%C
   is not implemented.
   .It
   Historic groff has many un-callable macros.
   Most of these (excluding some block-level macros) are callable
   in new groff and mandoc.
   .It
   .Sq \(ba
   (vertical bar) is not fully supported as a delimiter.
   \*[hist]
   .It
 .Sq \ef  .Sq \ef
   .Pq font face
   and
   .Sq \ef
   .Pq font family face
 .Sx Text Decoration  .Sx Text Decoration
 within line-macro scopes.  escapes behave irregularly when specified within line-macro scopes.
 mandoc follows a consistent system.  
 .It  .It
 In mandoc, negative scaling units are truncated to zero; groff would  Negative scaling units return to prior lines.
 move to prior lines.  Instead, mandoc truncates them to zero.
 Furthermore, the  .El
 .Sq f  .Pp
 scaling unit, while accepted, is rendered as the default unit.  The following features are unimplemented in mandoc:
   .Pp
   .Bl -dash -compact
 .It  .It
 In quoted literals, groff allowed pair-wise double-quotes to produce a  .Sx \&Bd
 standalone double-quote in formatted output.  .Fl file Ar file .
 This idiosyncratic behaviour is not applicable in mandoc.  
 .It  .It
 Display offsets  
 .Sx \&Bd  .Sx \&Bd
 .Fl offset Ar center  .Fl offset Ar center
 and  and
 .Fl offset Ar right  .Fl offset Ar right .
 are disregarded in mandoc.  Groff does not implement centered and flush-right rendering either,
 Furthermore, troff specifies a  but produces large indentations.
 .Fl file Ar file  
 argument that is not supported in mandoc.  
 Lastly, since text is not right-justified in mandoc (or even groff),  
 .Fl ragged  
 and  
 .Fl filled  
 are aliases, as are  
 .Fl literal  
 and  
 .Fl unfilled .  
 .It  .It
 Historic groff has many un-callable macros.  The
 Most of these (excluding some block-level macros) are now callable.  .Sq \eh
 .It  .Pq horizontal position ,
 The vertical bar  .Sq \ev
 .Sq \(ba  .Pq vertical position ,
 made historic groff  .Sq \em
 .Qq go orbital  .Pq text colour ,
 but has been a proper delimiter since then.  .Sq \eM
 .It  .Pq text filling colour ,
 .Sx \&It Fl nested  .Sq \ez
 is assumed for all lists (it wasn't in historic groff): any list may be  .Pq zero-length character ,
 nested and  
 .Fl enum  
 lists will restart the sequence only for the sub-list.  
 .It  
 Some manuals use  
 .Sx \&Li  
 incorrectly by following it with a reserved character and expecting the  
 delimiter to render.  
 This is not supported in mandoc.  
 .It  
 In groff, the  
 .Sx \&Cd ,  
 .Sx \&Er ,  
 .Sx \&Ex ,  
 and  and
 .Sx \&Rv  .Sq \es
 macros were stipulated only to occur in certain manual sections.  .Pq text size
 mandoc does not have these restrictions.  .Sx Text Decoration
   escapes are all discarded in mandoc.
 .It  .It
 Newer groff and mandoc print  The
 .Qq AT&T UNIX  .Sq \ef
 prior to unknown arguments of  scaling unit is accepted by mandoc, but rendered as the default unit.
 .Sx \&At ;  .It
 older groff did nothing.  In quoted literals, groff allows pairwise double-quotes to produce a
   standalone double-quote in formatted output.
   This is not supported by mandoc.
 .El  .El
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr mandoc 1 ,  .Xr mandoc 1 ,
 .Xr mandoc_char 7  .Xr mandoc_char 7
   .Sh HISTORY
   The
   .Nm
   language first appeared as a troff macro package in
   .Bx 4.4 .
   It was later significantly updated by Werner Lemberg and Ruslan Ermilov
   in groff-1.20.1.
   The standalone implementation that is part of the
   .Xr mandoc 1
   utility written by Kristaps Dzonsons appeared in
   .Ox 4.6 .
 .Sh AUTHORS  .Sh AUTHORS
 The  The
 .Nm  .Nm
Legend:
Removed from v.1.142  
changed lines
  Added in v.1.152
CVSweb