===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.45
retrieving revision 1.47
diff -u -p -r1.45 -r1.47
--- mandoc/mdoc.7	2009/07/17 12:40:48	1.45
+++ mandoc/mdoc.7	2009/07/18 18:49:19	1.47
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.45 2009/07/17 12:40:48 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.47 2009/07/18 18:49:19 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -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: July 17 2009 $
+.Dd $Mdocdate: July 18 2009 $
 .Dt MDOC 7
 .Os
 .\" SECTION---------------------------------------------
@@ -49,13 +49,13 @@ prior macros:
 Other lines are interpreted within the current state.
 .Ed
 .\" SECTION---------------------------------------------
-.Sh INPUT ENCODING
+.Sh LANGUAGE SYNTAX
 .Nm
 documents may contain only graphable 7-bit ASCII characters, the space
 character, and, in certain circumstances, the tab character.  All
 manuals must have
 .Ux
-line termination.  
+line terminators.  
 .\" SUB-SECTION----------------------
 .Ss Comments
 Text following a
@@ -131,24 +131,66 @@ also be text-decorated using the
 .Sq \ef
 escape followed by an indicator: B (bold), I, (italic), or P and R
 (Roman, or reset).  This form is not recommended.
+.Pp
+Lastly, a standalone double-quote may be produced in a macro line by
+using two consecutive double-quotes within a quoted literal.  See
+.Sx Quotation
+for details.
 .\" SUB-SECTION----------------------
 .Ss Whitespace
-In general, consecutive blocks of whitespace are pruned from input.
-These are later re-added, when applicable, by 
-.Xr mandoc 1 .
+In non-literal free-form lines, consecutive blocks of whitespace are
+pruned from input and added later in the output filter, if applicable:
+.Bd -literal -offset indent
+These     spaces   are    pruned       from    input.
+\&.Bd \-literal 
+These         are              not.
+\&.Ed
+.Ed
 .\" PARAGRAPH------------
 .Pp
-Blank lines are permitted within
-.Sq \&Bd \-literal
-or
-.Sq \&Bd \-unfilled
-contexts.  Tab characters are only acceptable when delimiting 
+In macro lines, whitespace delimits arguments and is discarded.  If
+arguments are quoted, whitespace within the quotes is retained.
+.\" PARAGRAPH------------
+.Pp
+Blank lines are only permitted within literal contexts, as are lines
+containing only whitespace.  Tab characters are only acceptable when
+delimiting 
 .Sq \&Bl \-column
-and in
-.Sq \&Bd \-literal
-or
-.Sq \&Bd \-unfilled
-contexts.
+or when in a literal context.
+.\" SUB-SECTION----------------------
+.Ss Quotation
+Macro arguments may be quoted with a double-quote to group
+space-delimited terms or to retain blocks of whitespace.  A quoted
+argument begins with a double-quote preceded by whitespace.  The next
+double-quote that is 
+.Em
+preceded by a double-quote terminates the term, regardless of
+surrounding whitespace.  Thus, the following construction produces 
+.Sq "a""b" ,
+since, as mentioned in
+.Sx Special Characters ,
+two consecutive double-quotes in a quoted literal produce a standalone
+double-quote:
+.Bd -literal -offset indent
+\&.Em "a""""b"
+.Ed
+.\" PARAGRAPH------------
+.Pp
+This produces tokens 
+.Sq a" ,
+.Sq b c ,
+.Sq de ,
+and
+.Sq fg" .
+Note that any quoted term, be it argument or macro, is indiscriminately
+considered literal text.  Thus, the following produces 
+.Sq \&Em a :
+.Bd -literal -offset indent
+\&.Em "Em a"
+.Ed
+.\" PARAGRAPH------------
+.Pp
+In free-form mode, quotes are regarded as opaque text.
 .\" SECTION---------------------------------------------
 .Sh MANUAL STRUCTURE
 Each
@@ -157,8 +199,11 @@ document must begin with a document prologue, containi
 .Sq \&Dd ,
 .Sq \&Dt ,
 and
-.Sq \&Os 
-(using this manual as an example):
+.Sq \&Os ,
+then the NAME section containing at least one
+.Sq \&Nm
+followed by 
+.Sq \&Nd :
 .Bd -literal -offset indent
 \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7
@@ -167,12 +212,6 @@ and
 \&.Nm mdoc
 \&.Nd mdoc language reference
 .Ed
-.Pp
-Following these, the document body must begin with the NAME section
-containing at least one 
-.Sq \&Nm
-followed by 
-.Sq \&Nd .
 .\" PARAGRAPH------------
 .Pp
 Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
@@ -181,10 +220,10 @@ but non-compulsory. 
 .Sh MACRO SYNTAX
 Every line beginning with the control character 
 .Sq \.
-is processed for macros, two- or three-character semantic annotations.
+is processed for macros, two- or three-character sequences.
 .\" PARAGRAPH------------
 .Pp
-The syntax of macro depends on its classification.  In this section,
+The syntax of a macro depends on its classification.  In this section,
 .Sq \-arg 
 refers to macro arguments, which may be followed by zero or more
 .Sq parm
@@ -199,7 +238,7 @@ The
 .Em Callable
 column indicates that the macro may be called subsequent to the initial
 line-macro.  The 
-.Qq Parsable
+.Em Parsable
 column indicates whether the macro may be followed by further
 (ostensibly callable) macros.  The
 .Em Scope
@@ -504,7 +543,7 @@ macro only produces the first parameter.  This is no l
 .Sh AUTHORS
 The
 .Nm
-utility was written by 
+reference was written by 
 .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION---------------------------------------------
 .Sh CAVEATS