better explain roff(7) macro argument quoting

[Ingo Schwarze <schwarze@usta.de>]

Hi Jason, hi Kristaps,

Kristaps Dzonsons wrote on Fri, Jan 21, 2011 at 07:31:53PM +0100:

[...]
> (I remember some documentation is still pending from you for the
> argument handling...)

Yes, indeed, i promised to look into that when i recently fixed the
roff(7) and man(7) argument parsing code.  Thanks for the reminder.

So, here is a suggestion.

This is really about roff(7) syntax, so i strongly feel it should be
in roff(7), not in man(7) and mdoc(7).  For now, i propose to put
a pointer into man(7), but to not touch the text in mdoc(7) yet.
As you know, the mdoc(7) code is still partially broken, so pointing
to roff(7) right now would even be a bit misleading; besides, what
mdoc(7) has so far roughly matches what mandoc really does in the
mdoc(7) case, even though that differs from groff in a few respects.

I realize that the text is getting much longer and rather technical.
But roff macro argument quoting is really tricky, so i think
documenting it with as much precision as possible is worthwhile.

Besides, i suggest to move this part of the documentation up to
its own chapter "MACRO SYNTAX" just after "REQUEST SYNTAX" because
the two are closely related, and because argument parsing logic
is somewhat misplaced below .de:  We are not talking about the
parsing of the arguments passed to the .de request after all.

OK?
  Ingo


Index: man.7
===================================================================
RCS file: /cvs/src/share/man/man7/man.7,v
retrieving revision 1.14
diff -u -r1.14 man.7
--- man.7	16 Jan 2011 02:56:47 -0000	1.14
+++ man.7	22 Jan 2011 16:04:23 -0000
@@ -373,6 +373,13 @@
 \&.\ \ \ PP
 .Ed
 .Pp
+To include space characters into macro arguments, arguments may be quoted;
+see the
+.Sq MACRO SYNTAX
+section in the
+.Xr roff 7
+manual for details.
+.Pp
 The
 .Nm
 macros are classified by scope: line scope or block scope.
Index: roff.7
===================================================================
RCS file: /cvs/src/share/man/man7/roff.7,v
retrieving revision 1.8
diff -u -r1.8 roff.7
--- roff.7	9 Jan 2011 15:24:57 -0000	1.8
+++ roff.7	22 Jan 2011 16:04:23 -0000
@@ -86,6 +86,38 @@
 \&.ig    end
 \&.   ig end
 .Ed
+.Sh MACRO SYNTAX
+Macros can be defined by the
+.Sx \&de
+request.
+When called, they follow the same syntax as requests, except that
+macro arguments may optionally be quoted by enclosing them
+in double quote characters
+.Pq Sq \(dq .
+To be recognized as the beginning of a quoted argument, the opening
+quote character must be preceded by a space character.
+.Pp
+A quoted argument may contain whitespace, and pairs of double quote
+characters
+.Pq Sq Qq
+resolve to single double quote characters.
+A quoted argument extends to the next double quote character that is not
+part of a pair, or to the end of the input line, whichever comes earlier.
+Leaving out the terminating double quote character at the end of the line
+is discouraged.
+For clarity, if more arguments follow on the same input line,
+it is recommended to follow the terminating double quote character
+by a space character; in case the next character after the terminating
+double quote character is anything else, it is regarded as the beginning
+of the next, unquoted argument.
+.Pp
+Both in quoted and unquoted arguments, pairs of backslashes
+.Pq Sq \e\e
+resolve to single backslashes.
+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.
 .Sh REQUEST REFERENCE
 The
 .Xr mandoc 1
@@ -174,12 +206,9 @@
 .Pp
 .D1 Pf . Ar name Op Ar argument Op Ar argument ...
 .Pp
-Arguments are separated by blank characters and can be quoted
-using double-quotes
-.Pq Sq \(dq
-to allow inclusion of blank characters into arguments.
-To include the double-quote character into a quoted argument,
-escape it from ending the argument by doubling it.
+Regarding argument parsing, see
+.Sx MACRO SYNTAX
+above.
 .Pp
 The line invoking the macro will be replaced
 in the input stream by the
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv