===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.120
retrieving revision 1.132
diff -u -p -r1.120 -r1.132
--- mandoc/mdoc.7	2010/06/06 10:49:56	1.120
+++ mandoc/mdoc.7	2010/07/06 10:55:50	1.132
@@ -1,6 +1,7 @@
-.\"	$Id: mdoc.7,v 1.120 2010/06/06 10:49:56 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.132 2010/07/06 10:55:50 kristaps Exp $
 .\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -14,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: June 6 2010 $
+.Dd $Mdocdate: July 6 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -55,7 +56,7 @@ Text following a
 whether in a macro or free-form text line, is ignored to the end of
 line.  A macro line with only a control character and comment escape,
 .Sq \&.\e" ,
-is also ignored.  Macro lines with only a control charater and optionally
+is also ignored.  Macro lines with only a control character and optionally
 whitespace are stripped from input.
 .Ss Reserved Characters
 Within a macro line, the following characters are reserved:
@@ -167,7 +168,7 @@ also defined a set of package-specific
 .Dq predefined strings ,
 which, like
 .Sx Special Characters ,
-demark special output characters and strings by way of input codes.
+mark special output characters and strings by way of input codes.
 Predefined strings are escaped with the slash-asterisk,
 .Sq \e* :
 single-character
@@ -333,8 +334,11 @@ must be the NAME section, consisting of at least one
 followed by
 .Sx \&Nd .
 .Pp
-Following that, convention dictates specifying at least the SYNOPSIS and
-DESCRIPTION sections, although this varies between manual sections.
+Following that, convention dictates specifying at least the
+.Em SYNOPSIS
+and
+.Em DESCRIPTION
+sections, although this varies between manual sections.
 .Pp
 The following is a well-formed skeleton
 .Nm
@@ -450,13 +454,44 @@ And for the third, configurations (section 4):
 Manuals not in these sections generally don't need a
 .Em SYNOPSIS .
 .Pp
-See
-.Sx \&Op ,
+Some macros are displayed differently in the
+.Em SYNOPSIS
+section, particularly
+.Sx \&Nm ,
 .Sx \&Cd ,
+.Sx \&Fd ,
 .Sx \&Fn ,
-.Sx \&Ft ,
+.Sx \&Fo ,
+.Sx \&In ,
+.Sx \&Vt ,
 and
-.Sx \&Vt .
+.Sx \&Ft .
+All of these macros are output on their own line.  If two such
+dissimilar macros are pair-wise invoked (except for
+.Sx \&Ft
+before
+.Sx \&Fo
+or
+.Sx \&Fn ) ,
+they are separated by a vertical space, unless in the case of
+.Sx \&Fo ,
+.Sx \&Fn ,
+and
+.Sx \&Ft ,
+which are always separated by vertical space.
+.Pp
+When text and macros following an
+.Sx \&Nm
+macro starting an input line span multiple output lines,
+all output lines but the first will be indented to align
+with the text immediately following the
+.Sx \&Nm
+macro, up to the next
+.Sx \&Nm ,
+.Sx \&Sx ,
+or
+.Sx \&Ss
+macro or the end of an enclosing block, whichever comes first.
 .It Em DESCRIPTION
 This expands upon the brief, one-line description in
 .Em NAME .
@@ -651,9 +686,20 @@ has multiple heads.
 .It Em Macro Ta Em Callable Ta Em Parsable 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
 .El
+.Pp
+Note that the
+.Sx \&Nm
+macro is a
+.Sx Block full-implicit
+macro only when invoked as the first macro
+in a
+.Em SYNOPSIS
+section line, else it is
+.Sx In-line .
 .Ss Block partial-explicit
 Like block full-explicit, but also with single-line scope.
 Each has at least a body and, in limited circumstances, a head
@@ -952,7 +998,7 @@ See also
 .Sx \&Aq .
 .Ss \&Ap
 Inserts an apostrophe without any surrounding white-space.
-This is generally used as a grammatic device when referring to the verb
+This is generally used as a grammatical device when referring to the verb
 form of a function:
 .Bd -literal -offset indent
 \&.Fn execve Ap d
