===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.114
retrieving revision 1.117
diff -u -p -r1.114 -r1.117
--- mandoc/mdoc.7	2010/06/03 14:29:52	1.114
+++ mandoc/mdoc.7	2010/06/04 20:57:26	1.117
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.114 2010/06/03 14:29:52 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.117 2010/06/04 20:57:26 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: June 3 2010 $
+.Dd $Mdocdate: June 4 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -1332,6 +1332,11 @@ See also
 and
 .Sx \&Dl .
 .Ss \&Db
+Start a debugging context.
+This macro is parsed, but generally ignored.
+Its calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Db Cm on | off
 .Ss \&Dc
 Closes a
 .Sx \&Do
@@ -1559,6 +1564,13 @@ and
 .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
@@ -1598,8 +1610,33 @@ is not provided, the document's name as stipulated in
 .Sx \&Nm
 is provided.
 .Ss \&Fa
+Function argument.
+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
+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
 .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.
@@ -1762,6 +1799,15 @@ See also
 .Ss \&Lp
 .Ss \&Ms
 .Ss \&Mt
+Format a
+.Qq mailto:
+hyperlink.
+The calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Mt Cm address
+.Pp
+Examples:
+.D1 \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd
 .Ss \&Nm
 .Ss \&No
@@ -1988,6 +2034,11 @@ Heirloom troff, the other significant troff implementa
 \-mdoc, is similar to historic groff.
 .Pp
 .Bl -dash -compact
+.It
+groff does not accept the
+.Sq \&Ta
+pseudo-macro as a line macro.
+mandoc does.
 .It
 The comment syntax
 .Sq \e."