===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.185
retrieving revision 1.189
diff -u -p -r1.185 -r1.189
--- mandoc/mdoc.7	2011/04/06 11:39:25	1.185
+++ mandoc/mdoc.7	2011/07/11 08:45:02	1.189
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.185 2011/04/06 11:39:25 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.189 2011/07/11 08:45:02 kristaps Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,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: April 6 2011 $
+.Dd $Mdocdate: July 11 2011 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -97,8 +97,6 @@ Within a macro line, the following terms are reserved:
 .Pq reserved-word vertical bar
 .El
 .Pp
-Use of reserved terms is described in
-.Sx MACRO SYNTAX .
 For general use in macro lines, these can be escaped with a non-breaking
 space
 .Pq Sq \e& .
@@ -298,19 +296,20 @@ sections, although this varies between manual sections
 .Pp
 The following is a well-formed skeleton
 .Nm
-file:
+file for a utility
+.Qq progname :
 .Bd -literal -offset indent
 \&.Dd $\&Mdocdate$
-\&.Dt mdoc 7
+\&.Dt PROGNAME section
 \&.Os
 \&.Sh NAME
-\&.Nm foo
+\&.Nm progname
 \&.Nd a description goes here
 \&.\e\*q .Sh LIBRARY
 \&.\e\*q For sections 2, 3, & 9 only.
 \&.\e\*q Not used in OpenBSD.
 \&.Sh SYNOPSIS
-\&.Nm foo
+\&.Nm progname
 \&.Op Fl options
 \&.Ar
 \&.Sh DESCRIPTION
@@ -1176,8 +1175,9 @@ See also
 and
 .Sx \&Sy .
 .Ss \&Bk
-Keep the output generated from each macro input line together
-on one single output line.
+For each macro, keep its output together on the same output line,
+until the end of the macro or the end of the input line is reached,
+whichever comes first.
 Line breaks in text lines are unaffected.
 The syntax is as follows:
 .Pp
@@ -1691,14 +1691,21 @@ See also
 and
 .Sx \&Os .
 .Ss \&Dv
-Defined variables such as preprocessor constants.
+Defined variables such as preprocessor constants, constant symbols,
+enumeration values, and so on.
 .Pp
 Examples:
+.Dl \&.Dv NULL
 .Dl \&.Dv BUFSIZ
 .Dl \&.Dv STDOUT_FILENO
 .Pp
 See also
-.Sx \&Er .
+.Sx \&Er
+and
+.Sx \&Ev
+for special-purpose constants and
+.Sx \&Va
+for variable symbols.
 .Ss \&Dx
 Format the DragonFly BSD version provided as an argument, or a default
 value if no argument is provided.
@@ -1774,14 +1781,17 @@ argument is used as the enclosure head, for example, s
 will emulate
 .Sx \&Do .
 .Ss \&Er
-Display error constants.
+Error constants for definitions of the
+.Va errno
+libc global variable.
 .Pp
 Examples:
 .Dl \&.Er EPERM
 .Dl \&.Er ENOENT
 .Pp
 See also
-.Sx \&Dv .
+.Sx \&Dv
+for general constants.
 .Ss \&Es
 This macro is obsolete and not implemented.
 .Ss \&Ev
@@ -1791,6 +1801,10 @@ Environmental variables such as those specified in
 Examples:
 .Dl \&.Ev DISPLAY
 .Dl \&.Ev PATH
+.Pp
+See also
+.Sx \&Dv
+for general constants.
 .Ss \&Ex
 Insert a standard sentence regarding exit values.
 Its syntax is as follows: