===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.195
retrieving revision 1.199
diff -u -p -r1.195 -r1.199
--- mandoc/mdoc.7	2011/08/02 01:07:26	1.195
+++ mandoc/mdoc.7	2011/08/16 23:44:58	1.199
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.195 2011/08/02 01:07:26 schwarze Exp $
+.\"	$Id: mdoc.7,v 1.199 2011/08/16 23:44:58 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: August 2 2011 $
+.Dd $Mdocdate: August 16 2011 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -471,6 +471,21 @@ Print verbose information.
 .Ed
 .Pp
 Manuals not documenting a command won't include the above fragment.
+.Pp
+Since the
+.Em DESCRIPTION
+section usually contains most of the text of a manual, longer manuals
+often use the
+.Sx \&Ss
+macro to form subsections.
+In very long manuals, the
+.Em DESCRIPTION
+may be split into multiple sections, each started by an
+.Sx \&Sh
+macro followed by a non-standard section name, and each having
+several subsections, like in the present
+.Nm
+manual.
 .It Em IMPLEMENTATION NOTES
 Implementation-specific notes should be kept here.
 This is useful when implementing standard functions that may have side
@@ -532,7 +547,13 @@ This section should exist for most manuals.
 Cross-references should conventionally be ordered first by section, then
 alphabetically.
 .Pp
+References to other documentation concerning the topic of the manual page,
+for example authoritative books or journal articles, may also be
+provided in this section.
+.Pp
 See
+.Sx \&Rs
+and
 .Sx \&Xr .
 .It Em STANDARDS
 References any standards implemented or used.
@@ -543,7 +564,8 @@ section should be used instead.
 See
 .Sx \&St .
 .It Em HISTORY
-A brief history of the subject, including where support first appeared.
+A brief history of the subject, including where it was first implemented,
+and when it was ported to or reimplemented for the operating system at hand.
 .It Em AUTHORS
 Credits to the person or persons who wrote the code and/or documentation.
 Authors should generally be noted by both name and email address.
@@ -664,11 +686,11 @@ has multiple heads.
 .Pp
 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX"
 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
-.It Sx \&It  Ta    \&No     Ta    Yes      Ta    closed by Sx \&It , Sx \&El
-.It Sx \&Nd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
-.It Sx \&Nm  Ta    \&No     Ta  Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
-.It Sx \&Sh  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
-.It Sx \&Ss  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh , Sx \&Ss
+.It Sx \&It Ta \&No Ta Yes  Ta closed by Sx \&It , Sx \&El
+.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
+.It Sx \&Nm Ta \&No Ta Yes  Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
+.It Sx \&Sh Ta \&No Ta Yes  Ta closed by Sx \&Sh
+.It Sx \&Ss Ta \&No Ta Yes  Ta closed by Sx \&Sh , Sx \&Ss
 .El
 .Pp
 Note that the
@@ -1037,6 +1059,8 @@ Examples:
 .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 +1131,17 @@ If an argument is not provided, the string
 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, use
+.Sx \&Fl
+or
+.Sx \&Cm .
 .Ss \&At
 Formats an AT&T version.
 Accepts one optional argument:
@@ -1166,20 +1198,27 @@ The
 must be one of the following:
 .Bl -tag -width 13n -offset indent
 .It Fl centered
-Centre-justify each line.
+Produce one output line from each input line, and centre-justify each line.
 Using this display type is not recommended; many
 .Nm
 implementations render it poorly.
 .It Fl filled
-Left- and right-justify the block.
+Change the positions of line breaks to fill each line, and left- and
+right-justify the resulting block.
 .It Fl literal
-Do not justify the block at all.
+Produce one output line from each input line,
+and do not justify the block at all.
 Preserve white space as it appears in the input.
+Always use a constant-width font.
+Use this for displaying source code.
 .It Fl ragged
-Only left-justify the block.
+Change the positions of line breaks to fill each line, and left-justify
+the resulting block.
 .It Fl unfilled
-An alias for
-.Fl literal .
+The same as
+.Fl literal ,
+but using the same font as for normal text, which is a variable width font
+if supported by the output device.
 .El
 .Pp
 The
@@ -1195,7 +1234,7 @@ which may be one of the following:
 .It
 One of the pre-defined strings
 .Cm indent ,
-the width of standard indentation;
+the width of a standard indentation (six constant width characters);
 .Cm indent-two ,
 twice
 .Cm indent ;
@@ -1372,9 +1411,12 @@ except that dashes are used in place of bullets.
 Like
 .Fl inset ,
 except that item heads are not parsed for macro invocations.
-.\" but with additional formatting to the head.
+Most often used in the
+.Em DIAGNOSTICS
+section with error constants in the item heads.
 .It Fl enum
 A numbered list.
+No item heads can be specified.
 Formatted like
 .Fl bullet ,
 except that cardinal numbers are used in place of bullets,
@@ -1414,6 +1456,13 @@ this head on the same output line.
 Otherwise, the body starts on the output line following the head.
 .El
 .Pp
+Lists may be nested within lists and displays.
+Nesting of
+.Fl column
+and
+.Fl enum
+lists may not be portable.
+.Pp
 See also
 .Sx \&El
 and
@@ -1490,12 +1539,13 @@ and
 .Sx \&Ux .
 .Ss \&Bt
 Prints
-.Dq is currently in beta test .
+.Dq is currently in beta test.
 .Ss \&Bx
 Format the BSD version provided as an argument, or a default value if no
 argument is provided.
 .Pp
 Examples:
+.Dl \&.Bx 4.3 Tahoe
 .Dl \&.Bx 4.4
 .Dl \&.Bx
 .Pp
@@ -1512,6 +1562,7 @@ and
 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 +1575,17 @@ declarations.
 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
@@ -1851,9 +1905,12 @@ See also
 and
 .Sx \&It .
 .Ss \&Em
-Denotes text that should be emphasised.
+Denotes text that should be
+.Em emphasised .
 Note that this is a presentation term and should not be used for
 stylistically decorating technical terms.
+Depending on the output device, this is usually represented
+using an italic font or underlined characters.
 .Pp
 Examples:
 .Dl \&.Em Warnings!
@@ -1861,9 +1918,10 @@ Examples:
 .Pp
 See also
 .Sx \&Bf ,
-.Sx \&Sy ,
+.Sx \&Li ,
+.Sx \&No ,
 and
-.Sx \&Li .
+.Sx \&Sy .
 .Ss \&En
 This macro is obsolete and not implemented in
 .Xr mandoc 1 .
@@ -1882,6 +1940,7 @@ will emulate
 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
@@ -1906,6 +1965,7 @@ for general constants.
 .Ss \&Ex
 Insert a standard sentence regarding command exit values of 0 on success
 and >0 on failure.
+This is most often used in section 1, 6, and 8 manual pages.
 Its syntax is as follows:
 .Pp
 .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
@@ -1966,7 +2026,7 @@ See also
 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 \-
@@ -1976,10 +2036,11 @@ If the argument is a macro, a hyphen is prefixed to th
 output.
 .Pp
 Examples:
-.Dl \&.Fl a b c
-.Dl \&.Fl \&Pf a b
-.Dl \&.Fl
-.Dl \&.Op \&Fl o \&Ns \&Ar file
+.Dl ".Fl R Op Fl H | L | P"
+.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
+.Dl ".Fl type Cm d Fl name Pa CVS"
+.Dl ".Fl Ar signal_number"
+.Dl ".Fl o Fl"
 .Pp
 See also
 .Sx \&Cm .
@@ -1996,11 +2057,16 @@ Its syntax is as follows:
 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
@@ -2010,7 +2076,8 @@ When referring to a function documented in another man
 .Sx \&Xr
 instead.
 See also
-.Sx MANUAL STRUCTURE
+.Sx MANUAL STRUCTURE ,
+.Sx \&Fo ,
 and
 .Sx \&Ft .
 .Ss \&Fo
@@ -2037,6 +2104,7 @@ Invocations usually occur in the following context:
 A
 .Sx \&Fo
 scope is closed by
+.Sx \&Fc .
 .Pp
 See also
 .Sx MANUAL STRUCTURE ,
@@ -2045,13 +2113,23 @@ See also
 and
 .Sx \&Ft .
 .Ss \&Fr
-This macro is obsolete and not implemented.
+This macro is obsolete and not implemented in
+.Xr mandoc 1 .
+.Pp
+It was used to show function return values.
+The syntax was:
+.Pp
+.Dl Pf . Sx \&Fr Ar value
 .Ss \&Ft
 A function type.
 Its syntax is as follows:
 .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
@@ -2084,7 +2162,13 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Hf
-This macro is obsolete and not implemented.
+This macro is not implemented in
+.Xr mandoc 1 .
+.Pp
+It was used to include the contents of a (header) file literally.
+The syntax was:
+.Pp
+.Dl Pf . Sx \&Hf Ar filename
 .Ss \&Ic
 Designate an internal or interactive command.
 This is similar to
