===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.126
retrieving revision 1.130
diff -u -p -r1.126 -r1.130
--- mandoc/mdoc.7	2010/06/12 11:41:50	1.126
+++ mandoc/mdoc.7	2010/07/04 22:04:04	1.130
@@ -1,6 +1,7 @@
-.\"	$Id: mdoc.7,v 1.126 2010/06/12 11:41:50 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.130 2010/07/04 22:04:04 schwarze 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 12 2010 $
+.Dd $Mdocdate: July 4 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -478,6 +479,19 @@ they are separated by a vertical space, unless in the 
 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 +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
@@ -1115,7 +1140,62 @@ 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.
+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
+.Pp
+See also
+.Sx \&Ek .
 .Ss \&Bl
 Begins a list composed of one or more list entries.
 A list is associated with a type, which is a required argument.
@@ -1588,7 +1668,11 @@ and
 .Ss \&Ec
 .Ss \&Ed
 .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 .
@@ -1937,6 +2021,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