From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp1.rz.uni-karlsruhe.de (Debian-exim@smtp1.rz.uni-karlsruhe.de [129.13.185.217]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p0MG919j023739 for ; Sat, 22 Jan 2011 11:09:02 -0500 (EST) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by smtp1.rz.uni-karlsruhe.de with esmtp (Exim 4.63 #1) id 1Pgg1J-0000sx-9o; Sat, 22 Jan 2011 17:08:58 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1Pgg1J-0000hS-7Y; Sat, 22 Jan 2011 17:08:57 +0100 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.69) (envelope-from ) id 1Pgg1J-0006IV-6X; Sat, 22 Jan 2011 17:08:57 +0100 Received: from schwarze by usta.de with local (Exim 4.72) (envelope-from ) id 1Pgg1I-0003wc-V6; Sat, 22 Jan 2011 17:08:56 +0100 Date: Sat, 22 Jan 2011 17:08:56 +0100 From: Ingo Schwarze To: jmc@openbsd.org Cc: tech@mdocml.bsd.lv Subject: better explain roff(7) macro argument quoting Message-ID: <20110122160856.GB12520@iris.usta.de> References: <20110102211552.GB21085@iris.usta.de> <4D20EFA4.6090409@bsd.lv> <20110104000606.GC11029@iris.usta.de> <20110120202205.GA14941@iris.usta.de> <4D39D119.7090507@bsd.lv> X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <4D39D119.7090507@bsd.lv> User-Agent: Mutt/1.5.21 (2010-09-15) 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