[BACK]Return to mdoc.7 CVS log [TXT][DIR] Up to [local] / src / usr.bin / mandoc

Diff for /src/usr.bin/mandoc/Attic/mdoc.7 between version 1.33 and 1.34

version 1.33, 2010/06/06 18:08:41 version 1.34, 2010/06/06 20:30:08
Line 33 
Line 33 
 .Pp  .Pp
 An  An
 .Nm  .Nm
 document follows simple rules:  lines beginning with the control  document follows simple rules: lines beginning with the control
 character  character
 .Sq \.  .Sq \.
 are parsed for macros.  Other lines are interpreted within the scope of  are parsed for macros.  Other lines are interpreted within the scope of
Line 122 
Line 122 
 A numerical representation 3, 2, or 1 (bold, italic, and Roman,  A numerical representation 3, 2, or 1 (bold, italic, and Roman,
 respectively) may be used instead.  respectively) may be used instead.
 A text decoration is valid within  A text decoration is valid within
 the current font scope only:  if a macro opens a font scope alongside  the current font scope only: if a macro opens a font scope alongside
 its own scope, such as  its own scope, such as
 .Sx \&Bf  .Sx \&Bf
 .Cm \&Sy ,  .Cm \&Sy ,
Line 343 
Line 343 
 \&.Dd $\&Mdocdate$  \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7  \&.Dt mdoc 7
 \&.Os  \&.Os
 \&.  
 \&.Sh NAME  \&.Sh NAME
 \&.Nm foo  \&.Nm foo
 \&.Nd a description goes here  \&.Nd a description goes here
 \&.\e\*q The next is for sections 2, 3, & 9 only.  \&.\e\*q The next is for sections 2, 3, & 9 only.
 \&.\e\*q .Sh LIBRARY  \&.\e\*q .Sh LIBRARY
 \&.  
 \&.Sh SYNOPSIS  \&.Sh SYNOPSIS
 \&.Nm foo  \&.Nm foo
 \&.Op Fl options  \&.Op Fl options
 \&.Ar  \&.Ar
 \&.  
 \&.Sh DESCRIPTION  \&.Sh DESCRIPTION
 The  The
 \&.Nm  \&.Nm
Line 1139 
Line 1136 
 These dictate the width of columns either as  These dictate the width of columns either as
 .Sx Scaling Widths  .Sx Scaling Widths
 or literal text.  or literal text.
 List entry bodies must be left empty.  If the initial macro of a
 Column bodies have the following syntax:  .Fl column
 .Pp  list is not an
 .D1 .It col1 <TAB> ... coln  .Sx \&It ,
 .D1 .It col1 Ta ... coln  an
 .D1 .It col1 <TAB> col2 Ta coln  .Sx \&It
 .Pp  context spanning each line is implied until an
 where columns may be separated by tabs, the literal string  .Sx \&It
 .Qq Ta ,  line macro is encountered, at which point list bodies are interpreted as
 or a mixture of both.  described in the
 These are equivalent except that quoted sections propogate over tabs,  .Sx \&It
 for example,  documentation.
 .Pp  
 .D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;  
 .Pp  
 will preserve the semicolon whitespace except for the last.  
 .It Fl dash  .It Fl dash
 A list offset by a dash (hyphen).  A list offset by a dash (hyphen).
 The head of list entries must be empty.  The head of list entries must be empty.
Line 1209 
Line 1202 
 .Fl width  .Fl width
 argument.  argument.
 .El  .El
   .Pp
   See also
   .Sx \&It .
 .Ss \&Bo  .Ss \&Bo
 Begins a block enclosed by square brackets.  Begins a block enclosed by square brackets.
 Does not have any head arguments.  Does not have any head arguments.
Line 1336 
Line 1332 
 and  and
 .Sx \&Dl .  .Sx \&Dl .
 .Ss \&Db  .Ss \&Db
   Start a debugging context.
   This macro is parsed, but generally ignored.
   Its syntax is as follows:
   .Pp
   .D1 Pf \. Sx \&Db Cm on | off
 .Ss \&Dc  .Ss \&Dc
 Closes a  Closes a
 .Sx \&Do  .Sx \&Do
