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

Diff for /mandoc/mdoc.7 between version 1.69 and 1.82

version 1.69, 2009/10/24 05:52:13 version 1.82, 2010/01/07 19:10:10
Line 131  and
Line 131  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), or P and R  escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
 (Roman, or reset).  This form is not recommended for  (revert to previous mode):
   .Pp
   .D1 \efBbold\efR \efIitalic\efP
   .Pp
   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
   .Sx \&Bf
   .Cm \&Sy ,
   in-scope invocations of
   .Sq \ef
   are only valid within the font scope of the macro.  If
   .Sq \ef
   is specified outside of any font scope, such as in unenclosed, free-form
   text, it will affect the remainder of the document.
   .Pp
   Text may also be sized with the
   .Sq \es
   escape, whose syntax is one of
   .Sq \es+-n
   for one-digit numerals;
   .Sq \es(+-nn
   or
   .Sq \es+-(nn
   for two-digit numerals; and
   .Sq \es[+-N] ,
   .Sq \es+-[N] ,
   .Sq \es'+-N' ,
   or
   .Sq \es+-'N'
   for arbitrary-digit numerals:
   .Pp
   .D1 \es+1bigger\es-1
   .D1 \es[+10]much bigger\es[-10]
   .D1 \es+(10much bigger\es-(10
   .D1 \es+'100'much much bigger\es-'100'
   .Pp
   Note these forms are
   .Em not
   recommended for
 .Nm ,  .Nm ,
 which encourages semantic, not presentation, annotation.  which encourages semantic annotation.
 .  .
 .  .
 .Ss Predefined Strings  .Ss Predefined Strings
 Historically,  Historically,
 .Xr groff 1  .Xr groff 1
 also defined a set of package-specific  also defined a set of package-specific
 .Dq predefined strings ,  .Dq predefined strings ,
 which, like  which, like
 .Sx Special Characters ,  .Sx Special Characters ,
 demark special output characters and strings by way of input codes.  demark special output characters and strings by way of input codes.
 Predefined strings are escaped with the slash-asterisk,  Predefined strings are escaped with the slash-asterisk,
Line 212  In free-form mode, quotes are regarded as opaque text.
Line 252  In free-form mode, quotes are regarded as opaque text.
 .Ss Dates  .Ss Dates
 There are several macros in  There are several macros in
 .Nm  .Nm
 that require a date argument.  The  that require a date argument.  The canonical form for dates is the
 .Em canonical form  American format:
 for dates is the American format:  
 .Pp  .Pp
 .D1 Cm Month Day , Year  .D1 Cm Month Day , Year
 .Pp  .Pp
Line 226  value is the full month name.  The
Line 265  value is the full month name.  The
 .Cm Year  .Cm Year
 value is the full four-digit year.  value is the full four-digit year.
 .Pp  .Pp
 The  Reduced form dates are broken-down canonical form dates:
 .Em non-canonical form  
 is the same as the canonical form, but without the comma between the  
 .Cm Day  
 and  
 .Cm Year  
 field.  
 .Pp  .Pp
 Lastly,  .D1 Cm Month , Year
 .Em reduced form  .D1 Cm Year
 dates range from only a  
 .Cm Year  
 to the full canonical or non-canonical form.  
 .Pp  .Pp
 Some examples of valid dates follow:  Some examples of valid dates follow:
 .Pp  .Pp
 .D1 "May, 2009" Pq reduced form  .D1 "May, 2009" Pq reduced form
 .D1 "2009" Pq reduced form  .D1 "2009" Pq reduced form
 .D1 "May 20, 2009" Pq canonical form  .D1 "May 20, 2009" Pq canonical form
 .D1 "May 20 2009" Pq non-canonical form  
 .  .
 .Ss Scaling Widths  .Ss Scaling Widths
 Many macros support scaled widths for their arguments, such as  Many macros support scaled widths for their arguments, such as
Line 314  and
Line 343  and
 .Sx \&Os  .Sx \&Os
 macros, is required for every document.  macros, is required for every document.
 .Pp  .Pp
 The first section (sections are denoted by  The first section (sections are denoted by
 .Sx \&Sh )  .Sx \&Sh )
 must be the NAME section, consisting of at least one  must be the NAME section, consisting of at least one
 .Sx \&Nm  .Sx \&Nm
Line 374  The sections in a
Line 403  The sections in a
 .Nm  .Nm
 document are conventionally ordered as they appear above.  Sections  document are conventionally ordered as they appear above.  Sections
 should be composed as follows:  should be composed as follows:
 .Bl -tag -width Ds -offset Ds  .Bl -ohang -offset Ds
 .It NAME  .It Em NAME
 Must contain at least one  The name(s) and a short description of the documented material.  The
   syntax for this as follows:
   .Bd -literal -offset indent
   \&.Nm name0
   \&.Nm name1
   \&.Nm name2
   \&.Nd a short description
   .Ed
   .Pp
   The
 .Sx \&Nm  .Sx \&Nm
 followed by  macro(s) must precede the
   .Sx \&Nd
   macro.
   .Pp
   See
   .Sx \&Nm
   and
 .Sx \&Nd .  .Sx \&Nd .
 The name needs re-stating since one  .
 .Nm  .It Em LIBRARY
 documents can be used for more than one utility or function, such as  The name of the library containing the documented material, which is
 .Xr grep 1  assumed to be a function in a section 2 or 3 manual.  The syntax for
 also being referenced as  this is as follows:
 .Xr egrep 1  .Bd -literal -offset indent
   \&.Lb libarm
   .Ed
   .Pp
   See
   .Sx \&Lb .
   .
   .It Em SYNOPSIS
   Documents the utility invocation syntax, function call syntax, or device
   configuration.
   .Pp
   For the first, utilities (sections 1, 6, and 8), this is
   generally structured as follows:
   .Bd -literal -offset indent
   \&.Nm foo
   \&.Op Fl v
   \&.Op Fl o Ar file
   \&.Op Ar
   \&.Nm bar
   \&.Op Fl v
   \&.Op Fl o Ar file
   \&.Op Ar
   .Ed
   .Pp
   For the second, function calls (sections 2, 3, 9):
   .Bd -literal -offset indent
   \&.Vt extern const char *global;
   \&.In header.h
   \&.Ft "char *"
   \&.Fn foo "const char *src"
   \&.Ft "char *"
   \&.Fn bar "const char *src"
   .Ed
   .Pp
   And for the third, configurations (section 4):
   .Bd -literal -offset indent
   \&.Cd \*qit* at isa? port 0x2e\*q
   \&.Cd \*qit* at isa? port 0x4e\*q
   .Ed
   .Pp
   Manuals not in these sections generally don't need a
   .Em SYNOPSIS .
   .Pp
   See
   .Sx \&Op ,
   .Sx \&Cd ,
   .Sx \&Fn ,
   .Sx \&Ft ,
 and  and
 .Xr fgrep 1 .  .Sx \&Vt .
 .It LIBRARY  .
 .It SYNOPSIS  .It Em DESCRIPTION
 .It DESCRIPTION  This expands upon the brief, one-line description in
 .It IMPLEMENTATION NOTES  .Em NAME .
 .It EXIT STATUS  It usually contains a break-down of the options (if documenting a
 .It RETURN VALUES  command), such as:
 .It ENVIRONMENT  .Bd -literal -offset indent
 .It FILES  The arguments are as follows:
 .It EXAMPLES  \&.Bl \-tag \-width Ds
 .It DIAGNOSTICS  \&.It Fl v
 .It ERRORS  Print verbose information.
 .It SEE ALSO  \&.El
 .It STANDARDS  .Ed
 .It HISTORY  .Pp
 .It AUTHORS  Manuals not documenting a command won't include the above fragment.
 .It CAVEATS  .
 .It BUGS  .It Em IMPLEMENTATION NOTES
 .It SECURITY CONSIDERATIONS  Implementation-specific notes should be kept here.  This is useful when
   implementing standard functions that may have side effects or notable
   algorithmic implications.
   .
   .It Em EXIT STATUS
   Command exit status for section 1, 6, and 8 manuals.  This section is
   the dual of
   .Em RETURN VALUES ,
   which is used for functions.  Historically, this information was
   described in
   .Em DIAGNOSTICS ,
   a practise that is now discouraged.
   .Pp
   See
   .Sx \&Ex .
   .
   .It Em RETURN VALUES
   This section is the dual of
   .Em EXIT STATUS ,
   which is used for commands.  It documents the return values of functions
   in sections 2, 3, and 9.
   .Pp
   See
   .Sx \&Rv .
   .
   .It Em ENVIRONMENT
   Documents any usages of environment variables, e.g.,
   .Xr environ 7 .
   .Pp
   See
   .Sx \&Ev .
   .
   .It Em FILES
   Documents files used.  It's helpful to document both the file and a
   short description of how the file is used (created, modified, etc.).
   .Pp
   See
   .Sx \&Pa .
   .
   .It Em EXAMPLES
   Example usages.  This often contains snippets of well-formed,
   well-tested invocations.  Make doubly sure that your examples work
   properly!
   .
   .It Em DIAGNOSTICS
   Documents error conditions.  This is most useful in section 4 manuals.
   Historically, this section was used in place of
   .Em EXIT STATUS
   for manuals in sections 1, 6, and 8; however, this practise is
   discouraged.
   .Pp
   See
   .Sx \&Bl
   .Fl diag .
   .
   .It Em ERRORS
   Documents error handling in sections 2, 3, and 9.
   .Pp
   See
   .Sx \&Er .
   .
   .It Em 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.
   .Pp
   See
   .Sx \&Xr .
   .
   .It Em STANDARDS
   References any standards implemented or used.  If not adhering to any
   standards, the
   .Em HISTORY
   section should be used instead.
   .Pp
   See
   .Sx \&St .
   .
   .It Em HISTORY
   The history of any manual without a
   .Em STANDARDS
   section should be described in this section.
   .
   .It Em AUTHORS
   Credits to authors, if applicable, should appear in this section.
   Authors should generally be noted by both name and an e-mail address.
   .Pp
   See
   .Sx \&An .
   .
   .It Em CAVEATS
   Explanations of common misuses and misunderstandings should be explained
   in this section.
   .
   .It Em BUGS
   Extant bugs should be described in this section.
   .
   .It Em SECURITY CONSIDERATIONS
   Documents any security precautions that operators should consider.
   .
 .El  .El
 .  .
 .  .
Line 493  All macros have bodies; some
Line 683  All macros have bodies; some
 don't have heads; only one  don't have heads; only one
 .Po  .Po
 .Sx \&It Fl column  .Sx \&It Fl column
 .Pc  .Pc
 has multiple heads.  has multiple heads.
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB  \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
Line 676  then the macro accepts an arbitrary number of argument
Line 866  then the macro accepts an arbitrary number of argument
 .It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    >0, <3  .It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    >0, <3
 .It Sx \&br  Ta    \&No     Ta    \&No     Ta    0  .It Sx \&br  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1  .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1
 .El  .El
 .  .
 .  .
 .Sh REFERENCE  .Sh REFERENCE
Line 710  this macro is not implemented in
Line 900  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 syntax for  block.  This should follow the reduced or canonical form syntax
   described in
 .Sx Dates .  .Sx Dates .
 Canonical or non-canonical form is not necessary since publications are  
 often referenced only by year, or month and year.  
 .  .
 .Ss \&%I  .Ss \&%I
 Publisher or issuer name of an  Publisher or issuer name of an
Line 759  block.  This macro may also be used in a non-bibliogra
Line 948  block.  This macro may also be used in a non-bibliogra
 when referring to article titles.  when referring to article titles.
 .  .
 .Ss \&%U  .Ss \&%U
 URI of current document.  URI of reference document.
 .  .
 .Ss \&%V  .Ss \&%V
 Volume number of an  Volume number of an
Line 837  a function:
Line 1026  a function:
 .Ed  .Ed
 .  .
 .Ss \&Aq  .Ss \&Aq
 Encloses its arguments in angled brackets.  Encloses its arguments in angled brackets.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent
Line 884  Note that these parameters do not begin with a hyphen.
Line 1073  Note that these parameters do not begin with a hyphen.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.At  \&.At
 \&.At V.1  \&.At V.1
 .Ed  .Ed
 .Pp  .Pp
Line 985  and
Line 1174  and
 .Ss \&Bf  .Ss \&Bf
 .Ss \&Bk  .Ss \&Bk
 .Ss \&Bl  .Ss \&Bl
 .  .\" Begins a list composed of one or more list entries.  A list entry is
   .\" specified by the
   .\" .Sx \&It
   .\" macro, which consists of a head and optional body.  By default, a list
   .\" is preceded by a blank line.  A list must specify one of the following
   .\" list types:
   .\" .Bl -tag -width 12n
   .\" .It Fl bullet
   .\" A list offset by a bullet.  The head of list entries must be empty.
   .\" List entry bodies are justified after the bullet.
   .\" .It Fl column
   .\" A columnated list.  The number of columns is specified as arguments to
   .\" the
   .\" .Sx \&Bl
   .\" macro (the deprecated form of following the invocation of
   .\" .Fl column
   .\" is also accepted).  Arguments dictate the width of columns specified in
   .\" list entries.  List entry bodies must be left empty.  Columns specified
   .\" in the list entry head are justified to their position in the sequence
   .\" of columns.
   .\" .It Fl dash
   .\" A list offset by a dash (hyphen).  The head of list entries must be
   .\" empty.  List entry bodies are justified past the dash.
   .\" .It Fl diag
   .\" Like
   .\" .Fl inset
   .\" lists, but with additional formatting to the head.
   .\" .It Fl enum
   .\" A list offset by a number indicating list entry position.  The head of
   .\" list entries must be empty.  List entry bodies are justified past the
   .\" enumeration.
   .\" .It Fl hang
   .\" Like
   .\" .Fl tag ,
   .\" but instead of list bodies justifying to the head on the first line,
   .\" they trail the head text.
   .\" .It Fl hyphen
   .\" Synonym for
   .\" .Fl dash .
   .\" .It Fl inset
   .\" Like
   .\" .Fl tag ,
   .\" but list entry bodies aren't justified.
   .\" .It Fl item
   .\" An un-justified list.  This produces blocks of text.
   .\" .It Fl ohang
   .\" List bodies are placed on the line following the head.
   .\" .It Fl tag
   .\" A list offset by list entry heads.  List entry bodies are justified
   .\" after the head.
   .\" .El
   .\" .Pp
   .\" More...
   .\" .
 .Ss \&Bo  .Ss \&Bo
 Begins a block enclosed by square brackets.  Does not have any head  Begins a block enclosed by square brackets.  Does not have any head
 arguments.  arguments.
Line 1000  See also
Line 1242  See also
 .Sx \&Bq .  .Sx \&Bq .
 .  .
 .Ss \&Bq  .Ss \&Bq
 Encloses its arguments in square brackets.  Encloses its arguments in square brackets.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent
Line 1147  manual.  Its calling syntax is as follows:
Line 1389  manual.  Its calling syntax is as follows:
 .Pp  .Pp
 .D1 \. Ns Sx \&Dd Cm date  .D1 \. Ns Sx \&Dd Cm date
 .Pp  .Pp
 The  The
 .Cm date  .Cm date
 field may be either  field may be either
 .Ar $\&Mdocdate$ ,  .Ar $\&Mdocdate$ ,
 which signifies the current manual revision date dictated by  which signifies the current manual revision date dictated by
 .Xr cvs 1  .Xr cvs 1 ,
 or instead a valid canonical date as specified by  or instead a valid canonical date as specified by
 .Sx Dates .  .Sx Dates .
   If a date does not conform, the current date is used instead.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent
Line 1195  See also
Line 1438  See also
 .Sx \&Dq .  .Sx \&Dq .
 .  .
 .Ss \&Dq  .Ss \&Dq
 Encloses its arguments in double quotes.  Encloses its arguments in double quotes.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent
Line 1344  See also
Line 1587  See also
 .Sx \&Er .  .Sx \&Er .
 .  .
 .Ss \&Dx  .Ss \&Dx
 Format the DragonFlyBSD version provided as an argument, or a default  Format the DragonFly BSD version provided as an argument, or a default
 value if no argument is provided.  value if no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
Line 1420  is provided.
Line 1663  is provided.
 .Ss \&Fc  .Ss \&Fc
 .Ss \&Fd  .Ss \&Fd
 .Ss \&Fl  .Ss \&Fl
   Command-line flag.  Used when listing arguments to command-line
   utilities.  Prints a fixed-width hyphen
   .Sq \-
   before each delimited argument.  If no arguments are provided, a hyphen
   is still printed.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Fl a b c
   \&.Fl
   \&.Op Fl o Ns Ar file
   .Ed
   .Pp
   See also
   .Sx \&Cm .
   .
 .Ss \&Fn  .Ss \&Fn
 .Ss \&Fo  .Ss \&Fo
 .Ss \&Fr  .Ss \&Fr
Line 1451  and
Line 1710  and
 .Ss \&Lb  .Ss \&Lb
 .Ss \&Li  .Ss \&Li
 .Ss \&Lk  .Ss \&Lk
   Format a hyperlink.  The calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Lk Cm uri Op Cm name
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Lk http://bsd.lv "The BSD.lv Project"
   \&.Lk http://bsd.lv
   .Ed
   .Pp
   See also
   .Sx \&Mt .
   .
 .Ss \&Lp  .Ss \&Lp
 .Ss \&Ms  .Ss \&Ms
 .Ss \&Mt  .Ss \&Mt
Line 1641  file re-write
Line 1913  file re-write
 .Pp  .Pp
 .Bl -dash -compact  .Bl -dash -compact
 .It  .It
   The comment syntax
   .Sq \e."
   is no longer accepted.
   .It
   In
   .Xr groff 1 ,
   the
   .Sx \&Pa
   macro does not format its arguments when used in the FILES section under
   certain list types.  This irregular behaviour has been discontinued.
   .It
   Historic
   .Xr groff 1
   does not print a dash for empty
   .Sx \&Fl
   arguments.  This behaviour has been discontinued.
   .It
   .Xr groff 1
   behaves strangely (even between versions) when specifying
   .Sq \ef
   escapes within line-macro scopes.  These aberrations have been
   normalised.
   .It
 Negative scaling units are now truncated to zero instead of creating  Negative scaling units are now truncated to zero instead of creating
 interesting conditions, such as with  interesting conditions, such as with
 .Sq \&sp -1i .  .Sx \&sp
   .Fl 1i .
 Furthermore, the  Furthermore, the
 .Sq f  .Sq f
 scaling unit, while accepted, is rendered as the default unit.  scaling unit, while accepted, is rendered as the default unit.
Line 1653  standalone double-quote in formatted output.  This idi
Line 1949  standalone double-quote in formatted output.  This idi
 behaviour is no longer applicable.  behaviour is no longer applicable.
 .It  .It
 Display types  Display types
 .Sx \&Bd Fl center  .Sx \&Bd
   .Fl center
 and  and
 .Fl right  .Fl right
 are aliases for  are aliases for
Line 1683  made historic groff
Line 1980  made historic groff
 .Qq go orbital  .Qq go orbital
 but is a proper delimiter in this implementation.  but is a proper delimiter in this implementation.
 .It  .It
 .Sx \&It Fl nested  .Sx \&It
   .Fl nested
 is assumed for all lists (it wasn't in historic groff): any list may be  is assumed for all lists (it wasn't in historic groff): any list may be
 nested and  nested and
 .Fl enum  .Fl enum
Legend:
Removed from v.1.69  
changed lines
  Added in v.1.82
CVSweb