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

Diff for /mandoc/mdoc.7 between version 1.119 and 1.120

version 1.119, 2010/06/04 22:16:27 version 1.120, 2010/06/06 10:49:56
Line 1334  and
Line 1334  and
 .Ss \&Db  .Ss \&Db
 Start a debugging context.  Start a debugging context.
 This macro is parsed, but generally ignored.  This macro is parsed, but generally ignored.
 Its calling syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 \. Ns Sx \&Db Cm on | off  .D1 Pf \. Sx \&Db Cm on | off
 .Ss \&Dc  .Ss \&Dc
 Closes a  Closes a
 .Sx \&Do  .Sx \&Do
Line 1346  Document date.
Line 1346  Document date.
 This is the mandatory first macro of any  This is the mandatory first macro of any
 .Nm  .Nm
 manual.  manual.
 Its calling syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 \. Ns Sx \&Dd Cm date  .D1 Pf \. Sx \&Dd Cm date
 .Pp  .Pp
 The  The
 .Cm date  .Cm date
Line 1407  Document title.
Line 1407  Document title.
 This is the mandatory second macro of any  This is the mandatory second macro of any
 .Nm  .Nm
 file.  file.
 Its calling syntax is as follows:  Its syntax is as follows:
   .Bd -ragged -offset indent
   .Pf \. Sx \&Dt
   .Oo
   .Cm title
   .Oo
   .Cm section
   .Op Cm volume | arch
   .Oc
   .Oc
   .Ed
 .Pp  .Pp
 .D1 \. Ns Sx \&Dt Op Cm title Op Cm section Op Cm volume | arch  
 .Pp  
 Its arguments are as follows:  Its arguments are as follows:
 .Bl -tag -width Ds -offset Ds  .Bl -tag -width Ds -offset Ds
 .It Cm title  .It Cm title
Line 1611  is not provided, the document's name as stipulated in
Line 1619  is not provided, the document's name as stipulated in
 is provided.  is provided.
 .Ss \&Fa  .Ss \&Fa
 Function argument.  Function argument.
   Its syntax is as follows:
   .Bd -ragged -offset indent
   .Pf \. Sx \&Fa
   .Op Cm argtype
   .Cm argname
   .Ed
   .Pp
 This may be invoked for names with or without the corresponding type.  This may be invoked for names with or without the corresponding type.
 It is also used to specify the field name of a structure.  It is also used to specify the field name of a structure.
 Most often, the  Most often, the
 .Sx \&Fa  .Sx \&Fa
 macro is used in the  macro is used in the
 .Em SYNOPSIS  .Em SYNOPSIS
   within
   .Sx \&Fo
 section when documenting multi-line function prototypes.  section when documenting multi-line function prototypes.
 If invoked with multiple arguments, the arguments are separated by a  If invoked with multiple arguments, the arguments are separated by a
 comma.  comma.