Line 1345 
Line 1346 
 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 1406 
Line 1407 
 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 Cm title 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
 The document's title (name).  The document's title (name), defaulting to
 This should be capitalised and is required.  .Qq UNKNOWN
   if unspecified.
   It should be capitalised.
 .It Cm section  .It Cm section
 The manual section.  The manual section.
 This may be one of  This may be one of
Line 1451 
Line 1462 
 or  or
 .Ar paper  .Ar paper
 .Pq paper .  .Pq paper .
 It is also required and should correspond to the manual's filename  It should correspond to the manual's filename suffix and defaults to
 suffix.  .Qq 1
   if unspecified.
 .It Cm volume  .It Cm volume
 This overrides the volume inferred from  This overrides the volume inferred from
 .Ar section .  .Ar section .
Line 1524 
Line 1536 
 .D1 \&.Dt FOO 1  .D1 \&.Dt FOO 1
 .D1 \&.Dt FOO 4 KM  .D1 \&.Dt FOO 4 KM
 .D1 \&.Dt FOO 9 i386  .D1 \&.Dt FOO 9 i386
 .D1 \&.Dt FOO 9 KM i386  
 .Pp  .Pp
 See also  See also
 .Sx \&Dd  .Sx \&Dd
Line 1561 
Line 1572 
 .Ss \&Ef  .Ss \&Ef
 .Ss \&Ek  .Ss \&Ek
 .Ss \&El  .Ss \&El
   Ends a list context started by
   .Sx \&Bl .
   .Pp
   See also
   .Sx \&Bl
   and
   .Sx \&It .
 .Ss \&Em  .Ss \&Em
 Denotes text that should be emphasised.  Denotes text that should be emphasised.
 Note that this is a presentation term and should not be used for  Note that this is a presentation term and should not be used for
Line 1600 
Line 1618 
 .Sx \&Nm  .Sx \&Nm
 is provided.  is provided.
 .Ss \&Fa  .Ss \&Fa
   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.
   It is also used to specify the field name of a structure.
   Most often, the
   .Sx \&Fa
   macro is used in the
   .Em SYNOPSIS
   within
   .Sx \&Fo
   section when documenting multi-line function prototypes.
   If invoked with multiple arguments, the arguments are separated by a
   comma.
   Furthermore, if the following macro is another
   .Sx \&Fa ,
   the last argument will also have a trailing comma.
   .Pp
   Examples:
   .D1 \&.Fa \(dqconst char *p\(dq
   .D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
   .D1 \&.Fa foo
   .Pp
   See also
   .Sx \&Fo .
 .Ss \&Fc  .Ss \&Fc
 .Ss \&Fd  .Ss \&Fd
   Historically used to document include files.
   This usage has been deprecated in favour of
   .Sx \&In .
   Do not use this macro.
   .Pp
   See also
   .Sx \&In .
 .Ss \&Fl  .Ss \&Fl
 Command-line flag.  Command-line flag.
 Used when listing arguments to command-line utilities.  Used when listing arguments to command-line utilities.
Line 1621 
Line 1676 
 See also  See also
 .Sx \&Cm .  .Sx \&Cm .
 .Ss \&Fn  .Ss \&Fn
   A function name.
   Its syntax is as follows:
   .Bd -ragged -offset indent
   .Pf \. Ns Sx \&Fn
   .Op Cm functype
   .Cm funcname
   .Op Oo Cm argtype Oc Cm argname
   .Ed
   .Pp
   If invoked in the
   .Em SYNOPSIS
   section, vertical space is asserted before and after the macro.
   In all cases, the function arguments are surrounded in parenthesis and
   are delimited by commas.
   If no arguments are specified, blank parenthesis are output.
   .Pp
   Examples:
   .D1 \&.Fn "int funcname" "int arg0" "int arg1"
   .D1 \&.Fn funcname "int arg0"
   .D1 \&.Fn funcname arg0
   .Bd -literal -offset indent -compact
   \&.Ft functype
   \&.Fn funcname
   .Ed
   .Pp
   See also
   .Sx \&Fa ,
   .Sx \&Fo ,
   .Sx \&Fc ,
   and
   .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 1644 
Line 1796 
 .Ss \&Hf  .Ss \&Hf
 .Ss \&Ic  .Ss \&Ic
 .Ss \&In  .Ss \&In
   An
   .Qq include
   file.
   In the
   .Em SYNOPSIS
   section (only if invoked as the line macro), the first argument is
   preceded by
   .Qq #include ,
   the arguments is enclosed in angled braces, and a newline is asserted.
   In all other invocations, only angled braces will enclose the argument.
   .Pp
   Examples
   .D1 \&.In sys/types
 .Ss \&It  .Ss \&It
   A list item.
   The syntax of this macro depends on the list type.
   .Pp
   Lists
   of type
   .Fl hang ,
   .Fl ohang ,
   .Fl inset ,
   and
   .Fl diag
   have the following syntax:
   .Pp
   .D1 Pf \. Sx \&It Cm args
   .Pp
   Lists of type
   .Fl bullet ,
   .Fl dash ,
   .Fl enum ,
   .Fl hyphen
   and
   .Fl item
   have the following syntax:
   .Pp
   .D1 Pf \. Sx \&It
   .Pp
   with subsequent lines interpreted within the scope of the
   .Sx \&It
   until either a closing
   .Sx \&El
   or another
   .Sx \&It .
   .Pp
   The
   .Fl tag
   list has the following syntax:
   .Pp
   .D1 Pf \. Sx \&It Op Cm args
   .Pp
   Subsequent lines are interpreted as with
   .Fl bullet
   and family.
   The line arguments correspond to the list's left-hand side; body
   arguments correspond to the list's contents.
   .Pp
   The
   .Fl column
   list is the most complicated.
   Its syntax is as follows:
   .Pp
   .D1 Pf \. Sx \&It Op Cm args
   .Pp
   The
   .Cm args
   are phrases, a mix of macros and text corresponding to a line column,
   delimited by tabs or the special
   .Sq \&Ta
   pseudo-macro.
   Lines subsequent the
   .Sx \&It
   are interpreted within the scope of the last phrase.
   Calling the pseudo-macro
   .Sq \&Ta
   will open a new phrase scope (this must occur on a macro line to be
   interpreted as a macro).  Note that the tab phrase delimiter may only be
   used within the
   .Sx \&It
   line itself.
   Subsequent this, only the
   .Sq \&Ta
   pseudo-macro may be used to delimit phrases.
   Furthermore, note that quoted sections propogate over tab-delimited
   phrases on an
   .Sx \&It ,
   for example,
   .Pp
   .D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
   .Pp
   will preserve the semicolon whitespace except for the last.
   .Pp
   See also
   .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 1671 
Line 1917 
 .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 1684 
Line 1930 
 .Ss \&Lp  .Ss \&Lp
 .Ss \&Ms  .Ss \&Ms
 .Ss \&Mt  .Ss \&Mt
   Format a
   .Qq mailto:
   hyperlink.
   Its syntax is as follows:
   .Pp
   .D1 Pf \. Sx \&Mt Cm address
   .Pp
   Examples:
   .D1 \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd  .Ss \&Nd
 .Ss \&Nm  .Ss \&Nm
 .Ss \&No  .Ss \&No
Line 1713 
Line 1968 
 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 1787 
Line 2043 
 .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 1872 
Line 2129 
 .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 1911 
Line 2168 
 .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
   .Sx \&Fn
   when not invoked as the line macro in the
   .Em SYNOPSIS
   section.
   .It
   Historic groff formats the
   .Sx \&In
   badly: trailing arguments are trashed and
   .Em SYNOPSIS
   is not specially treated.
   .It
   groff does not accept the
   .Sq \&Ta
   pseudo-macro as a line macro.
   mandoc does.
   .It
 The comment syntax  The comment syntax
 .Sq \e."  .Sq \e."
 is no longer accepted.  is no longer accepted.
Line 1981 
Line 2281 
 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.33  
changed lines
  Added in v.1.34