checking mdoc.samples(7)

[Ingo Schwarze <schwarze@usta.de>]

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