Bring man.7's LANGUAGE SYNTAX in line with mdoc.7. While here, change

out the \*q escapes.  Also fix some spelling typos in both manuals.

1 files changed, 77 insertions, 61 deletions

diff --git a/man.7 b/man.7
index 9a4098ae..7bf31b85 100644
--- a/man.7
+++ b/man.7
@@ -1,4 +1,4 @@
-.\"	$Id: man.7,v 1.105 2011/08/18 08:58:43 kristaps Exp $
+.\"	$Id: man.7,v 1.106 2011/08/19 13:07:22 kristaps Exp $
 .\"
 .\" Copyright (c) 2009, 2010 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: August 18 2011 $
+.Dd $Mdocdate: August 19 2011 $
 .Dt MAN 7
 .Os
 .Sh NAME
@@ -39,15 +39,15 @@ language, instead.
 .Pp
 A
 .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
-prior macros:
+Lines not beginning with the control character are
+interpreted within the scope of prior macros:
 .Bd -literal -offset indent
 \&.SH Macro lines change control state.
-Other lines are interpreted within the current state.
+Text lines are interpreted within the current state.
 .Ed
 .Sh LANGUAGE SYNTAX
 .Nm
@@ -62,11 +62,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
@@ -75,10 +75,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
@@ -96,10 +96,10 @@ or a single one character sequence.
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact
-.It \e(em
-em dash
-.It \ee
-backslash
+.It Li \e(em
+Two-letter em dash escape.
+.It Li \ee
+One-letter backslash escape.
 .El
 .Pp
 See
@@ -109,7 +109,7 @@ for a complete list.
 Terms may be text-decorated using the
 .Sq \ef
 escape followed by an indicator: B (bold), I (italic), R (regular), or P
-(revert to previous mode):
+(revert to previous mode).
 A numerical representation 3, 2, or 1 (bold, italic, and regular,
 respectively) may be used instead.
 A text decoration is only valid, if specified in free-form text, until
@@ -125,10 +125,10 @@ attribute is forgotten when entering or exiting a macro block.
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact
-.It \efBbold\efR
-write in bold, then switch to regular
-.It \efIitalic\efP
-write in italic, then return to previous
+.It Li \efBbold\efR
+Write in bold, then switch to regular font mode.
+.It Li \efIitalic\efP
+Write in italic, then return to previous font mode.
 .El
 .Ss Predefined Strings
 Predefined strings, like
@@ -145,10 +145,10 @@ and N-character
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact
-.It \e*(Am
-ampersand
-.It \e*(Ba
-vertical bar
+.It Li \e*(Am
+Two-letter ampersand predefined string.
+.It Li \e*q
+One-letter double-quote predefined string.
 .El
 .Pp
 These strings are set using
@@ -170,25 +170,41 @@ 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 rendered as literal
+characters by using non-breaking space escapes or
+.Sx Quotation .
 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.
+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.
-.Pp
-In text lines, quotes are regarded as opaque text.
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li .BR a \(dqb c\(dq d
+Group arguments
+.Qq b c
+into one un-bolded argument.
+If unspecified,
+.Qq a
+and
+.Qq c
+will be in bold,
+.Qq b
+and
+.Qq d
+in regular font mode.
+Furthermore, will be preserved between
+.Qq b
+and
+.Qq c .
+.El
 .Ss Scaling Widths
 Many macros support scaled widths for their arguments.
 The syntax for a scaled width is
@@ -294,36 +310,36 @@ file for a utility
 \&.TH PROGNAME 1 2009-10-10
 \&.SH NAME
 \efBprogname\efR \e(en a description goes here
-\&.\e\*q .SH LIBRARY
-\&.\e\*q For sections 2 & 3 only.
-\&.\e\*q Not used in OpenBSD.
+\&.\e\(dq .SH LIBRARY
+\&.\e\(dq For sections 2 & 3 only.
+\&.\e\(dq Not used in OpenBSD.
 \&.SH SYNOPSIS
 \efBprogname\efR [\efB\e-options\efR] arguments...
 \&.SH DESCRIPTION
 The \efBfoo\efR 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 .BR foo ( 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 .BR foo ( 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 a