Re: checking mdoc.samples(7)

[Ingo Schwarze <schwarze@usta.de>]

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