===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.122
retrieving revision 1.128
diff -u -p -r1.122 -r1.128
--- mandoc/mdoc.7	2010/06/07 11:01:15	1.122
+++ mandoc/mdoc.7	2010/07/01 15:38:56	1.128
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.122 2010/06/07 11:01:15 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.128 2010/07/01 15:38:56 schwarze Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,7 +14,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 7 2010 $
+.Dd $Mdocdate: July 1 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -55,7 +55,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 +167,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
@@ -471,13 +471,26 @@ dissimilar macros are pair-wise invoked (except for
 before
 .Sx \&Fo
 or
-.Sx \&Fn ) , 
+.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 .
@@ -672,9 +685,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
@@ -973,7 +997,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
@@ -1094,10 +1118,7 @@ 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
@@ -1119,6 +1140,25 @@ and
 .Sx \&Dl .
 .Ss \&Bf
 .Ss \&Bk
+Begins a keep block, containing a collection of macros or text
+to be kept together in the output.
+One argument is required; additional arguments are ignored.
+Currently, the only argument implemented is
+.Fl words ,
+requesting to keep together all words of the contained text
+on the same output line.
+A
+.Fl lines
+argument to keep together all lines of the contained text
+on the same page has been desired for a long time,
+but has never been implemented.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bk \-words
+\&.Op o Ar output_file
+\&.Ek
+.Ed
 .Ss \&Bl
 Begins a list composed of one or more list entries.
 A list is associated with a type, which is a required argument.
@@ -1592,6 +1632,8 @@ and
 .Ss \&Ed
 .Ss \&Ef
 .Ss \&Ek
+Ends a keep context started by
+.Sx \&Bk .
 .Ss \&El
 Ends a list context started by
 .Sx \&Bl .
@@ -1879,7 +1921,7 @@ 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,
@@ -1940,6 +1982,42 @@ Examples:
 .D1 \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd
 .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
 .Ss \&Ns
 .Ss \&Nx
@@ -2102,7 +2180,7 @@ 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 in the
 .Em SYNOPSIS
 section, else it accepts ordinary
 .Sx In-line
@@ -2169,6 +2247,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
@@ -2185,7 +2266,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.
@@ -2243,16 +2324,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, the
 .Fl file Ar file
-argument is ignored.
+argument is not supported in mandoc.
 Lastly, since text is not right-justified in mandoc (or even groff),
 .Fl ragged
 and