@@ -1018,6 +1064,14 @@ Closes a
 block.  Does not have any tail arguments.
 .Ss \&Bd
 Begins a display block.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Bd
+.Fl type
+.Op Fl offset Ar width
+.Op Fl compact
+.Ed
+.Pp
 A display is collection of macros or text which may be collectively
 offset or justified in a manner different from that
 of the enclosing context.
@@ -1042,9 +1096,9 @@ Centre-justify each line.
 The type must be provided first.
 Secondary arguments are as follows:
 .Bl -tag -width 12n -offset indent
-.It Fl offset Ar width
+.It Fl offset Ar val
 Offset by the value of
-.Ar width ,
+.Ar val ,
 which is interpreted as one of the following, specified in order:
 .Bl -item
 .It
@@ -1055,7 +1109,7 @@ the width of standard indentation;
 twice
 .Ar indent ;
 .Ar left ,
-which has no effect ;
+which has no effect;
 .Ar right ,
 which justifies to the right margin; and
 .Ar center ,
@@ -1073,16 +1127,9 @@ As a scaling unit following the syntax described in
 As the calculated string length of the opaque string.
 .El
 .Pp
-If unset, it will revert to the value of
-.Ar 8n
-as described in
-.Sx Scaling Widths .
+If not provided an argument, it will be ignored.
 .It Fl compact
 Do not assert a vertical space before the block.
-.It Fl file Ar file
-Prepend the file
-.Ar file
-before any text or macros within the block.
 .El
 .Pp
 Examples:
@@ -1097,9 +1144,73 @@ See also
 and
 .Sx \&Dl .
 .Ss \&Bf
+Change the font mode for a scoped block of text.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Bf
+.Oo
+.Fl emphasis | literal | symbolic |
+.Cm \&Em | \&Li | \&Sy
+.Oc
+.Ed
+.Pp
+The
+.Fl emphasis
+and
+.Cm \&Em
+argument are equivalent, as are
+.Fl symbolic
+and
+.Cm \&Sy,
+and
+.Fl literal
+and
+.Cm \&Li .
+Without an argument, this macro does nothing.
+The font mode continues until broken by a new font mode in a nested
+scope or
+.Sx \&Ef
+is encountered.
+.Pp
+See also
+.Sx \&Li ,
+.Sx \&Ef ,
+and
+.Sx \&Sy .
 .Ss \&Bk
+Begins a keep block, containing a collection of macros or text
+to be kept together in the output.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Bk Fl words
+.Pp
+Currently, the only argument implemented is
+.Fl words ,
+requesting to keep together all words of the contained text
+on the same output line.
+Subsequent arguments are ignored.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bk \-words
+\&.Op o Ar output_file
+\&.Ek
+.Ed
+.Pp
+See also
+.Sx \&Ek .
 .Ss \&Bl
 Begins a list composed of one or more list entries.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Bl
+.Fl type
+.Op Fl width Ar val
+.Op Fl offset Ar val
+.Op Fl compact
+.Op HEAD ...
+.Ed
+.Pp
 A list is associated with a type, which is a required argument.
 Other arguments are
 .Fl width ,
