From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout.scc.kit.edu (scc-mailout.scc.kit.edu [129.13.185.201]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p717Q3GP014654 for ; Mon, 1 Aug 2011 03:26:04 -0400 (EDT) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by scc-mailout-01 with esmtp (Exim 4.72 #1) id 1Qnmsz-0007Zv-E8; Mon, 01 Aug 2011 09:26:01 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1Qnmsz-0001YD-Bw; Mon, 01 Aug 2011 09:26:01 +0200 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.69) (envelope-from ) id 1Qnmsz-0000vt-7x; Mon, 01 Aug 2011 09:26:01 +0200 Received: from schwarze by usta.de with local (Exim 4.72) (envelope-from ) id 1Qnmsy-0007EI-Rp; Mon, 01 Aug 2011 09:26:00 +0200 Date: Mon, 1 Aug 2011 09:26:00 +0200 From: Ingo Schwarze To: tech@mdocml.bsd.lv Cc: jmc@openbsd.org Subject: checking mdoc.samples(7) Message-ID: <20110801072600.GA30355@iris.usta.de> X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.5.21 (2010-09-15) Hi, since a long time, i have been planning to check whether any content from mdoc.samples(7) is missing from mdoc(7). Now i have done another step forward, checking all chapters except those covering individual macros (MANUAL DOMAIN, GENERAL TEXT DOMAIN, and PAGE STRUCTURE DOMAIN). These three remain to be checked. The result is the following patch, containing new text for mdoc(7), mostly rewritten from scratch. * Discourage trailing whitespace. * Move all information about quoted arguments to the relevant subsection, shortening it a bit, and adding an example. * Mention that blanks can be quoted with a backslash. * A better .Nd line in the template (verbatim form mdoc.samples(7)). * Explain how to escape callable macro names, and provide examples. OK? Yours, Ingo Index: mdoc.7 =================================================================== RCS file: /cvs/src/share/man/man7/mdoc.7,v retrieving revision 1.75 diff -u -r1.75 mdoc.7 --- mdoc.7 31 Jul 2011 17:12:29 -0000 1.75 +++ mdoc.7 1 Aug 2011 07:23:15 -0000 @@ -179,15 +179,38 @@ Blank text lines, which may include whitespace, are only permitted within literal contexts. .Pp +In general, trailing whitespace on input lines is discouraged +for reasons of clarity and portability. +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 macro lines, whitespace delimits arguments and is discarded. -If arguments are quoted, whitespace within the quotes is retained. .Ss Quotation -Macro arguments may be quoted with double-quotes to group -space-delimited terms or to retain blocks of whitespace. +Macro arguments may be quoted with double-quotes; in this case, +whitespace within the quotes is retained as part of the argument. +For example, +.Pp +.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq" +.Pp +renders as +.Sq Fn strlen "const char *s" , +while +.Pp +.D1 Pf \. \&Fn strlen "const char *s" +.Pp +would produce +.Sq Fn strlen const char *s . +.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. Thus, the following produces @@ -305,7 +328,7 @@ \&.Os \&.Sh NAME \&.Nm progname -\&.Nd a description goes here +\&.Nd one line about what it does \&.\e\*q .Sh LIBRARY \&.\e\*q For sections 2, 3, & 9 only. \&.\e\*q Not used in OpenBSD. @@ -601,6 +624,17 @@ .Em Callable column indicates that the macro may also be called by passing its name as an argument to another macro. +For example, +.Sq \&.Op \&Fl O \&Ar file +produces +.Sq Op Fl O Ar file . +To prevent a macro call and render the macro name literally, +escape it by prepending a non-breaking space, +.Sq \e& . +For example, +.Sq \&Op \e&Fl O +produces +.Sq Op \&Fl O . If a macro is not callable but its name appears as an argument to another macro, it is interpreted as opaque text. For example, -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv