===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/mandoc/Attic/mdoc.7,v
retrieving revision 1.33
retrieving revision 1.34
diff -c -r1.33 -r1.34
*** src/usr.bin/mandoc/Attic/mdoc.7	2010/06/06 18:08:41	1.33
--- src/usr.bin/mandoc/Attic/mdoc.7	2010/06/06 20:30:08	1.34
***************
*** 1,4 ****
! .\"	$Id: mdoc.7,v 1.33 2010/06/06 18:08:41 schwarze Exp $
  .\"
  .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
  .\"
--- 1,4 ----
! .\"	$Id: mdoc.7,v 1.34 2010/06/06 20:30:08 schwarze Exp $
  .\"
  .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
  .\"
***************
*** 33,39 ****
  .Pp
  An
  .Nm
! document follows simple rules:  lines beginning with the control
  character
  .Sq \.
  are parsed for macros.  Other lines are interpreted within the scope of
--- 33,39 ----
  .Pp
  An
  .Nm
! document follows simple rules: lines beginning with the control
  character
  .Sq \.
  are parsed for macros.  Other lines are interpreted within the scope of
***************
*** 122,128 ****
  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 ,
--- 122,128 ----
  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 ,
***************
*** 343,360 ****
  \&.Dd $\&Mdocdate$
  \&.Dt mdoc 7
  \&.Os
- \&.
  \&.Sh NAME
  \&.Nm foo
  \&.Nd a description goes here
  \&.\e\*q The next is for sections 2, 3, & 9 only.
  \&.\e\*q .Sh LIBRARY
- \&.
  \&.Sh SYNOPSIS
  \&.Nm foo
  \&.Op Fl options
  \&.Ar
- \&.
  \&.Sh DESCRIPTION
  The
  \&.Nm
--- 343,357 ----
***************
*** 1139,1160 ****
  These dictate the width of columns either as
  .Sx Scaling Widths
  or literal text.
! List entry bodies must be left empty.
! Column bodies have the following syntax:
! .Pp
! .D1 .It col1 <TAB> ... coln
! .D1 .It col1 Ta ... coln
! .D1 .It col1 <TAB> col2 Ta coln
! .Pp
! where columns may be separated by tabs, the literal string
! .Qq Ta ,
! or a mixture of both.
! These are equivalent except that quoted sections propogate over tabs,
! for example,
! .Pp
! .D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
! .Pp
! will preserve the semicolon whitespace except for the last.
  .It Fl dash
  A list offset by a dash (hyphen).
  The head of list entries must be empty.
--- 1136,1153 ----
  These dictate the width of columns either as
  .Sx Scaling Widths
  or literal text.
! If the initial macro of a
! .Fl column
! list is not an
! .Sx \&It ,
! an
! .Sx \&It
! context spanning each line is implied until an
! .Sx \&It
! line macro is encountered, at which point list bodies are interpreted as
! described in the
! .Sx \&It
! documentation.
  .It Fl dash
  A list offset by a dash (hyphen).
  The head of list entries must be empty.
***************
*** 1209,1214 ****
--- 1202,1210 ----
  .Fl width
  argument.
  .El
+ .Pp
+ See also
+ .Sx \&It .
  .Ss \&Bo
  Begins a block enclosed by square brackets.
  Does not have any head arguments.
***************
*** 1336,1341 ****
--- 1332,1342 ----
  and
  .Sx \&Dl .
  .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
  Closes a
  .Sx \&Do
***************
*** 1345,1353 ****
  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
--- 1346,1354 ----
  This is the mandatory first macro of any
  .Nm
  manual.
! Its syntax is as follows:
  .Pp
! .D1 Pf \. Sx \&Dd Cm date
  .Pp
  The
  .Cm date
***************
*** 1406,1420 ****
  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
--- 1407,1431 ----
  This is the mandatory second macro of any
  .Nm
  file.
! 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
  Its arguments are as follows:
  .Bl -tag -width Ds -offset Ds
  .It Cm title
! The document's title (name), defaulting to
! .Qq UNKNOWN
! if unspecified.
! It should be capitalised.
  .It Cm section
  The manual section.
  This may be one of
***************
*** 1451,1458 ****
  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 .
--- 1462,1470 ----
  or
  .Ar paper
  .Pq paper .
! It should correspond to the manual's filename suffix and defaults to
! .Qq 1
! if unspecified.
  .It Cm volume
  This overrides the volume inferred from
  .Ar section .
***************
*** 1524,1530 ****
  .D1 \&.Dt FOO 1
  .D1 \&.Dt FOO 4 KM
  .D1 \&.Dt FOO 9 i386
- .D1 \&.Dt FOO 9 KM i386
  .Pp
  See also
  .Sx \&Dd
--- 1536,1541 ----
***************
*** 1561,1566 ****
--- 1572,1584 ----
  .Ss \&Ef
  .Ss \&Ek
  .Ss \&El
+ Ends a list context started by
+ .Sx \&Bl .
+ .Pp
+ See also
+ .Sx \&Bl
+ and
+ .Sx \&It .
  .Ss \&Em
  Denotes text that should be emphasised.
  Note that this is a presentation term and should not be used for
***************
*** 1600,1607 ****
--- 1618,1662 ----
  .Sx \&Nm
  is provided.
  .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 \&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
  Command-line flag.
  Used when listing arguments to command-line utilities.
***************
*** 1621,1629 ****
--- 1676,1781 ----
  See also
  .Sx \&Cm .
  .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
+ 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 \&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
  Format the FreeBSD version provided as an argument, or a default value
  if no argument is provided.
***************
*** 1644,1655 ****
  .Ss \&Hf
  .Ss \&Ic
  .Ss \&In
  .Ss \&It
  .Ss \&Lb
  Specify a library.
! The calling syntax is as follows:
  .Pp
! .D1 \. Ns Sx \&Lb Cm library
  .Pp
  The
  .Cm library
--- 1796,1901 ----
  .Ss \&Hf
  .Ss \&Ic
  .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
+ 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
  Specify a library.
! The syntax is as follows:
  .Pp
! .D1 Pf \. Sx \&Lb Cm library
  .Pp
  The
  .Cm library
***************
*** 1671,1679 ****
  .Ss \&Li
  .Ss \&Lk
  Format a hyperlink.
! The calling syntax is as follows:
  .Pp
! .D1 \. Ns Sx \&Lk Cm uri Op Cm name
  .Pp
  Examples:
  .D1 \&.Lk http://bsd.lv "The BSD.lv Project"
--- 1917,1925 ----
  .Ss \&Li
  .Ss \&Lk
  Format a hyperlink.
! Its syntax is as follows:
  .Pp
! .D1 Pf \. Sx \&Lk Cm uri Op Cm name
  .Pp
  Examples:
  .D1 \&.Lk http://bsd.lv "The BSD.lv Project"
***************
*** 1684,1689 ****
--- 1930,1944 ----
  .Ss \&Lp
  .Ss \&Ms
  .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 \&Nm
  .Ss \&No
***************
*** 1713,1721 ****
  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
--- 1968,1977 ----
  This is the mandatory third macro of
  any
  .Nm
! file.
! Its syntax is as follows:
  .Pp
! .D1 Pf \. Sx \&Os Op Cm system
  .Pp
  The optional
  .Cm system
***************
*** 1787,1792 ****
--- 2043,2049 ----
  .Sx \&%Q ,
  .Sx \&%R ,
  .Sx \&%T ,
+ .Sx \&%U ,
  and
  .Sx \&%V
  child macros (at least one must be specified).
***************
*** 1872,1880 ****
  .Ss \&Xr
  Link to another manual
  .Pq Qq cross-reference .
! Its calling syntax is
  .Pp
! .D1 \. Ns Sx \&Xr Cm name section
  .Pp
  The
  .Cm name
--- 2129,2137 ----
  .Ss \&Xr
  Link to another manual
  .Pq Qq cross-reference .
! Its syntax is as follows:
  .Pp
! .D1 Pf \. Sx \&Xr Cm name section
  .Pp
  The
  .Cm name
***************
*** 1911,1916 ****
--- 2168,2216 ----
  .Pp
  .Bl -dash -compact
  .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
  .Sq \e."
  is no longer accepted.
***************
*** 1981,1991 ****
  incorrectly by following it with a reserved character and expecting the
  delimiter to render.
  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
  In groff, the
  .Sx \&Cd ,
--- 2281,2286 ----