===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.117
retrieving revision 1.119
diff -u -p -r1.117 -r1.119
--- mandoc/mdoc.7	2010/06/04 20:57:26	1.117
+++ mandoc/mdoc.7	2010/06/04 22:16:27	1.119
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.117 2010/06/04 20:57:26 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.119 2010/06/04 22:16:27 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -33,7 +33,7 @@ section describes compatibility with other troff \-mdo
 .Pp
 An
 .Nm
-document follows simple rules:  lines beginning with the control
+document follows simple rules: lines beginning with the control
 character
 .Sq \.
 are parsed for macros.  Other lines are interpreted within the scope of
@@ -122,7 +122,7 @@ escape followed by an indicator: B (bold), I, (italic)
 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
+the current font scope only: if a macro opens a font scope alongside
 its own scope, such as
 .Sx \&Bf
 .Cm \&Sy ,
@@ -1656,6 +1656,33 @@ Examples:
 See also
 .Sx \&Cm .
 .Ss \&Fn
+A function name.
+Its calling 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
+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
+.D1 \&.Fn funcname "int arg0"
+.D1 \&.Fn funcname arg0
+.Pp
+See also
+.Sx \&Fa ,
+.Sx \&Fo ,
+.Sx \&Fc ,
+and
+.Sx \&Ft .
 .Ss \&Fo
 .Ss \&Fr
 .Ss \&Ft
@@ -1679,6 +1706,19 @@ and
 .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
@@ -2034,6 +2074,18 @@ Heirloom troff, the other significant troff implementa
 \-mdoc, is similar to historic groff.
 .Pp
 .Bl -dash -compact
+.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