@@ -1568,9 +1679,26 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Ec
+Close a scope started by
+.Sx \&Eo .
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Ec Op Cm TERM
+.Pp
+The
+.Cm TERM
+argument is used as the enclosure tail, for example, specifying \e(rq
+will emulate
+.Sx \&Dc .
 .Ss \&Ed
+End a display context started by
+.Sx \&Bd .
 .Ss \&Ef
+Ends a font mode context started by
+.Sx \&Bf .
 .Ss \&Ek
+Ends a keep context started by
+.Sx \&Bk .
 .Ss \&El
 Ends a list context started by
 .Sx \&Bl .
@@ -1588,7 +1716,18 @@ Examples:
 .D1 \&.Em Warnings!
 .D1 \&.Em Remarks :
 .Ss \&En
+This macro is obsolete and not implemented.
 .Ss \&Eo
+An arbitrary enclosure.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Eo Op Cm TERM
+.Pp
+The
+.Cm TERM
+argument is used as the enclosure head, for example, specifying \e(lq
+will emulate
+.Sx \&Do .
 .Ss \&Er
 Display error constants.
 .Pp
@@ -1599,6 +1738,7 @@ Examples:
 See also
 .Sx \&Dv .
 .Ss \&Es
+This macro is obsolete and not implemented.
 .Ss \&Ev
 Environmental variables such as those specified in
 .Xr environ 7 .
@@ -1649,6 +1789,8 @@ Examples:
 See also
 .Sx \&Fo .
 .Ss \&Fc
+Ends a function context started by
+.Sx \&Fo .
 .Ss \&Fd
 Historically used to document include files.
 This usage has been deprecated in favour of
@@ -1656,6 +1798,8 @@ This usage has been deprecated in favour of
 Do not use this macro.
 .Pp
 See also
+.Sx MANUAL STRUCTURE
+and
 .Sx \&In .
 .Ss \&Fl
 Command-line flag.
@@ -1685,10 +1829,7 @@ Its syntax is as follows:
 .Op Oo Cm argtype Oc Cm argname
 .Ed
 .Pp
-If invoked in the
-.Em SYNOPSIS
-section, vertical space is asserted before and after the macro.
-In all cases, the function arguments are surrounded in parenthesis and
+Function arguments are surrounded in parenthesis and
 are delimited by commas.
 If no arguments are specified, blank parenthesis are output.
 .Pp
@@ -1702,9 +1843,7 @@ Examples:
 .Ed
 .Pp
 See also
-.Sx \&Fa ,
-.Sx \&Fo ,
-.Sx \&Fc ,
+.Sx MANUAL STRUCTURE
 and
 .Sx \&Ft .
 .Ss \&Fo
@@ -1728,42 +1867,21 @@ Invocations usually occur in the following context:
 .Pf \. Sx \&Fc
 .Ed
 .Pp
-In the
-.Em SYNOPSIS
-section, a
-.Sx \&Fo
-block is surrounded by vertical space unless
-.Sx \&Ft
-is the prior macro, in which case it is preceded by only a newline.
-.Pp
 A
 .Sx \&Fo
 scope is closed by
 .Pp
 See also
+.Sx MANUAL STRUCTURE ,
 .Sx \&Fa ,
 .Sx \&Fc ,
 and
-.Sx \&Fn .
-.Sx \&Fc .
-.Ss \&Fr
 .Ss \&Ft
 A function type.
 Its syntax is as follows:
 .Pp
 .D1 Pf \. Sx \&Ft Cm functype
 .Pp
-If invoked before a
-.Sx \&Fo
-or
-.Sx \&Fn
-in the
-.Em SYNOPSIS
-section, a line-break will follow.
-Furthermore, if invoked in the
-.Em SYNOPSIS
-section, it will assert vertical space prior to its arguments.
-.Pp
 Examples:
 .D1 \&.Ft int
 .Bd -literal -offset indent -compact
@@ -1772,10 +1890,10 @@ Examples:
 .Ed
 .Pp
 See also
-.Sx \&Fo ,
-.Sx \&Fc ,
+.Sx MANUAL STRUCTURE ,
+.Sx \&Fn ,
 and
-.Sx \&Fn .
+.Sx \&Fo .
 .Ss \&Fx
 Format the FreeBSD version provided as an argument, or a default value
 if no argument is provided.
@@ -1794,7 +1912,24 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Hf
+This macro is obsolete and not implemented.
 .Ss \&Ic
+Designate an internal or interactive command.
+This is similar to
+.Sx \&Cm
+but used for instructions rather than values.
+.Pp
+Examples:
+.D1 \&.Ic hash
+.D1 \&.Ic alias
+.Pp
+Note that using
+.Sx \&Bd No Fl literal
+or
+.Sx \&D1
+is preferred for displaying code; the
+.Sx \&Ic
+macro is used when referring to specific instructions.
 .Ss \&In
 An
 .Qq include
@@ -1804,11 +1939,13 @@ In the
 section (only if invoked as the line macro), the first argument is
 preceded by
 .Qq #include ,
-the arguments is enclosed in angled braces, and a newline is asserted.
-In all other invocations, only angled braces will enclose the argument.
+the arguments is enclosed in angled braces.
 .Pp
-Examples
+Examples:
 .D1 \&.In sys/types
+.Pp
+See also
+.Sx MANUAL STRUCTURE .
 .Ss \&It
 A list item.
 The syntax of this macro depends on the list type.
@@ -1880,12 +2017,12 @@ line itself.
 Subsequent this, only the
 .Sq \&Ta
 pseudo-macro may be used to delimit phrases.
-Furthermore, note that quoted sections propogate over tab-delimited
+Furthermore, note that quoted sections propagate over tab-delimited
 phrases on an
 .Sx \&It ,
 for example,
 .Pp
-.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
+.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
 .Pp
 will preserve the semicolon whitespace except for the last.
 .Pp
@@ -1915,6 +2052,9 @@ Examples:
 .D1 \&.Lb libz
 .D1 \&.Lb mdoc
 .Ss \&Li
+Denotes text that should be in a literal font mode.
+Note that this is a presentation term and should not be used for
+stylistically decorating technical terms.
 .Ss \&Lk
 Format a hyperlink.
 Its syntax is as follows:
@@ -1928,6 +2068,8 @@ Examples:
 See also
 .Sx \&Mt .
 .Ss \&Lp
+Synonym for
+.Sx \&Pp .
 .Ss \&Ms
 .Ss \&Mt
 Format a
@@ -1940,8 +2082,73 @@ Its syntax is as follows:
 Examples:
 .D1 \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd
+A one-line description of the manual's content.
+This may only be invoked in the
+.Em SYNOPSIS
+section subsequent the
+.Sx \&Nm
+macro.
+.Pp
+Examples:
+.D1 \&.Sx \&Nd mdoc language reference
+.D1 \&.Sx \&Nd format and display UNIX manuals
+.Pp
+The
+.Sx \&Nd
+macro technically accepts child macros and terminates with a subsequent
+.Sx \&Sh
+invocation.
+Do not assume this behaviour: some
+.Xr whatis 1
+database generators are not smart enough to parse more than the line
+arguments and will display macros verbatim.
+.Pp
+See also
+.Sx \&Nm .
 .Ss \&Nm
+The name of the manual page, or \(em in particular in section 1, 6,
+and 8 pages \(em of an additional command or feature documented in
+the manual page.
+When first invoked, the
+.Sx \&Nm
+macro expects a single argument, the name of the manual page.
+Usually, the first invocation happens in the
+.Em NAME
+section of the page.
+The specified name will be remembered and used whenever the macro is
+called again without arguments later in the page.
+The
+.Sx \&Nm
+macro uses
+.Sx Block full-implicit
+semantics when invoked as the first macro on an input line in the
+.Em SYNOPSIS
+section; otherwise, it uses ordinary
+.Sx In-line
+semantics.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Sh SYNOPSIS
+\&.Nm cat
+\&.Op Fl benstuv
+\&.Op Ar
+.Ed
+.Pp
+In the
+.Em SYNOPSIS
+of section 2, 3 and 9 manual pages, use the
+.Sx \&Fn
+macro rather than
+.Sx \&Nm
+to mark up the name of the manual page.
 .Ss \&No
+A
+.Qq noop
+macro used to terminate prior macro contexts.
+.Pp
+Examples:
+.D1 \&.Sx \&Fl ab \&No cd \&Fl ef
 .Ss \&Ns
 .Ss \&Nx
 Format the NetBSD version provided as an argument, or a default value if
@@ -1961,8 +2168,30 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Oc
+Closes multi-line
+.Sx \&Oo
+context.
 .Ss \&Oo
+Multi-line version of
+.Sx \&Op .
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Oo
+\&.Op Fl flag Ns Ar value
+\&.Oc
+.Ed
 .Ss \&Op
+Command-line option.
+Used when listing options to command-line utilities.
+Prints the argument(s) in brackets.
+.Pp
+Examples:
+.D1 \&.Op \&Fl a \&Ar b
+.D1 \&.Op \&Ar a | b
+.Pp
+See also
+.Sx \&Oo .
 .Ss \&Os
 Document operating system version.
 This is the mandatory third macro of
@@ -2011,11 +2240,43 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Pa
+A file-system path.
+.Pp
+Examples:
+.D1 \&.Pa /usr/bin/mandoc
+.D1 \&.Pa /usr/share/man/man7/mdoc.7
+.Pp
+See also
+.Sx \&Lk .
 .Ss \&Pc
+Close parenthesised context opened by
+.Sx \&Po .
 .Ss \&Pf
+Removes the space
+.Pq Qq prefix
+between its arguments.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. \&Pf Cm prefix suffix
+.Pp
+The
+.Cm suffix
+argument may be a macro.
+.Pp
+Examples:
+.D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix
 .Ss \&Po
+Multi-line version of
+.Sx \&Pq .
 .Ss \&Pp
+Break a paragraph.
+This will assert vertical space between prior and subsequent macros
+and/or text.
 .Ss \&Pq
+Parenthesised enclosure.
+.Pp
+See also
+.Sx \&Po .
 .Ss \&Qc
 .Ss \&Ql
 .Ss \&Qo
@@ -2096,14 +2357,21 @@ See also
 and
 .Sx \&Ox .
 .Ss \&Va
+A variable name.
+.Pp
+Examples:
+.D1 \&.Va foo
+.D1 \&.Va const char *bar ;
 .Ss \&Vt
 A variable type.
-This is also used for indicating global variables in the SYNOPSIS
+This is also used for indicating global variables in the
+.Em SYNOPSIS
 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 SYNOPSIS section, else it
-accepts ordinary
+syntax when invoked as the first macro in the
+.Em SYNOPSIS
+section, else it accepts ordinary
 .Sx In-line
 syntax.
 .Pp
@@ -2113,10 +2381,10 @@ which is used for function return types.
 .Pp
 Examples:
 .D1 \&.Vt unsigned char
-.D1 \&.Vt extern const char * const sys_signame[] ;
+.D1 \&.Vt extern const char * const sys_signame[] \&;
 .Pp
 See also
-.Sx \&Ft
+.Sx MANUAL STRUCTURE
 and
 .Sx \&Va .
 .Ss \&Xc
@@ -2148,7 +2416,7 @@ This behaviour is for compatibility with
 .Pp
 Examples:
 .D1 \&.Xr mandoc 1
-.D1 \&.Xr mandoc 1 ;
+.D1 \&.Xr mandoc 1 \&;
 .D1 \&.Xr mandoc 1 \&Ns s behaviour
 .Ss \&br
 .Ss \&sp
@@ -2168,6 +2436,9 @@ Heirloom troff, the other significant troff implementa
 .Pp
 .Bl -dash -compact
 .It
+Old groff fails to assert a newline before
+.Sx \&Bd Fl ragged compact .
+.It
 groff behaves inconsistently when encountering
 .Pf non- Sx \&Fa
 children of
@@ -2184,7 +2455,7 @@ and
 .Sx \&Fn
 in the
 .Em SYNOPSIS :
-at times newline(s) are suppressed dependong on whether a prior
+at times newline(s) are suppressed depending on whether a prior
 .Sx \&Fn
 has been invoked.
 In mandoc, this is not the case.
@@ -2242,16 +2513,15 @@ In quoted literals, groff allowed pair-wise double-quo
 standalone double-quote in formatted output.
 This idiosyncratic behaviour is not applicable in mandoc.
 .It
-Display types
+Display offsets
 .Sx \&Bd
-.Fl center
+.Fl offset Ar center
 and
-.Fl right
-are aliases for
-.Fl left
-in manodc.  Furthermore, the
+.Fl offset Ar right
+are disregarded in mandoc.
+Furthermore, troff specifies a
 .Fl file Ar file
-argument is ignored.
+argument that is not supported in mandoc.
 Lastly, since text is not right-justified in mandoc (or even groff),
 .Fl ragged
 and