mdoc(7) COMPATIBILITY

[Ingo Schwarze <schwarze@usta.de>]

Hi Kristaps,

> That reminds me: can you put a note in mdoc.7 COMPATIBILITY?

Uh.
I felt unable to decide where to put it...

So, here is a proposal to sort that section by macro names,
to uniformly put these at the beginning of each line,
in order to make it easier to navigate,
and to distinguish shortcomings in groff from
unimplemented features in mandoc.

I have removed a few entries because they seem untrue or
irrelevant:

 - "The comment syntax `\."' is no longer accepted."
   It is discouraged, but mandoc does accept it.
 - .Bd -ragged = -filled, -literal = -unfilled
   I'm not aware of any real difference between groff and mandoc
   in this respect.
 - .Cd was restricted to section 4 manuals.
   .Er was restricted to section 2 manuals.
   .Ex was restricted to section 1, 6, and 8 manuals.
   .Rv was restricted to section 2 and 3 manuals.
   Actually, groff always renders these macros correctly,
   even though it warns about .Ex and .Rv used elsewhere.

Of course, i have also added the sentence about spacing in
.Bd -column, now that it's clear where to put it.  ;-)

OK?

Yours,
  Ingo


Index: mdoc.7
===================================================================
RCS file: /cvs/src/share/man/man7/mdoc.7,v
retrieving revision 1.48
diff -u -p -r1.48 mdoc.7
--- mdoc.7	18 Aug 2010 01:59:59 -0000	1.48
+++ mdoc.7	21 Aug 2010 20:03:10 -0000
@@ -2715,155 +2715,132 @@ 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
+.Sx \&Bd Fl ragged compact
+does not start a new line.
+\*[hist]
 .It
-An empty
-.Sq \&Dd
-macro in groff prints
+.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.
-.It
-Historic groff does not break before an
-.Sx \&Fn
-when not invoked as the line macro in the
-.Em SYNOPSIS
-section.
+for the normalised behaviour in mandoc.
 .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
+.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
+.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
-groff does not accept the
-.Sq \&Ta
-pseudo-macro as a line macro.
-mandoc does.
-.It
-The comment syntax
-.Sq \e\."
-is no longer accepted.
+.Sx \&Lk
+only accepts a single link-name argument; the remainder is misformatted.
 .It
-In groff, the
 .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
+.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
-groff behaves irregularly when specifying
 .Sq \ef
 .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 .
-.It
-Historic groff has many un-callable macros.
-Most of these (excluding some block-level macros) are now callable.
+.Fl offset Ar right .
+Groff does not implement centered and flush-right rendering either,
+but produces large indentations.
 .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.
+The \em (font colour), \eM (font filling colour), and \es (font size)
+font decoration escapes are all discarded in mandoc.
 .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 ,
-and
-.Sx \&Rv
-macros were stipulated only to occur in certain manual sections.
-mandoc does not have these restrictions.
+The
+.Sq f
+scaling unit is accepted by mandoc, but rendered as the default unit.
 .It
-Newer groff and mandoc print
-.Qq AT&T UNIX
-prior to unknown arguments of
-.Sx \&At ;
-older groff did nothing.
+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 man 1 ,
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv