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

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

version 1.65, 2009/10/19 11:02:23 version 1.69, 2009/10/24 05:52:13
Line 210  considered literal text.  Thus, the following produces
Line 210  considered literal text.  Thus, the following produces
 In free-form mode, quotes are regarded as opaque text.  In free-form mode, quotes are regarded as opaque text.
 .  .
 .Ss Dates  .Ss Dates
 TODO.  There are several macros in
   .Nm
   that require a date argument.  The
   .Em canonical form
   for dates is the American format:
   .Pp
   .D1 Cm Month Day , Year
   .Pp
   The
   .Cm Day
   value is an optionally zero-padded numeral.  The
   .Cm Month
   value is the full month name.  The
   .Cm Year
   value is the full four-digit year.
   .Pp
   The
   .Em non-canonical form
   is the same as the canonical form, but without the comma between the
   .Cm Day
   and
   .Cm Year
   field.
   .Pp
   Lastly,
   .Em reduced form
   dates range from only a
   .Cm Year
   to the full canonical or non-canonical form.
   .Pp
   Some examples of valid dates follow:
   .Pp
   .D1 "May, 2009" Pq reduced form
   .D1 "2009" Pq reduced 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 267  is necessarily non-portable across output media.  See
Line 302  is necessarily non-portable across output media.  See
 .  .
 .  .
 .Sh MANUAL STRUCTURE  .Sh MANUAL STRUCTURE
 Each  A well-formed
 .Nm  .Nm
 document must begin with a document prologue, containing, in order,  document consists of a document prologue followed by one or more
   sections.
   .Pp
   The prologue, which consists of (in order) the
 .Sx \&Dd ,  .Sx \&Dd ,
 .Sx \&Dt ,  .Sx \&Dt ,
 and  and
 .Sx \&Os ,  .Sx \&Os
 then the NAME section containing at least one  macros, is required for every document.
   .Pp
   The first section (sections are denoted by
   .Sx \&Sh )
   must be the NAME section, consisting of at least one
 .Sx \&Nm  .Sx \&Nm
 followed by  followed by
 .Sx \&Nd :  .Sx \&Nd .
   .Pp
   Following that, convention dictates specifying at least the SYNOPSIS and
   DESCRIPTION sections, although this varies between manual sections.
   .Pp
   The following is a well-formed skeleton
   .Nm
   file:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Dd $\&Mdocdate$  \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7  \&.Dt mdoc 7
Line 320  utility processes files ...
Line 369  utility processes files ...
 \&.\e\*q .Sh BUGS  \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS  \&.\e\*q .Sh SECURITY CONSIDERATIONS
 .Ed  .Ed
 .  
 .Pp  .Pp
 Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,  The sections in a
 but non-compulsory.  .Nm
   document are conventionally ordered as they appear above.  Sections
   should be composed as follows:
   .Bl -tag -width Ds -offset Ds
   .It NAME
   Must contain at least one
   .Sx \&Nm
   followed by
   .Sx \&Nd .
   The name needs re-stating since one
   .Nm
   documents can be used for more than one utility or function, such as
   .Xr grep 1
   also being referenced as
   .Xr egrep 1
   and
   .Xr fgrep 1 .
   .It LIBRARY
   .It SYNOPSIS
   .It DESCRIPTION
   .It IMPLEMENTATION NOTES
   .It EXIT STATUS
   .It RETURN VALUES
   .It ENVIRONMENT
   .It FILES
   .It EXAMPLES
   .It DIAGNOSTICS
   .It ERRORS
   .It SEE ALSO
   .It STANDARDS
   .It HISTORY
   .It AUTHORS
   .It CAVEATS
   .It BUGS
   .It SECURITY CONSIDERATIONS
   .El
 .  .
 .  .
 .Sh MACRO SYNTAX  .Sh MACRO SYNTAX
Line 528  then the macro accepts an arbitrary number of argument
Line 611  then the macro accepts an arbitrary number of argument
 .It Sx \&%N  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%N  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%O  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%O  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%P  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%P  Ta    \&No     Ta    \&No     Ta    >0
   .It Sx \&%Q  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%R  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%R  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%T  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%T  Ta    \&No     Ta    \&No     Ta    >0
   .It Sx \&%U  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%V  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%V  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&Ad  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Ad  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&An  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&An  Ta    Yes      Ta    Yes      Ta    n
Line 604  Author name of an
Line 689  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.  line.  Author names should be ordered with full or abbreviated
 .Pp  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
Line 627  this macro is not implemented in
Line 710  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 canonical syntax for  block.  This should follow the reduced syntax for
 .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 673  Article title of an
Line 758  Article title of an
 block.  This macro may also be used in a non-bibliographical context  block.  This macro may also be used in a non-bibliographical context
 when referring to article titles.  when referring to article titles.
 .  .
   .Ss \&%U
   URI of current document.
   .
 .Ss \&%V  .Ss \&%V
 Volume number of an  Volume number of an
 .Sx \&Rs  .Sx \&Rs
Line 698  Author name.  This macro may alternatively accepts the
Line 786  Author name.  This macro may alternatively accepts the
 arguments, although these may not be specified along with a parameter:  arguments, although these may not be specified along with a parameter:
 .Bl -tag -width 12n -offset indent  .Bl -tag -width 12n -offset indent
 .It Fl split  .It Fl split
 Renders a line break is rendered before each author listing.  Renders a line break before each author listing.
 .It Fl nosplit  .It Fl nosplit
 The opposite of  The opposite of
 .Fl split .  .Fl split .
Line 770  See also
Line 858  See also
 .Sx \&Ao .  .Sx \&Ao .
 .  .
 .Ss \&Ar  .Ss \&Ar
 Command arguments.  If an argument is not provided, the strings  Command arguments.  If an argument is not provided, the string
 .Dq file ...  .Dq file ...
 are used as a default.  is used as a default.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent
Line 801  Examples:
Line 889  Examples:
 .Ed  .Ed
 .Pp  .Pp
 See also  See also
 .Sx \&Bx ,  
 .Sx \&Bsx ,  .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
 .Sx \&Fx ,  .Sx \&Fx ,
 .Sx \&Nx ,  .Sx \&Nx ,
 .Sx \&Ox ,  .Sx \&Ox ,
Line 859  which aligns around an imagined centre axis.
Line 948  which aligns around an imagined centre axis.
 .It  .It
 As a precalculated width for a named macro.  The most popular is the  As a precalculated width for a named macro.  The most popular is the
 imaginary macro  imaginary macro
 .Ar Ds ,  .Ar \&Ds ,
 which resolves to  which resolves to
 .Ar 6n .  .Ar 6n .
 .It  .It
Line 887  Examples:
Line 976  Examples:
    Hello       world.     Hello       world.
 \&.Ed  \&.Ed
 .Ed  .Ed
   .Pp
   See also
   .Sx \&D1
   and
   .Sx \&Dl .
 .  .
 .Ss \&Bf  .Ss \&Bf
 .Ss \&Bk  .Ss \&Bk
Line 966  Examples:
Line 1060  Examples:
 See also  See also
 .Sx \&At ,  .Sx \&At ,
 .Sx \&Bx ,  .Sx \&Bx ,
   .Sx \&Dx ,
 .Sx \&Fx ,  .Sx \&Fx ,
 .Sx \&Nx ,  .Sx \&Nx ,
 .Sx \&Ox ,  .Sx \&Ox ,
Line 973  and
Line 1068  and
 .Sx \&Ux .  .Sx \&Ux .
 .  .
 .Ss \&Bt  .Ss \&Bt
   Prints
   .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 986  Examples:
Line 1084  Examples:
 See also  See also
 .Sx \&At ,  .Sx \&At ,
 .Sx \&Bsx ,  .Sx \&Bsx ,
   .Sx \&Dx ,
 .Sx \&Fx ,  .Sx \&Fx ,
 .Sx \&Nx ,  .Sx \&Nx ,
 .Sx \&Ox ,  .Sx \&Ox ,
Line 993  and
Line 1092  and
 .Sx \&Ux .  .Sx \&Ux .
 .  .
 .Ss \&Cd  .Ss \&Cd
   Configuration declaration (suggested for use only in section four
   manuals).  This denotes strings accepted by
   .Xr config 8 .
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Cd device le0 at scode?
   .Ed
   .Pp
   .Em Remarks :
   this macro is commonly abused by using quoted literals to retain
   white-space and align consecutive
   .Sx \&Cd
   declarations.  This practise is discouraged.
   .
 .Ss \&Cm  .Ss \&Cm
   Command modifiers.  Useful when specifying configuration options or
   keys.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Cm ControlPath
   \&.Cm ControlMaster
   .Ed
   .Pp
   See also
   .Sx \&Fl .
   .
 .Ss \&D1  .Ss \&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.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.D1 Fl abcdefgh
   .Ed
   .Pp
   See also
   .Sx \&Bd
   and
   .Sx \&Dl .
   .
 .Ss \&Db  .Ss \&Db
 .Ss \&Dc  .Ss \&Dc
   Closes a
   .Sx \&Do
   block.  Does not have any tail arguments.
   .
 .Ss \&Dd  .Ss \&Dd
   Document date.  This is the mandatory first macro of any
   .Nm
   manual.  Its calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Dd Cm date
   .Pp
   The
   .Cm date
   field may be either
   .Ar $\&Mdocdate$ ,
   which signifies the current manual revision date dictated by
   .Xr cvs 1
   or instead a valid canonical date as specified by
   .Sx Dates .
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Dd $\&Mdocdate$
   \&.Dd $\&Mdocdate: July 21 2007$
   \&.Dd July 21, 2007
   .Ed
   .Pp
   See also
   .Sx \&Dt
   and
   .Sx \&Os .
   .
 .Ss \&Dl  .Ss \&Dl
   One-line intended display.  This is formatted as literal text and is
   useful for commands and invocations.  It is followed by a newline.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Dl % mandoc mdoc.7 | less
   .Ed
   .Pp
   See also
   .Sx \&Bd
   and
   .Sx \&D1 .
   .
 .Ss \&Do  .Ss \&Do
   Begins a block enclosed by double quotes.  Does not have any head
   arguments.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.D1 Do April is the cruellest month Dc \e(em T.S. Eliot
   .Ed
   .Pp
   See also
   .Sx \&Dq .
   .
 .Ss \&Dq  .Ss \&Dq
   Encloses its arguments in double quotes.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Dq April is the cruellest month
   \e(em T.S. Eliot
   .Ed
   .Pp
   See also
   .Sx \&Do .
   .
 .Ss \&Dt  .Ss \&Dt
   Document title.  This is the mandatory second macro of any
   .Nm
   file.  Its calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch
   .Pp
   Its arguments are as follows:
   .Bl -tag -width Ds -offset Ds
   .It Cm title
   The document's title (name).  This should be capitalised and is
   required.
   .It Cm section
   The manual section.  This may be one of
   .Ar 1
   .Pq utilities ,
   .Ar 2
   .Pq system calls ,
   .Ar 3
   .Pq libraries ,
   .Ar 3p
   .Pq Perl libraries ,
   .Ar 4
   .Pq devices ,
   .Ar 5
   .Pq file formats ,
   .Ar 6
   .Pq games ,
   .Ar 7
   .Pq miscellaneous ,
   .Ar 8
   .Pq system utilities ,
   .Ar 9
   .Pq kernel functions ,
   .Ar X11
   .Pq X Window System ,
   .Ar X11R6
   .Pq X Window System ,
   .Ar unass
   .Pq unassociated ,
   .Ar local
   .Pq local system ,
   .Ar draft
   .Pq draft manual ,
   or
   .Ar paper
   .Pq paper .
   It is also required and should correspond to the manual's filename
   suffix.
   .It Cm volume
   This overrides the volume inferred from
   .Ar section .
   This field is optional, and if specified, must be one of
   .Ar USD
   .Pq users' supplementary documents ,
   .Ar PS1
   .Pq programmers' supplementary documents ,
   .Ar AMD
   .Pq administrators' supplementary documents ,
   .Ar SMM
   .Pq system managers' manuals ,
   .Ar URM
   .Pq users' reference manuals ,
   .Ar PRM
   .Pq programmers' reference manuals ,
   .Ar KM
   .Pq kernel manuals ,
   .Ar IND
   .Pq master index ,
   .Ar MMI
   .Pq master index ,
   .Ar LOCAL
   .Pq local manuals ,
   .Ar LOC
   .Pq local manuals ,
   or
   .Ar CON
   .Pq contributed manuals .
   .It Cm arch
   This specifies a specific relevant architecture.  If
   .Cm 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
   .Ar alpha ,
   .Ar amd64 ,
   .Ar amiga ,
   .Ar arc ,
   .Ar arm ,
   .Ar armish ,
   .Ar aviion ,
   .Ar hp300 ,
   .Ar hppa ,
   .Ar hppa64 ,
   .Ar i386 ,
   .Ar landisk ,
   .Ar luna88k ,
   .Ar mac68k ,
   .Ar macppc ,
   .Ar mvme68k ,
   .Ar mvme88k ,
   .Ar mvmeppc ,
   .Ar pmax ,
   .Ar sgi ,
   .Ar socppc ,
   .Ar sparc ,
   .Ar sparc64 ,
   .Ar sun3 ,
   .Ar vax ,
   or
   .Ar zaurus .
   .El
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Dt FOO 1
   \&.Dt FOO 4 KM
   \&.Dt FOO 9 i386
   \&.Dt FOO 9 KM i386
   .Ed
   .Pp
   See also
   .Sx \&Dd
   and
   .Sx \&Os .
   .
 .Ss \&Dv  .Ss \&Dv
   Defined variables such as preprocessor constants.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Dv BUFSIZ
   \&.Dv STDOUT_FILENO
   .Ed
   .Pp
   See also
   .Sx \&Er .
   .
 .Ss \&Dx  .Ss \&Dx
   Format the DragonFlyBSD version provided as an argument, or a default
   value if no argument is provided.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Dx 2.4.1
   \&.Dx
   .Ed
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   .Sx \&Ox ,
   and
   .Sx \&Ux .
   .
 .Ss \&Ec  .Ss \&Ec
 .Ss \&Ed  .Ss \&Ed
 .Ss \&Ef  .Ss \&Ef
 .Ss \&Ek  .Ss \&Ek
 .Ss \&El  .Ss \&El
 .Ss \&Em  .Ss \&Em
   Denotes text that should be emphasised.  Note that this is a
   presentation term and should not be used for stylistically decorating
   technical terms.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Ed Warnings!
   \&.Ed Remarks :
   .Ed
   .
 .Ss \&En  .Ss \&En
 .Ss \&Eo  .Ss \&Eo
 .Ss \&Er  .Ss \&Er
   Error constants (suggested for use only in section two manuals).
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Er EPERM
   \&.Er ENOENT
   .Ed
   .Pp
   See also
   .Sx \&Dv .
   .
 .Ss \&Es  .Ss \&Es
   .
 .Ss \&Ev  .Ss \&Ev
   Environmental variables such as those specified in
   .Xr environ 7 .
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Ev DISPLAY
   \&.Ev PATH
   .Ed
   .
 .Ss \&Ex  .Ss \&Ex
   Inserts text regarding a utility's exit values.  This macro must have
   first the
   .Fl std
   argument specified, then an optional
   .Ar utility .
   If
   .Ar utility
   is not provided, the document's name as stipulated in
   .Sx \&Nm
   is provided.
 .Ss \&Fa  .Ss \&Fa
 .Ss \&Fc  .Ss \&Fc
 .Ss \&Fd  .Ss \&Fd
Line 1036  Examples:
Line 1436  Examples:
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
 .Sx \&Bx ,  
 .Sx \&Bsx ,  .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
 .Sx \&Nx ,  .Sx \&Nx ,
 .Sx \&Ox ,  .Sx \&Ox ,
 and  and
Line 1069  Examples:
Line 1470  Examples:
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
 .Sx \&Bx ,  
 .Sx \&Bsx ,  .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
 .Sx \&Fx ,  .Sx \&Fx ,
 .Sx \&Ox ,  .Sx \&Ox ,
 and  and
Line 1080  and
Line 1482  and
 .Ss \&Oo  .Ss \&Oo
 .Ss \&Op  .Ss \&Op
 .Ss \&Os  .Ss \&Os
   Document operating system version.  This is the mandatory third macro of
   any
   .Nm
   file.  Its calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Os Op Cm system
   .Pp
   The optional
   .Cm system
   parameter specifies the relevant operating system or environment.  Left
   unspecified, it defaults to the local operating system version.  This is
   the suggested form.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Os
   \&.Os KTH/CSC/TCS
   \&.Os BSD 4.3
   .Ed
   .Pp
   See also
   .Sx \&Dd
   and
   .Sx \&Dt .
   .
 .Ss \&Ot  .Ss \&Ot
   Unknown usage.
   .Pp
   .Em Remarks :
   this macro has been deprecated.
   .
 .Ss \&Ox  .Ss \&Ox
 Format the OpenBSD version provided as an argument, or a default value  Format the OpenBSD version provided as an argument, or a default value
 if no argument is provided.  if no argument is provided.
Line 1095  See also
Line 1527  See also
 .Sx \&At ,  .Sx \&At ,
 .Sx \&Bsx ,  .Sx \&Bsx ,
 .Sx \&Bx ,  .Sx \&Bx ,
   .Sx \&Dx ,
 .Sx \&Fx ,  .Sx \&Fx ,
 .Sx \&Nx ,  .Sx \&Nx ,
 and  and
Line 1119  block.  Does not have any tail arguments.
Line 1552  block.  Does not have any tail arguments.
 .Ss \&Rs  .Ss \&Rs
 Begins a bibliographic  Begins a bibliographic
 .Pq Dq reference  .Pq Dq reference
 block.  Does not have any head arguments.  The block macro and may only  block.  Does not have any head arguments.  The block macro may only
 contain  contain
 .Sx \&%A ,  .Sx \&%A ,
 .Sx \&%B ,  .Sx \&%B ,
Line 1177  Examples:
Line 1610  Examples:
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
 .Sx \&Bx ,  
 .Sx \&Bsx ,  .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
 .Sx \&Fx ,  .Sx \&Fx ,
 .Sx \&Nx ,  .Sx \&Nx ,
 and  and
Legend:
Removed from v.1.65  
changed lines
  Added in v.1.69
CVSweb