@@ -2092,6 +2176,7 @@ This is similar to
 but used for instructions rather than values.
 .Pp
 Examples:
+.Dl \&.Ic :wq
 .Dl \&.Ic hash
 .Dl \&.Ic alias
 .Pp
@@ -2106,15 +2191,17 @@ macro is used when referring to specific instructions.
 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 .
@@ -2220,15 +2307,21 @@ Examples:
 .Dl \&.Lb libz
 .Dl \&.Lb mdoc
 .Ss \&Li
-Denotes text that should be in a literal font mode.
+Denotes text that should be in a
+.Li literal
+font mode.
 Note that this is a presentation term and should not be used for
 stylistically decorating technical terms.
 .Pp
+On terminal output devices, this is often indistinguishable from
+normal text.
+.Pp
 See also
 .Sx \&Bf ,
-.Sx \&Sy ,
+.Sx \&Em ,
+.Sx \&No ,
 and
-.Sx \&Em .
+.Sx \&Sy .
 .Ss \&Lk
 Format a hyperlink.
 Its syntax is as follows:
@@ -2272,8 +2365,8 @@ section subsequent the
 macro.
 .Pp
 Examples:
-.Dl \&.Sx \&Nd mdoc language reference
-.Dl \&.Sx \&Nd format and display UNIX manuals
+.Dl Pf . Sx \&Nd mdoc language reference
+.Dl Pf . Sx \&Nd format and display UNIX manuals
 .Pp
 The
 .Sx \&Nd
@@ -2325,21 +2418,44 @@ macro rather than
 .Sx \&Nm
 to mark up the name of the manual page.
 .Ss \&No
-A
-.Dq noop
-macro used to terminate prior macro contexts.
+Normal text.
+Closes the scope of any preceding in-line macro.
+When used after physical formatting macros like
+.Sx \&Em
+or
+.Sx \&Sy ,
+switches back to the standard font face and weight.
+Can also be used to embed plain text strings in macro lines
+using semantic annotation macros.
 .Pp
 Examples:
-.Dl \&.Sx \&Fl ab \&No cd \&Fl ef
+.Dl ".Em italic , Sy bold , No and roman"
+.Pp
+.Bd -literal -offset indent -compact
+\&.Sm off
+\&.Cm :C No / Ar pattern No / Ar replacement No /
+\&.Sm on
+.Ed
+.Pp
+See also
+.Sx \&Em ,
+.Sx \&Li ,
+and
+.Sx \&Sy .
 .Ss \&Ns
-Suppress a space.
-Following invocation, text is interpreted as free-form text until a
-macro is encountered.
+Suppress a space between the output of the preceding macro
+and the following text or macro.
+Following invocation, input is interpreted as normal text
+just like after an
+.Sx \&No
+macro.
 .Pp
 This has no effect when invoked at the start of a macro line.
 .Pp
 Examples:
-.Dl \&.Fl o \&Ns \&Ar output
+.Dl ".Ar name Ns = Ns Ar value"
+.Dl ".Cm :M Ns Ar pattern"
+.Dl ".Fl o Ns Ar output"
 .Pp
 See also
 .Sx \&No
@@ -2379,9 +2495,11 @@ Examples:
 \&.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
@@ -2415,10 +2533,13 @@ See also
 and
 .Sx \&Dt .
 .Ss \&Ot
-Unknown usage.
+This macro is obsolete and not implemented in
+.Xr mandoc 1 .
 .Pp
-.Em Remarks :
-this macro has been deprecated.
+Historical
+.Xr mdoc 7
+packages described it as
+.Dq "old function type (FORTRAN)" .
 .Ss \&Ox
 Format the
 .Ox
@@ -2439,9 +2560,9 @@ See also
 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:
@@ -2454,19 +2575,25 @@ See also
 Close parenthesised context opened by
 .Sx \&Po .
 .Ss \&Pf
-Removes the space
+Removes the space between its argument
 .Pq Dq prefix
-between its arguments.
+and the following macro.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. \&Pf Ar prefix suffix
+.D1 .Pf Ar prefix macro arguments ...
 .Pp
-The
-.Ar suffix
-argument may be a macro.
+This is equivalent to:
 .Pp
+.D1 .No Ar prefix No \&Ns Ar macro arguments ...
+.Pp
 Examples:
