===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.149
retrieving revision 1.150
diff -u -p -r1.149 -r1.150
--- mandoc/mdoc.7	2010/08/09 00:07:51	1.149
+++ mandoc/mdoc.7	2010/08/22 14:54:29	1.150
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.149 2010/08/09 00:07:51 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.150 2010/08/22 14:54:29 kristaps Exp $
 .\"
 .\" Copyright (c) 2009, 2010 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 9 2010 $
+.Dd $Mdocdate: August 22 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -2715,155 +2715,148 @@ file re-write
 Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.
 .Pp
+The following problematic behaviour is found in groff:
+.ds hist (Historic groff only.)
+.Pp
 .Bl -dash -compact
 .It
-groff only accepts a single
-.Sq \&Lk
-link-name argument; the remainder is misformatted.
+.Sx \&At
+with unknown arguments produces no output at all.
+\*[hist]
+Newer groff and mandoc print
+.Qq AT&T UNIX
+and the arguments.
 .It
-The
-.Sq \&%C
-macro is not implemented in groff.
+.Sx \&Bd Fl column
+does not recognize trailing punctuation characters when they immediately
+precede tabulator characters, but treats them as normal text and
+outputs a space before them.
 .It
-An empty
-.Sq \&Dd
-macro in groff prints
+.Sx \&Bd Fl ragged compact
+does not start a new line.
+\*[hist]
+.It
+.Sx \&Dd
+without an argument prints
 .Dq Epoch .
 In mandoc, it resolves to the current date.
 .It
-The \es (font size), \em (font colour), and \eM (font filling colour)
-font decoration escapes are all discarded in mandoc.
+.Sx \&Fl
+does not print a dash for an empty argument.
+\*[hist]
 .It
-Old groff fails to assert a newline before
-.Sx \&Bd Fl ragged compact .
+.Sx \&Fn
+does not start a new line unless invoked as the line macro in the
+.Em SYNOPSIS
+section.
+\*[hist]
 .It
-groff behaves inconsistently when encountering
-.Pf non- Sx \&Fa
-children of
 .Sx \&Fo
-regarding spacing between arguments.
-In mandoc, this is not the case: each argument is consistently followed
-by a single space and the trailing
-.Sq \&)
-suppresses prior spacing.
+with
+.Pf non- Sx \&Fa
+children causes inconsistent spacing between arguments.
+In mandoc, a single space is always inserted between arguments.
 .It
-groff behaves inconsistently when encountering
 .Sx \&Ft
-and
-.Sx \&Fn
 in the
-.Em SYNOPSIS :
-at times newline(s) are suppressed depending on whether a prior
+.Em SYNOPSIS
+causes inconsistent vertical spacing, depending on whether a prior
 .Sx \&Fn
 has been invoked.
-In mandoc, this is not the case.
 See
 .Sx \&Ft
 and
 .Sx \&Fn
-for the normalised behaviour.
+for the normalised behaviour in mandoc.
 .It
-Historic groff does not break before an
-.Sx \&Fn
-when not invoked as the line macro in the
-.Em SYNOPSIS
-section.
-.It
-Historic groff formats the
 .Sx \&In
-badly: trailing arguments are trashed and
-.Em SYNOPSIS
-is not specially treated.
+ignores additional arguments and is not treated specially in the
+.Em SYNOPSIS .
+\*[hist]
 .It
-groff does not accept the
-.Sq \&Ta
-pseudo-macro as a line macro.
-mandoc does.
+.Sx \&It
+sometimes requires a
+.Fl nested
+flag.
+\*[hist]
+In new groff and mandoc, any list may be nested by default and
+.Fl enum
+lists will restart the sequence only for the sub-list.
 .It
-The comment syntax
-.Sq \e\."
-is no longer accepted.
+.Sx \&Li
+followed by a reserved character is incorrectly used in some manuals
+instead of properly quoting that character, which sometimes works with
+historic groff.
 .It
-In groff, the
+.Sx \&Lk
+only accepts a single link-name argument; the remainder is misformatted.
+.It
 .Sx \&Pa
-macro does not format its arguments when used in the FILES section under
+does not format its arguments when used in the FILES section under
 certain list types.
-mandoc does.
 .It
-Historic groff does not print a dash for empty
-.Sx \&Fl
-arguments.
-mandoc and newer groff implementations do.
+.Sx \&Ta
+can only be called by other macros, but not at the beginning of a line.
 .It
-groff behaves irregularly when specifying
+.Sx \&%C
+is not implemented.
+.It
+Historic groff has many un-callable macros.
+Most of these (excluding some block-level macros) are callable
+in new groff and mandoc.
+.It
+.Sq \(ba
+(vertical bar) is not fully supported as a delimiter.
+\*[hist]
+.It
 .Sq \ef
+.Pq font face
+and
+.Sq \ef
+.Pq font family face
 .Sx Text Decoration
-within line-macro scopes.
-mandoc follows a consistent system.
+escapes behave irregularly when specified within line-macro scopes.
 .It
-In mandoc, negative scaling units are truncated to zero; groff would
-move to prior lines.
-Furthermore, the
-.Sq f
-scaling unit, while accepted, is rendered as the default unit.
+Negative scaling units return to prior lines.
+Instead, mandoc truncates them to zero.
+.El
+.Pp
+The following features are unimplemented in mandoc:
+.Pp
+.Bl -dash -compact
 .It
-In quoted literals, groff allowed pairwise double-quotes to produce a
-standalone double-quote in formatted output.
-This idiosyncratic behaviour is not applicable in mandoc.
+.Sx \&Bd
+.Fl file Ar file .
 .It
-Display offsets
 .Sx \&Bd
 .Fl offset Ar center
 and
-.Fl offset Ar right
-are disregarded in mandoc.
-Furthermore, troff specifies a
-.Fl file Ar file
-argument that is not supported in mandoc.
-Lastly, since text is not right-justified in mandoc (or even groff),
-.Fl ragged
-and
-.Fl filled
-are aliases, as are
-.Fl literal
-and
-.Fl unfilled .
+.Fl offset Ar right .
+Groff does not implement centered and flush-right rendering either,
+but produces large indentations.
 .It
-Historic groff has many un-callable macros.
-Most of these (excluding some block-level macros) are now callable.
-.It
-The vertical bar
-.Sq \(ba
-made historic groff
-.Qq go orbital
-but has been a proper delimiter since then.
-.It
-.Sx \&It Fl nested
-is assumed for all lists (it wasn't in historic groff): any list may be
-nested and
-.Fl enum
-lists will restart the sequence only for the sub-list.
-.It
-Some manuals use
-.Sx \&Li
-incorrectly by following it with a reserved character and expecting the
-delimiter to render.
-This is not supported in mandoc.
-.It
-In groff, the
-.Sx \&Cd ,
-.Sx \&Er ,
-.Sx \&Ex ,
+The
+.Sq \eh
+.Pq horizontal position ,
+.Sq \ev
+.Pq vertical position ,
+.Sq \em
+.Pq text colour ,
+.Sq \eM
+.Pq text filling colour ,
 and
-.Sx \&Rv
-macros were stipulated only to occur in certain manual sections.
-mandoc does not have these restrictions.
+.Sq \es
+.Pq text size
+.Sx Text Decoration
+escapes are all discarded in mandoc.
 .It
-Newer groff and mandoc print
-.Qq AT&T UNIX
-prior to unknown arguments of
-.Sx \&At ;
-older groff did nothing.
+The
+.Sq \ef
+scaling unit is accepted by mandoc, but rendered as the default unit.
+.It
+In quoted literals, groff allows pairwise double-quotes to produce a
+standalone double-quote in formatted output.
+This is not supported by mandoc.
 .El
 .Sh SEE ALSO
 .Xr mandoc 1 ,