* mdocml: Better explain roff(7) macro argument quoting; ok jmc@.
@ 2011-01-24 23:17 schwarze
0 siblings, 0 replies; only message in thread
From: schwarze @ 2011-01-24 23:17 UTC (permalink / raw)
To: source
Log Message:
-----------
Better explain roff(7) macro argument quoting;
ok jmc@.
Modified Files:
--------------
mdocml:
man.7
roff.7
Revision Data
-------------
Index: man.7
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/man.7,v
retrieving revision 1.95
retrieving revision 1.96
diff -Lman.7 -Lman.7 -u -p -r1.95 -r1.96
--- man.7
+++ man.7
@@ -373,6 +373,13 @@ Thus, the following are equivalent:
\&.\ \ \ PP
.Ed
.Pp
+To include space characters in 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: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/roff.7,v
retrieving revision 1.23
retrieving revision 1.24
diff -Lroff.7 -Lroff.7 -u -p -r1.23 -r1.24
--- roff.7
+++ roff.7
@@ -86,6 +86,38 @@ Thus, the following request lines are al
\&.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 @@ The macro can be invoked later using the
.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 source+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2011-01-24 23:17 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-01-24 23:17 mdocml: Better explain roff(7) macro argument quoting; ok jmc@ schwarze
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).