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

version 1.65, 2009/10/19 11:02:23 version 1.66, 2009/10/20 05:45:21
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 604  Author name of an
Line 687  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 708  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 698  Author name.  This macro may alternatively accepts the
Line 781  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 853  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 884  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 887  Examples:
Line 971  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 1055  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 1063  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 1079  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 1087  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 1431  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 1465  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 1477  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 1522  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 1177  Examples:
Line 1605  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.66
CVSweb