[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.79

version 1.69, 2009/10/24 05:52:13 version 1.79, 2010/01/01 13:35:30
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
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 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 .  .Sx \&Nd
 The name needs re-stating since one  macro.
 .Nm  .
 documents can be used for more than one utility or function, such as  .It Em LIBRARY
 .Xr grep 1  The name of the library containing the documented material, which is
 also being referenced as  assumed to be a function in a section 2 or 3 manual.  The syntax for
 .Xr egrep 1  this is as follows:
 and  .Bd -literal -offset indent
 .Xr fgrep 1 .  \&.Lb libarm
 .It LIBRARY  .Ed
 .It SYNOPSIS  .Pp
 .It DESCRIPTION  See
 .It IMPLEMENTATION NOTES  .Sx \&Lb
 .It EXIT STATUS  for details.
 .It RETURN VALUES  .
 .It ENVIRONMENT  .It Em SYNOPSIS
 .It FILES  Documents the utility invocation syntax, function call syntax, or device
 .It EXAMPLES  configuration.
 .It DIAGNOSTICS  .Pp
 .It ERRORS  For the first, utilities (sections 1, 6, and 8), this is
 .It SEE ALSO  generally structured as follows:
 .It STANDARDS  .Bd -literal -offset indent
 .It HISTORY  \&.Nm foo
 .It AUTHORS  \&.Op Fl v
 .It CAVEATS  \&.Op Fl o Ar file
 .It BUGS  \&.Op Ar
 .It SECURITY CONSIDERATIONS  \&.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 .
   .
   .It Em DESCRIPTION
   This expands upon the brief, one-line description in
   .Em NAME .
   It usually contains a break-down of the options (if documenting a
   command), such as:
   .Bd -literal -offset indent
   The arguments are as follows:
   \&.Bl \-tag \-width Ds
   \&.It Fl v
   Print verbose information.
   \&.El
   .Ed
   Manuals not documenting a command won't include the above fragment.
   .
   .It Em 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.
   .
   .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 No \-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 710  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 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 934  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 1152  The 
Line 1327  The 
 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 1344  See also
Line 1520  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 1596  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 1643  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 1846  file re-write
 .Pp  .Pp
 .Bl -dash -compact  .Bl -dash -compact
 .It  .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
   .Cm \-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 1871  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 1902  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.79
CVSweb