First, use \(dq instead of \*q for double-quote. Second, use `Li' to

note literal text in "Examples:" parts.  Finally, move parts of
Quotation related to keeping whitespace into Whitespace and clean up the
text to be a bit clearer.  Examples can be added back in at will, but
now it follows the general layout of explanation followed by examples.

1 files changed, 67 insertions, 74 deletions

diff --git a/mdoc.7 b/mdoc.7
index b42c6fcc..1f8049df 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.202 2011/08/18 08:58:44 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.203 2011/08/19 10:19:55 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: August 18 2011 $
+.Dd $Mdocdate: August 19 2011 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -63,11 +63,11 @@ and
 .Sx Special Characters .
 .Ss Comments
 Text following an escaped double-quote
-.Sq \e\*q ,
+.Sq \e\(dq ,
 whether in a macro or text line, is ignored to the end of
 line.
 A macro line beginning with a control character and comment escape
-.Sq \&.\e\*q
+.Sq \&.\e\(dq
 is also ignored.
 Furthermore,
 macro lines with only a control character and optional trailing
@@ -76,10 +76,10 @@ stripped from input.
 .Pp
 Examples:
 .Bd -literal -offset indent -compact
-\&.\e\*q This is a comment line.
-\&.\e\*q The next line is ignored:
+\&.\e\(dq This is a comment line.
+\&.\e\(dq The next line is ignored:
 \&.
-\&.Em Emphasis \e\*q This is also a comment.
+\&.Em Emphasis \e\(dq This is also a comment.
 .Ed
 .Ss Special Characters
 Special characters are used to encode special glyphs and are rendered
@@ -97,9 +97,9 @@ or a single one character sequence.
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact
-.It \e(em
+.It Li \e(em
 em dash
-.It \ee
+.It Li \ee
 backslash
 .El
 .Pp
@@ -125,9 +125,9 @@ scope.
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact
-.It \efBbold\efR
+.It Li \efBbold\efR
 write in bold, then switch to regular
-.It \efIitalic\efP
+.It Li \efIitalic\efP
 write in italic, then return to previous
 .El
 .Pp
@@ -151,9 +151,9 @@ and N-character
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact
-.It \e*(Am
+.It Li \e*(Am
 ampersand
-.It \e*(Ba
+.It Li \e*(Ba
 vertical bar
 .El
 .Pp
@@ -176,44 +176,37 @@ In the rare case that a blank character is needed at the end of an
 input line, it may be forced by
 .Sq \e\ \e& .
 .Pp
+In general, space characters can be considered as non-whitespace
+characters by using non-breaking space escapes or
+.Sx Quotation .
+.Pp
 Blank text lines, which may include whitespace, are only permitted
 within literal contexts.
 If the first character of a text line is a space, that line is printed
 with a leading newline.
 .Ss Quotation
-Macro arguments may be quoted with double-quotes; in this case,
-whitespace within the quotes is retained as part of the argument.
-For example,
-.Pp
-.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq"
-.Pp
-renders as
-.Sq Fn strlen "const char *s" ,
-while
-.Pp
-.D1 Pf \. \&Fn strlen "const char *s"
-.Pp
-would produce
-.Sq Fn strlen const char *s .
+Macro arguments may be quoted with double-quotes to so that the
+enclosed text is one literal term.
+Quoted text, even if whitespace or if it would cause a macro invocation
+when unquoted, is considered literal text.
 .Pp
 A quoted argument begins with a double-quote preceded by whitespace.
 The next double-quote not pairwise adjacent to another double-quote
 terminates the literal, regardless of surrounding whitespace.
 .Pp
-In unquoted arguments, space characters can alternatively be included
-by preceding them with a backslash
-.Pq Sq \e\~ ,
-but quoting is usually better for clarity.
-.Pp
-Note that any quoted text, even if it would cause a macro invocation
-when unquoted, is considered literal text.
-Thus, the following produces
-.Sq Op "Fl a" :
-.Bd -literal -offset indent
-\&.Op "Fl a"
-.Ed
-.Pp
-In text lines, quotes are regarded as opaque text.
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li .Fn strlen \(dqconst char *s\(dq
+groups
+.Qq const char *s
+into one term
+.Pq see Sx \&Fn
+.It Li .Op \(dqFl a\(dq
+considers
+.Qq \&Fl a
+as literal text
+.Pq see Sx \&Op , \&Fl
+.El
 .Ss Scaling Widths
 Many macros support scaled widths for their arguments.
 The syntax for a scaled width is
@@ -265,10 +258,10 @@ See
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact
-.It \&.Bl -tag -width 2i
+.It Li \&.Bl -tag -width 2i
 two-inch tagged list indentation
 .Pq see Sx \&Bl
-.It \&.sp 2v
+.It Li \&.sp 2v
 two vertical spaces
 .Pq see Sx \&sp
 .El
@@ -332,9 +325,9 @@ file for a utility
 \&.Sh NAME
 \&.Nm progname
 \&.Nd one line about what it does
-\&.\e\*q .Sh LIBRARY
-\&.\e\*q For sections 2, 3, & 9 only.
-\&.\e\*q Not used in OpenBSD.
+\&.\e\(dq .Sh LIBRARY
+\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq Not used in OpenBSD.
 \&.Sh SYNOPSIS
 \&.Nm progname
 \&.Op Fl options
@@ -343,29 +336,29 @@ file for a utility
 The
 \&.Nm
 utility processes files ...
-\&.\e\*q .Sh IMPLEMENTATION NOTES
-\&.\e\*q Not used in OpenBSD.
-\&.\e\*q .Sh RETURN VALUES
-\&.\e\*q For sections 2, 3, & 9 only.
-\&.\e\*q .Sh ENVIRONMENT
-\&.\e\*q For sections 1, 6, 7, & 8 only.
-\&.\e\*q .Sh FILES
-\&.\e\*q .Sh EXIT STATUS
-\&.\e\*q For sections 1, 6, & 8 only.
-\&.\e\*q .Sh EXAMPLES
-\&.\e\*q .Sh DIAGNOSTICS
-\&.\e\*q For sections 1, 4, 6, 7, & 8 only.
-\&.\e\*q .Sh ERRORS
-\&.\e\*q For sections 2, 3, & 9 only.
-\&.\e\*q .Sh SEE ALSO
-\&.\e\*q .Xr foobar 1
-\&.\e\*q .Sh STANDARDS
-\&.\e\*q .Sh HISTORY
-\&.\e\*q .Sh AUTHORS
-\&.\e\*q .Sh CAVEATS
-\&.\e\*q .Sh BUGS
-\&.\e\*q .Sh SECURITY CONSIDERATIONS
-\&.\e\*q Not used in OpenBSD.
+\&.\e\(dq .Sh IMPLEMENTATION NOTES
+\&.\e\(dq Not used in OpenBSD.
+\&.\e\(dq .Sh RETURN VALUES
+\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq .Sh ENVIRONMENT
+\&.\e\(dq For sections 1, 6, 7, & 8 only.
+\&.\e\(dq .Sh FILES
+\&.\e\(dq .Sh EXIT STATUS
+\&.\e\(dq For sections 1, 6, & 8 only.
+\&.\e\(dq .Sh EXAMPLES
+\&.\e\(dq .Sh DIAGNOSTICS
+\&.\e\(dq For sections 1, 4, 6, 7, & 8 only.
+\&.\e\(dq .Sh ERRORS
+\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq .Sh SEE ALSO
+\&.\e\(dq .Xr foobar 1
+\&.\e\(dq .Sh STANDARDS
+\&.\e\(dq .Sh HISTORY
+\&.\e\(dq .Sh AUTHORS
+\&.\e\(dq .Sh CAVEATS
+\&.\e\(dq .Sh BUGS
+\&.\e\(dq .Sh SECURITY CONSIDERATIONS
+\&.\e\(dq Not used in OpenBSD.
 .Ed
 .Pp
 The sections in an
@@ -446,8 +439,8 @@ macros should follow C header-file conventions.
 .Pp
 And for the third, configurations (section 4):
 .Bd -literal -offset indent
-\&.Cd \*qit* at isa? port 0x2e\*q
-\&.Cd \*qit* at isa? port 0x4e\*q
+\&.Cd \(dqit* at isa? port 0x2e\(dq
+\&.Cd \(dqit* at isa? port 0x4e\(dq
 .Ed
 .Pp
 Manuals not in these sections generally don't need a
@@ -2103,8 +2096,8 @@ section, this macro starts a new output line,
 and a blank line is automatically inserted between function definitions.
 .Pp
 Examples:
-.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q
-.Dl \&.Fn funcname \*qint arg0\*q
+.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
+.Dl \&.Fn funcname \(dqint arg0\(dq
 .Dl \&.Fn funcname arg0
 .Pp
 .Bd -literal -offset indent -compact
@@ -2369,7 +2362,7 @@ Its syntax is as follows:
 .D1 Pf \. Sx \&Lk Ar uri Op Ar name
 .Pp
 Examples:
-.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q
+.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
 .Dl \&.Lk http://bsd.lv
 .Pp
 See also