Line 1628  Examples:
Line 1645  Examples:
 .D1 \&.Fa \(dqconst char *p\(dq  .D1 \&.Fa \(dqconst char *p\(dq
 .D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq  .D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
 .D1 \&.Fa foo  .D1 \&.Fa foo
   .Pp
   See also
   .Sx \&Fo .
 .Ss \&Fc  .Ss \&Fc
 .Ss \&Fd  .Ss \&Fd
 Historically used to document include files.  Historically used to document include files.
Line 1657  See also
Line 1677  See also
 .Sx \&Cm .  .Sx \&Cm .
 .Ss \&Fn  .Ss \&Fn
 A function name.  A function name.
 Its calling syntax is as follows:  Its syntax is as follows:
 .Bd -ragged -offset indent  .Bd -ragged -offset indent
 .Pf \. Ns Sx \&Fn  .Pf \. Ns Sx \&Fn
 .Op Cm functype  .Op Cm functype
 .Cm funcname  .Cm funcname
 .Op Oo Cm argtype Oc Cm argname  .Op Oo Cm argtype Oc Cm argname
 .Ed  .Ed
   .Pp
 If invoked in the  If invoked in the
 .Em SYNOPSIS  .Em SYNOPSIS
 section, vertical space is asserted before and after the macro.  section, vertical space is asserted before and after the macro.
Line 1673  If no arguments are specified, blank parenthesis are o
Line 1694  If no arguments are specified, blank parenthesis are o
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Fn "int funcname" "int arg0" "int arg1"  .D1 \&.Fn "int funcname" "int arg0" "int arg1"
 .D1 \&.Fn funcname  
 .D1 \&.Fn funcname "int arg0"  .D1 \&.Fn funcname "int arg0"
 .D1 \&.Fn funcname arg0  .D1 \&.Fn funcname arg0
   .Bd -literal -offset indent -compact
   \&.Ft functype
   \&.Fn funcname
   .Ed
 .Pp  .Pp
 See also  See also
 .Sx \&Fa ,  .Sx \&Fa ,
Line 1684  See also
Line 1708  See also
 and  and
 .Sx \&Ft .  .Sx \&Ft .
 .Ss \&Fo  .Ss \&Fo
   Begin a function block.
   This is a multi-line version of
   .Sx \&Fn .
   Its syntax is as follows:
   .Pp
   .D1 Pf \. Sx \&Fo Cm funcname
   .Pp
   Invocations usually occur in the following context:
   .Bd -ragged -offset indent
   .Pf \. Sx \&Ft Cm functype
   .br
   .Pf \. Sx \&Fo Cm funcname
   .br
   .Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname
   .br
   \.\.\.
   .br
   .Pf \. Sx \&Fc
   .Ed
   .Pp
   In the
   .Em SYNOPSIS
   section, a
   .Sx \&Fo
   block is surrounded by vertical space unless
   .Sx \&Ft
   is the prior macro, in which case it is preceded by only a newline.
   .Pp
   A
   .Sx \&Fo
   scope is closed by
   .Pp
   See also
   .Sx \&Fa ,
   .Sx \&Fc ,
   and
   .Sx \&Fn .
   .Sx \&Fc .
 .Ss \&Fr  .Ss \&Fr
 .Ss \&Ft  .Ss \&Ft
   A function type.
   Its syntax is as follows:
   .Pp
   .D1 Pf \. Sx \&Ft Cm functype
   .Pp
   If invoked before a
   .Sx \&Fo
   or
   .Sx \&Fn
   in the
   .Em SYNOPSIS
   section, a line-break will follow.
   Furthermore, if invoked in the
   .Em SYNOPSIS
   section, it will assert vertical space prior to its arguments.
   .Pp
   Examples:
   .D1 \&.Ft int
   .Bd -literal -offset indent -compact
   \&.Ft functype
   \&.Fn funcname
   .Ed
   .Pp
   See also
   .Sx \&Fo ,
   .Sx \&Fc ,
   and
   .Sx \&Fn .
 .Ss \&Fx  .Ss \&Fx
 Format the FreeBSD version provided as an argument, or a default value  Format the FreeBSD version provided as an argument, or a default value
 if no argument is provided.  if no argument is provided.
Line 1720  In all other invocations, only angled braces will encl
Line 1810  In all other invocations, only angled braces will encl
 Examples  Examples
 .D1 \&.In sys/types  .D1 \&.In sys/types
 .Ss \&It  .Ss \&It
 A list item.  The syntax of this macro depends on the list type.  A list item.
   The syntax of this macro depends on the list type.
 .Pp  .Pp
 Lists  Lists
 of type  of type
Line 1729  of type
Line 1820  of type
 .Fl inset ,  .Fl inset ,
 and  and
 .Fl diag  .Fl diag
 have the following calling syntax:  have the following syntax:
 .Pp  .Pp
 .D1 \. Ns Sx \&It Cm args  .D1 Pf \. Sx \&It Cm args
 .Pp  .Pp
 Lists of type  Lists of type
 .Fl bullet ,  .Fl bullet ,
Line 1740  Lists of type
Line 1831  Lists of type
 .Fl hyphen  .Fl hyphen
 and  and
 .Fl item  .Fl item
 have the following calling syntax:  have the following syntax:
 .Pp  .Pp
 .D1 \. Ns Sx \&It  .D1 Pf \. Sx \&It
 .Pp  .Pp
 with subsequent lines interpreted within the scope of the  with subsequent lines interpreted within the scope of the
 .Sx \&It  .Sx \&It
Line 1753  or another
Line 1844  or another
 .Pp  .Pp
 The  The
 .Fl tag  .Fl tag
 list has syntax  list has the following syntax:
 .Pp  .Pp
 .D1 \. Ns Sx \&It Op Cm args  .D1 Pf \. Sx \&It Op Cm args
 .Pp  .Pp
 with subsequent lines interpreted as with  Subsequent lines are interpreted as with
 .Fl bullet  .Fl bullet
 and family.  and family.
 The line arguments correspond to the list's left-hand side; body  The line arguments correspond to the list's left-hand side; body
Line 1766  arguments correspond to the list's contents.
Line 1857  arguments correspond to the list's contents.
 The  The
 .Fl column  .Fl column
 list is the most complicated.  list is the most complicated.
 Its syntax is  Its syntax is as follows:
 .Pp  .Pp
 .D1 \. Ns Sx \&It Op Cm args  .D1 Pf \. Sx \&It Op Cm args
 .Pp  .Pp
 where  The
 .Cm args  .Cm args
 are phrases, a mix of macros and text corresponding to a line column,  are phrases, a mix of macros and text corresponding to a line column,
 delimited by tabs or the special  delimited by tabs or the special
Line 1802  See also
Line 1893  See also
 .Sx \&Bl .  .Sx \&Bl .
 .Ss \&Lb  .Ss \&Lb
 Specify a library.  Specify a library.
 The calling syntax is as follows:  The syntax is as follows:
 .Pp  .Pp
 .D1 \. Ns Sx \&Lb Cm library  .D1 Pf \. Sx \&Lb Cm library
 .Pp  .Pp
 The  The
 .Cm library  .Cm library
Line 1826  Examples:
Line 1917  Examples:
 .Ss \&Li  .Ss \&Li
 .Ss \&Lk  .Ss \&Lk
 Format a hyperlink.  Format a hyperlink.
 The calling syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 \. Ns 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 "The BSD.lv Project"
Line 1842  See also
Line 1933  See also
 Format a  Format a
 .Qq mailto:  .Qq mailto:
 hyperlink.  hyperlink.
 The calling syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 \. Ns Sx \&Mt Cm address  .D1 Pf \. Sx \&Mt Cm address
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Mt discuss@manpages.bsd.lv  .D1 \&.Mt discuss@manpages.bsd.lv
Line 1877  Document operating system version.
Line 1968  Document operating system version.
 This is the mandatory third macro of  This is the mandatory third macro of
 any  any
 .Nm  .Nm
 file.  Its calling syntax is as follows:  file.
   Its syntax is as follows:
 .Pp  .Pp
 .D1 \. Ns Sx \&Os Op Cm system  .D1 Pf \. Sx \&Os Op Cm system
 .Pp  .Pp
 The optional  The optional
 .Cm system  .Cm system
Line 1951  The block macro may only contain
Line 2043  The block macro may only contain
 .Sx \&%Q ,  .Sx \&%Q ,
 .Sx \&%R ,  .Sx \&%R ,
 .Sx \&%T ,  .Sx \&%T ,
   .Sx \&%U ,
 and  and
 .Sx \&%V  .Sx \&%V
 child macros (at least one must be specified).  child macros (at least one must be specified).
Line 2036  since this limit has been lifted, the macro has been d
Line 2129  since this limit has been lifted, the macro has been d
 .Ss \&Xr  .Ss \&Xr
 Link to another manual  Link to another manual
 .Pq Qq cross-reference .  .Pq Qq cross-reference .
 Its calling syntax is  Its syntax is as follows:
 .Pp  .Pp
 .D1 \. Ns Sx \&Xr Cm name section  .D1 Pf \. Sx \&Xr Cm name section
 .Pp  .Pp
 The  The
 .Cm name  .Cm name
Line 2075  Heirloom troff, the other significant troff implementa
Line 2168  Heirloom troff, the other significant troff implementa
 .Pp  .Pp
 .Bl -dash -compact  .Bl -dash -compact
 .It  .It
   groff behaves inconsistently when encountering
   .Pf non- Sx \&Fa
   children of
   .Sx \&Fo
   regarding spacing between arguments.
   In mandoc, this is not the case: each argument is consistently followed
   by a single space and the trailing
   .Sq \&)
   suppresses prior spacing.
   .It
   groff behaves inconsistently when encountering
   .Sx \&Ft
   and
   .Sx \&Fn
   in the
   .Em SYNOPSIS :
   at times newline(s) are suppressed dependong on whether a prior
   .Sx \&Fn
   has been invoked.
   In mandoc, this is not the case.
   See
   .Sx \&Ft
   and
   .Sx \&Fn
   for the normalised behaviour.
   .It
 Historic groff does not break before an  Historic groff does not break before an
 .Sx \&Fn  .Sx \&Fn
 when not invoked as the line macro in the  when not invoked as the line macro in the
Line 2162  Some manuals use
Line 2281  Some manuals use
 incorrectly by following it with a reserved character and expecting the  incorrectly by following it with a reserved character and expecting the
 delimiter to render.  delimiter to render.
 This is not supported in mandoc.  This is not supported in mandoc.
 .It  
 In groff, the  
 .Sx \&Fo  
 macro only produces the first parameter.  
 This is not the case in mandoc.  
 .It  .It
 In groff, the  In groff, the
 .Sx \&Cd ,  .Sx \&Cd ,

Legend:
Removed from v.1.119  
changed lines
  Added in v.1.120

CVSweb