checking mdoc.samples(7)

checking mdoc.samples(7)

[Ingo Schwarze]

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

Re: checking mdoc.samples(7)

[Ingo Schwarze]

Hi,

Ingo Schwarze wrote on Mon, Aug 01, 2011 at 09:26:00AM +0200:

> 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.

Another step: I have ploughed through MANUAL DOMAIN.

Here is the result:

 * More text for An Ar Cm Fn Ft In Pa Vt.
 * Avoid Ns between Fl and Ar in examples where it is not needed.
 * Fix broken spacing in the last Ar example.
 * In general, just use quoted strings for new and updated examples,
   making the source much easier on the eye.
 * Mention the usual sections for Cd Er Ex In Op.
 * More realistical examples for Cm Fl.
 * Mention the term "options" for Fl, it's used in lots of manuals.
 * Put a blank line before the multi-line Fn example.
 * Add an Sx from Fn to Fo.
 * Typo fix: Say that Fo is closed by Fc.
 * A nice interactive example of Ic taken from mdoc.samples(7).
 * Examples of In look nicer with .h.
 * Avoid the confusing term "command-line option" for Op,
   because that sounds all too much like Fl.
 * Typo fix: -xpg4.3 got lost.

OK?
  Ingo


Index: mdoc.7
===================================================================
RCS file: /cvs/src/share/man/man7/mdoc.7,v
retrieving revision 1.77
diff -u -r1.77 mdoc.7
--- mdoc.7	2 Aug 2011 00:52:34 -0000	1.77
+++ mdoc.7	3 Aug 2011 00:35:39 -0000
@@ -1037,6 +1037,8 @@
 .Dl \&.Ad 0x00000000
 .Ss \&An
 Author name.
+Can be used both for the authors of the program, function, or driver
+documented in the manual, or for the authors of the manual itself.
 Requires either the name of an author or one of the following arguments:
 .Pp
 .Bl -tag -width "-nosplitX" -offset indent -compact
@@ -1107,9 +1109,17 @@
 is used as a default.
 .Pp
 Examples:
-.Dl \&.Fl o \&Ns \&Ar file1
-.Dl \&.Ar
-.Dl \&.Ar arg1 , arg2 .
+.Dl ".Fl o Ar file"
+.Dl ".Ar"
+.Dl ".Ar arg1 , arg2 ."
+.Pp
+The arguments to the
+.Sx \&Ar
+macro are names and placeholders for command arguments;
+for fixed strings to be passed verbatim as arguments, rather use
+.Sx \&Fl
+or
+.Sx \&Cm .
 .Ss \&At
 Formats an AT&T version.
 Accepts one optional argument:
@@ -1512,6 +1522,7 @@
 Kernel configuration declaration.
 This denotes strings accepted by
 .Xr config 8 .
+It is most often used in section 4 manual pages.
 .Pp
 Examples:
 .Dl \&.Cd device le0 at scode?
@@ -1524,14 +1535,17 @@
 This practise is discouraged.
 .Ss \&Cm
 Command modifiers.
-Useful when specifying configuration options or keys.
+Typically used for fixed strings passed as arguments, unless 
+.Sx \&Fl
+is more appropriate.
+Also useful when specifying configuration options or keys.
 .Pp
 Examples:
-.Dl \&.Cm ControlPath
-.Dl \&.Cm ControlMaster
-.Pp
-See also
-.Sx \&Fl .
+.Dl ".Nm mt Fl f Ar device Cm rewind"
+.Dl ".Nm ps Fl o Cm pid , Ns Cm command"
+.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
+.Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa"
+.Dl ".Cm LogLevel Dv DEBUG"
 .Ss \&D1
 One-line indented display.
 This is formatted by the default rules and is useful for simple indented
@@ -1881,6 +1895,7 @@
 Error constants for definitions of the
 .Va errno
 libc global variable.
+This is most often used in section 2 and 3 manual pages.
 .Pp
 Examples:
 .Dl \&.Er EPERM
@@ -1905,6 +1920,7 @@
 .Ss \&Ex
 Insert a standard sentence regarding command exit values of 0 on success
 and >0 on failure.
+This is used most often in section 1, 6, and 8 manual pages.
 Its syntax is as follows:
 .Pp
 .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
@@ -1965,7 +1981,7 @@
 and
 .Sx \&In .
 .Ss \&Fl
-Command-line flag.
+Command-line flag or option.
 Used when listing arguments to command-line utilities.
 Prints a fixed-width hyphen
 .Sq \-
