===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.200
retrieving revision 1.210
diff -u -p -r1.200 -r1.210
--- mandoc/mdoc.7	2011/08/17 20:34:53	1.200
+++ mandoc/mdoc.7	2011/09/18 07:57:16	1.210
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.200 2011/08/17 20:34:53 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.210 2011/09/18 07:57:16 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 17 2011 $
+.Dd $Mdocdate: September 18 2011 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -63,16 +63,24 @@ and
 .Sx Special Characters .
 .Ss Comments
 Text following an escaped double-quote
-.Sq \e\*q ,
+.Sq \e\(dq ,
 whether in a macro or text line, is ignored to the end of
 line.
 A macro line beginning with a control character and comment escape
-.Sq \&.\e\*q
+.Sq \&.\e\(dq
 is also ignored.
 Furthermore,
 macro lines with only a control character and optional trailing
 whitespace are
 stripped from input.
+.Pp
+Examples:
+.Bd -literal -offset indent -compact
+\&.\e\(dq This is a comment line.
+\&.\e\(dq The next line is ignored:
+\&.
+\&.Em Emphasis \e\(dq This is also a comment.
+.Ed
 .Ss Special Characters
 Special characters are used to encode special glyphs and are rendered
 differently across output media.
@@ -89,10 +97,10 @@ or a single one character sequence.
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact
-.It \e(em
-em dash
-.It \ee
-backslash
+.It Li \e(em
+Two-letter em dash escape.
+.It Li \ee
+One-letter backslash escape.
 .El
 .Pp
 See
@@ -117,10 +125,10 @@ scope.
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact
-.It \efBbold\efR
-write in bold, then switch to regular
-.It \efIitalic\efP
-write in italic, then return to previous
+.It Li \efBbold\efR
+Write in bold, then switch to regular font mode.
+.It Li \efIitalic\efP
+Write in italic, then return to previous font mode.
 .El
 .Pp
 Text decoration is
@@ -143,10 +151,10 @@ and N-character
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact
-.It \e*(Am
-ampersand
-.It \e*(Ba
-vertical bar
+.It Li \e*(Am
+Two-letter ampersand predefined string.
+.It Li \e*q
+One-letter double-quote predefined string.
 .El
 .Pp
 These strings are set using
@@ -168,44 +176,43 @@ In the rare case that a blank character is needed at t
 input line, it may be forced by
 .Sq \e\ \e& .
 .Pp
+In general, space characters can be rendered as literal
+characters by using non-breaking space escapes or
+.Sx Quotation .
+.Pp
 Blank text lines, which may include whitespace, are only permitted
 within literal contexts.
 If the first character of a text line is a space, that line is printed
 with a leading newline.
 .Ss Quotation
-Macro arguments may be quoted with double-quotes; in this case,
-whitespace within the quotes is retained as part of the argument.
-For example,
+Macro arguments may be quoted with double-quotes to so that the
+enclosed text is one literal term.
+Quoted text, even if whitespace or if it would cause a macro invocation
+when unquoted, is considered literal text.
 .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
-.Sq Op "Fl a" :
-.Bd -literal -offset indent
-\&.Op "Fl a"
-.Ed
-.Pp
-In text lines, quotes are regarded as opaque text.
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li .Fn strlen \(dqconst char *s\(dq
+Group arguments
+.Qq const char *s
+into one function argument.
+If unspecified,
+.Qq const ,
+.Qq char ,
+and
+.Qq *s
+would be considered separate arguments.
+.Pq See Sx \&Fn .
+.It Li .Op \(dqFl a\(dq
+Consider
+.Qq \&Fl a
+as literal text instead of a flag macro.
+.Pq Aee Sx \&Op , \&Fl .
+.El
 .Ss Scaling Widths
 Many macros support scaled widths for their arguments.
 The syntax for a scaled width is
@@ -257,12 +264,12 @@ See
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact
-.It \&.Bl -tag -width 2i
+.It Li \&.Bl -tag -width 2i
 two-inch tagged list indentation
 .Pq see Sx \&Bl
-.It \&.br 2v
+.It Li \&.sp 2v
 two vertical spaces
-.Pq see Sx \&br
+.Pq see Sx \&sp
 .El
 .Ss Sentence Spacing
 Sentences should terminate at the end of an input line.
@@ -324,9 +331,9 @@ file for a utility
 \&.Sh NAME
 \&.Nm progname
 \&.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.
+\&.\e\(dq .Sh LIBRARY
+\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq Not used in OpenBSD.
 \&.Sh SYNOPSIS
 \&.Nm progname
 \&.Op Fl options
@@ -335,29 +342,29 @@ file for a utility
 The
 \&.Nm
 utility processes files ...
-\&.\e\*q .Sh IMPLEMENTATION NOTES
-\&.\e\*q Not used in OpenBSD.
-\&.\e\*q .Sh RETURN VALUES
-\&.\e\*q For sections 2, 3, & 9 only.
-\&.\e\*q .Sh ENVIRONMENT
-\&.\e\*q For sections 1, 6, 7, & 8 only.
-\&.\e\*q .Sh FILES
-\&.\e\*q .Sh EXIT STATUS
-\&.\e\*q For sections 1, 6, & 8 only.
-\&.\e\*q .Sh EXAMPLES
-\&.\e\*q .Sh DIAGNOSTICS
-\&.\e\*q For sections 1, 4, 6, 7, & 8 only.
-\&.\e\*q .Sh ERRORS
-\&.\e\*q For sections 2, 3, & 9 only.
-\&.\e\*q .Sh SEE ALSO
-\&.\e\*q .Xr foobar 1
-\&.\e\*q .Sh STANDARDS
-\&.\e\*q .Sh HISTORY
-\&.\e\*q .Sh AUTHORS
-\&.\e\*q .Sh CAVEATS
-\&.\e\*q .Sh BUGS
-\&.\e\*q .Sh SECURITY CONSIDERATIONS
-\&.\e\*q Not used in OpenBSD.
+\&.\e\(dq .Sh IMPLEMENTATION NOTES
+\&.\e\(dq Not used in OpenBSD.
+\&.\e\(dq .Sh RETURN VALUES
+\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq .Sh ENVIRONMENT
+\&.\e\(dq For sections 1, 6, 7, & 8 only.
+\&.\e\(dq .Sh FILES
+\&.\e\(dq .Sh EXIT STATUS
+\&.\e\(dq For sections 1, 6, & 8 only.
+\&.\e\(dq .Sh EXAMPLES
+\&.\e\(dq .Sh DIAGNOSTICS
+\&.\e\(dq For sections 1, 4, 6, 7, & 8 only.
+\&.\e\(dq .Sh ERRORS
+\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq .Sh SEE ALSO
+\&.\e\(dq .Xr foobar 1
+\&.\e\(dq .Sh STANDARDS
+\&.\e\(dq .Sh HISTORY
+\&.\e\(dq .Sh AUTHORS
+\&.\e\(dq .Sh CAVEATS
+\&.\e\(dq .Sh BUGS
+\&.\e\(dq .Sh SECURITY CONSIDERATIONS
+\&.\e\(dq Not used in OpenBSD.
 .Ed
 .Pp
 The sections in an
@@ -438,8 +445,8 @@ macros should follow C header-file conventions.
 .Pp
 And for the third, configurations (section 4):
 .Bd -literal -offset indent
-\&.Cd \*qit* at isa? port 0x2e\*q
-\&.Cd \*qit* at isa? port 0x4e\*q
+\&.Cd \(dqit* at isa? port 0x2e\(dq
+\&.Cd \(dqit* at isa? port 0x4e\(dq
 .Ed
 .Pp
 Manuals not in these sections generally don't need a
@@ -682,8 +689,7 @@ contain a head.
 \(lBbody...\(rB
 \&.Yc
 .Ed
-.Pp
-.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXX"
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&Bd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ed
 .It Sx \&Bf  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ef
@@ -715,8 +721,7 @@ has multiple heads.
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
 \(lBbody...\(rB
 .Ed
-.Pp
-.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX"
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
 .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
@@ -751,8 +756,7 @@ and/or tail
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
 \(lBbody...\(rB \&Yc \(lBtail...\(rB
 .Ed
-.Pp
-.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&Ac  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Ao
 .It Sx \&Ao  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Ac
@@ -785,8 +789,7 @@ end of the line.
 .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
 .Ed
-.Pp
-.Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent
+.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
 .It Em Macro Ta Em Callable Ta Em Parsed
 .It Sx \&Aq  Ta    Yes      Ta    Yes
 .It Sx \&Bq  Ta    Yes      Ta    Yes
@@ -821,8 +824,7 @@ in
 lists.
 It delimits blocks representing table cells;
 these blocks have bodies, but no heads.
-.Pp
-.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&Ta  Ta    Yes      Ta    Yes    Ta closed by Sx \&Ta , Sx \&It
 .El
@@ -840,8 +842,7 @@ then the macro accepts an arbitrary number of argument
 
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
 .Ed
-.Pp
-.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset indent
+.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
 .It Sx \&%A  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%B  Ta    \&No     Ta    \&No     Ta    >0
@@ -1002,6 +1003,130 @@ in the same way as a plain
 .Sq \&|
 character.
 Using this predefined string is not recommended in new manuals.
+.Sh MACRO OVERVIEW
+This overview is sorted such that macros of similar purpose are listed
+together, to help find the best macro for any given purpose.
+Deprecated macros are not included in the overview, but can be found
+in the alphabetical reference below.
+.Ss Document preamble and NAME section macros
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Dd Ta document date: Cm $Mdocdate: September 18 2011 $ | Ar month day , year
+.It Sx \&Dt Ta document title: Ar TITLE section Op Ar volume | arch
+.It Sx \&Os Ta operating system version: Op Ar system Op Ar version
+.It Sx \&Nm Ta document name (one argument)
+.It Sx \&Nd Ta document description (one line)
+.El
+.Ss Sections and cross references
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Sh Ta section header (one line)
+.It Sx \&Ss Ta subsection header (one line)
+.It Sx \&Sx Ta internal cross reference to a section or subsection
+.It Sx \&Xr Ta cross reference to another manual page: Ar name section
+.It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments)
+.El
+.Ss Displays and lists
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Bd , \&Ed Ta display block:
+.Fl Ar type
+.Op Fl offset Ar width
+.Op Fl compact
+.It Sx \&D1 Ta indented display (one line)
+.It Sx \&Dl Ta indented literal display (one line)
+.It Sx \&Bl , \&El Ta list block:
+.Fl Ar type
+.Op Fl width Ar val
+.Op Fl offset Ar val
+.Op Fl compact
+.It Sx \&It Ta list item (syntax depends on Fl Ar type )
+.It Sx \&Ta Ta table cell separator in Sx Bl Fl column No lists
+.It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references)
+.El
+.Ss Spacing control
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Pf Ta prefix, no following horizontal space (one argument)
+.It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
+.It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
+.It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off
+.It Sx \&Bk , \&Ek Ta keep block: Fl words
+.It Sx \&br Ta force output line break in text mode (no arguments)
+.It Sx \&sp Ta force vertical space: Op Ar height
+.El
+.Ss Semantic markup for command line utilities:
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility
+.It Sx \&Fl Ta command line options (flags) (>=0 arguments)
+.It Sx \&Cm Ta command modifier (>0 arguments)
+.It Sx \&Ar Ta command arguments (>=0 arguments)
+.It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)
+.It Sx \&Ic Ta internal or interactive command (>0 arguments)
+.It Sx \&Ev Ta environmental variable (>0 arguments)
+.It Sx \&Pa Ta file system path (>=0 arguments)
+.El
+.Ss Semantic markup for function libraries:
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Lb Ta function library (one argument)
+.It Sx \&In Ta include file (one argument)
+.It Sx \&Ft Ta function type (>0 arguments)
+.It Sx \&Fo , \&Fc Ta function block: Ar funcname
+.It Sx \&Fn Ta function name:
+.Op Ar functype
+.Ar funcname
+.Oo
+.Op Ar argtype
+.Ar argname
+.Oc
+.It Sx \&Fa Ta function argument (>0 arguments)
+.It Sx \&Vt Ta variable type (>0 arguments)
+.It Sx \&Va Ta variable name (>0 arguments)
+.It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments)
+.It Sx \&Er Ta error constant (>0 arguments)
+.It Sx \&Ev Ta environmental variable (>0 arguments)
+.El
+.Ss Various semantic markup:
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&An Ta author name (>0 arguments)
+.It Sx \&Lk Ta hyperlink: Ar uri Op Ar name
+.It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address
+.It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
+.It Sx \&Ad Ta memory address (>0 arguments)
+.It Sx \&Ms Ta mathematical symbol (>0 arguments)
+.It Sx \&Tn Ta tradename (>0 arguments)
+.El
+.Ss Physical markup
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)
+.It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)
+.It Sx \&Li Ta typewriter font (literal) (>0 arguments)
+.It Sx \&No Ta return to roman font (normal) (no arguments)
+.It Sx \&Bf , \&Ef Ta font block:
+.Op Fl Ar type | Cm \&Em | \&Li | \&Sy
+.El
+.Ss Physical enclosures
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
+.It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
+.It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
+.It Sx \&Ql Ta single-quoted literal text: Ql text
+.It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
+.It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
+.It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
+.It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text
+.It Sx \&Eo , \&Ec Ta generic enclosure
+.El
+.Ss Text production
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
+.It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
+.It Sx \&St Ta reference to a standards document (one argument)
+.It Sx \&Ux Ta Ux
+.It Sx \&At Ta At
+.It Sx \&Bx Ta Bx
+.It Sx \&Bsx Ta Bsx
+.It Sx \&Nx Ta Nx
+.It Sx \&Fx Ta Fx
+.It Sx \&Ox Ta Ox
+.It Sx \&Dx Ta Dx
+.El
 .Sh REFERENCE
 This section is a canonical reference of all macros, arranged
 alphabetically.
@@ -2095,8 +2220,8 @@ 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 \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
+.Dl \&.Fn funcname \(dqint arg0\(dq
 .Dl \&.Fn funcname arg0
 .Pp
 .Bd -literal -offset indent -compact
@@ -2301,7 +2426,7 @@ line itself; on following lines, only the
 .Sx \&Ta
 macro can be used to delimit cells, and
 .Sx \&Ta
-is only recognized as a macro when called by other macros,
+is only recognised as a macro when called by other macros,
 not as the first macro on a line.
 .Pp
 Note that quoted strings may span tab-delimited cells on an
@@ -2361,7 +2486,7 @@ Its syntax is as follows:
 .D1 Pf \. Sx \&Lk Ar uri Op Ar name
 .Pp
 Examples:
-.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q
+.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
 .Dl \&.Lk http://bsd.lv
 .Pp
 See also
@@ -2875,6 +3000,8 @@ The following standards are recognised:
 .St -ieee754
 .It \-iso8802-3
 .St -iso8802-3
+.It \-iso8601
+.St -iso8601
 .It \-ieee1275-94
 .St -ieee1275-94
 .It \-xpg3
@@ -3093,7 +3220,7 @@ Newer groff and mandoc print
 and the arguments.
 .It
 .Sx \&Bl Fl column
-does not recognize trailing punctuation characters when they immediately
+does not recognise trailing punctuation characters when they immediately
 precede tabulator characters, but treats them as normal text and
 outputs a space before them.
 .It
@@ -3205,7 +3332,7 @@ The following features are unimplemented in mandoc:
 .Fl offset Ar center
 and
 .Fl offset Ar right .
-Groff does not implement centered and flush-right rendering either,
+Groff does not implement centred and flush-right rendering either,
 but produces large indentations.
 .It
 The
@@ -3261,4 +3388,5 @@ utility written by Kristaps Dzonsons appeared in
 The
 .Nm
 reference was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.An Kristaps Dzonsons ,
+.Mt kristaps@bsd.lv .