-.Dl \&.Pf \e. \&Sx \&Pf \&Ar prefix suffix
+.Dl ".Pf $ Ar variable_name"
+.Dl ".Pf 0x Ar hex_digits"
+.Pp
+See also
+.Sx \&Ns
+and
+.Sx \&Sm .
 .Ss \&Po
 Multi-line version of
 .Sx \&Pq .
@@ -2474,6 +2601,18 @@ Multi-line version of
 Break a paragraph.
 This will assert vertical space between prior and subsequent macros
 and/or text.
+.Pp
+Paragraph breaks are not needed before or after
+.Sx \&Sh
+or
+.Sx \&Ss
+macros or before displays
+.Pq Sx \&Bd
+or lists
+.Pq Sx \&Bl
+unless the
+.Fl compact
+flag is given.
 .Ss \&Pq
 Parenthesised enclosure.
 .Pp
@@ -2493,7 +2632,7 @@ Multi-line version of
 .Sx \&Qq .
 .Ss \&Qq
 Encloses its arguments in
-.Dq typewriter
+.Qq typewriter
 double-quotes.
 Consider using
 .Sx \&Dq .
@@ -2580,6 +2719,9 @@ custom sections be used.
 .Pp
 Section names should be unique so that they may be keyed by
 .Sx \&Sx .
+Although this macro is parsed, it should not consist of child node or it
+may not be linked with
+.Sx \&Sx .
 .Pp
 See also
 .Sx \&Pp ,
@@ -2604,7 +2746,7 @@ Multi-line version of
 .Sx \&Sq .
 .Ss \&Sq
 Encloses its arguments in
-.Dq typewriter
+.Sq typewriter
 single-quotes.
 .Pp
 See also
@@ -2613,16 +2755,21 @@ See also
 and
 .Sx \&So .
 .Ss \&Ss
-Begin a new sub-section.
+Begin a new subsection.
 Unlike with
 .Sx \&Sh ,
-there's no convention for sub-sections.
-Conventional sections, as described in
-.Sx MANUAL STRUCTURE ,
-rarely have sub-sections.
+there is no convention for the naming of subsections.
+Except
+.Em DESCRIPTION ,
+the conventional sections described in
+.Sx MANUAL STRUCTURE
+rarely have subsections.
 .Pp
 Sub-section names should be unique so that they may be keyed by
 .Sx \&Sx .
+Although this macro is parsed, it should not consist of child node or it
+may not be linked with
+.Sx \&Sx .
 .Pp
 See also
 .Sx \&Pp ,
@@ -2704,6 +2851,7 @@ The following standards are recognised:
 .St -xpg4
 .It \-xpg4.2
 .St -xpg4.2
+.It \-xpg4.3
 .St -xpg4.3
 .It \-xbd5
 .St -xbd5
@@ -2727,8 +2875,8 @@ The following standards are recognised:
 .St -svid4
 .El
 .Ss \&Sx
-Reference a section or sub-section.
-The referenced section or sub-section name must be identical to the
+Reference a section or subsection in the same manual page.
+The referenced section or subsection name must be identical to the
 enclosed argument, including whitespace.
 .Pp
 Examples:
@@ -2746,9 +2894,10 @@ stylistically decorating technical terms.
 .Pp
 See also
 .Sx \&Bf ,
+.Sx \&Em ,
 .Sx \&Li ,
 and
-.Sx \&Em .
+.Sx \&No .
 .Ss \&Ta
 Table cell separator in
 .Sx \&Bl Fl column
@@ -2757,11 +2906,16 @@ lists; can only be used below
 .Ss \&Tn
 Format a tradename.
 .Pp
+Since this macro is often implemented to use a small caps font,
+it has historically been used for acronyms (like ASCII) as well.
+Such usage is not recommended because it would use the same macro
+sometimes for semantical annotation, sometimes for physical formatting.
+.Pp
 Examples:
 .Dl \&.Tn IBM
 .Ss \&Ud
 Prints out
-.Dq currently under development .
+.Dq currently under development.
 .Ss \&Ux
 Format the UNIX name.
 Accepts no argument.
@@ -2791,11 +2945,14 @@ This is also used for indicating global variables in t
 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 ,
@@ -3054,7 +3211,7 @@ This is not supported by mandoc.
 .Xr mandoc 1 ,
 .Xr eqn 7 ,
 .Xr man 7 ,
-.Xr mandoc_char 7
+.Xr mandoc_char 7 ,
 .Xr roff 7 ,
 .Xr tbl 7
 .Sh HISTORY