@@ -1975,10 +1991,11 @@
 output.
 .Pp
 Examples:
-.Dl \&.Fl a b c
-.Dl \&.Fl \&Pf a b
-.Dl \&.Fl
-.Dl \&.Op \&Fl o \&Ns \&Ar file
+.Dl ".Nm cat Fl v No considered harmful"
+.Dl ".Nm cp Fl pR Ar source ... directory"
+.Dl ".Nm find Ar dir Fl type Cm d Fl name Pa CVS
+.Dl ".Nm kill Fl Ar signal_number pid"
+.Dl ".Nm su Fl"
 .Pp
 See also
 .Sx \&Cm .
@@ -1995,11 +2012,16 @@
 Function arguments are surrounded in parenthesis and
 are delimited by commas.
 If no arguments are specified, blank parenthesis are output.
+In the
+.Em SYNOPSIS
+section, this macro starts a new output line,
+and a blank line is automatically inserted between function definitions.
 .Pp
 Examples:
 .Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q
 .Dl \&.Fn funcname \*qint arg0\*q
 .Dl \&.Fn funcname arg0
+.Pp
 .Bd -literal -offset indent -compact
 \&.Ft functype
 \&.Fn funcname
@@ -2009,7 +2031,8 @@
 .Sx \&Xr
 instead.
 See also
-.Sx MANUAL STRUCTURE
+.Sx MANUAL STRUCTURE ,
+.Sx \&Fo ,
 and
 .Sx \&Ft .
 .Ss \&Fo
@@ -2036,6 +2059,7 @@
 A
 .Sx \&Fo
 scope is closed by
+.Sx \&Fc .
 .Pp
 See also
 .Sx MANUAL STRUCTURE ,
@@ -2051,6 +2075,10 @@
 .Pp
 .D1 Pf \. Sx \&Ft Ar functype
 .Pp
+In the
+.Em SYNOPSIS
+section, a new output line is started after this macro.
+.Pp
 Examples:
 .Dl \&.Ft int
 .Bd -literal -offset indent -compact
@@ -2091,6 +2119,7 @@
 but used for instructions rather than values.
 .Pp
 Examples:
+.Dl \&.Ic :wq
 .Dl \&.Ic hash
 .Dl \&.Ic alias
 .Pp
@@ -2105,15 +2134,17 @@
 An
 .Dq include
 file.
-In the
+When invoked as the first macro on an input line in the
 .Em SYNOPSIS
-section (only if invoked as the line macro), the first argument is
-preceded by
+section, the argument is displayed in angle brackets
+and preceded by
 .Dq #include ,
-the arguments is enclosed in angle brackets.
+and a blank line is inserted in front if there is a preceding
+function declaration.
+This is most often used in section 2, 3, and 9 manual pages.
 .Pp
 Examples:
-.Dl \&.In sys/types
+.Dl \&.In sys/types.h
 .Pp
 See also
 .Sx MANUAL STRUCTURE .
@@ -2378,9 +2409,11 @@
 \&.Oc
 .Ed
 .Ss \&Op
-Command-line option.
-Used when listing options to command-line utilities.
+Optional part of a command line.
 Prints the argument(s) in brackets.
+This is most often used in the
+.Em SYNOPSIS
+section of section 1 and 8 manual pages.
 .Pp
 Examples:
 .Dl \&.Op \&Fl a \&Ar b
@@ -2438,9 +2471,9 @@
 and
 .Sx \&Ux .
 .Ss \&Pa
-A file-system path.
-If an argument is not provided, the string
-.Dq \(ti
+An absolute or relative file system path, or a file or directory name.
+If an argument is not provided, the character
+.Sq \(ti
 is used as a default.
 .Pp
 Examples:
@@ -2703,6 +2736,7 @@
 .St -xpg4
 .It \-xpg4.2
 .St -xpg4.2
+.It \-xpg4.3
 .St -xpg4.3
 .It \-xbd5
 .St -xbd5
@@ -2790,11 +2824,14 @@
 section, in which case a variable name is also specified.
 Note that it accepts
 .Sx Block partial-implicit
-syntax when invoked as the first macro in the
+syntax when invoked as the first macro on an input line in the
 .Em SYNOPSIS
 section, else it accepts ordinary
 .Sx In-line
 syntax.
+In the former case, this macro starts a new output line,
+and a blank line is inserted in front if there is a preceding
+function definition or include directive.
 .Pp
 Note that this should not be confused with
 .Sx \&Ft ,
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv