Re: [Groff] Using real tables in groff_mdoc(7)

[Werner LEMBERG]

> However, it's probably still true that maintaining a common manual
> can provide quality (and in particular consistency) improvements in
> the long run, and that the long-term maintenance effort may be
> lower, even though there is an initial investment for merging the
> two.

I second this.

> It seems that groff_mdoc(7) aims to describe basic roff features as
> well in so far as they are relevant for mdoc, accepting duplication
> with what should be in groff_man(7), groff_me(7) and similar manuals
> as well.

To a certain degree, yes.  It is assumed that a user who writes a
basic man page with mdoc needs only to read groff_mdoc.  Essentially,
this boils down to a single introductory section.

> The mdocml mdoc(7) manual, on the other hand, relies on the mdocml
> roff(7) manual for such material, sometimes using explicit pointers.
> Examples include spaces in arguments, trailing white space, special
> characters.  The mdocml roff(7) manual contains the subset of the
> groff(7) manual that is relevant to mandoc(1).  Getting such
> pointers portable such that the resulting mdoc(7) reference fits
> into both contexts is going to be tricky.

Well, a possible solution is to compile this first section only for
groff, this is, on BSD systems the conversion process from
groff_mdoc.man to mdoc.7 strips off this first section.

> The mdoc(7) manual considers some minor features implementation
> details that don't warrant documentation, for example end of
> sentence spacing (which depends, by the way, on the formatting
> frontend; -Thtml probably doesn't do anything about it).

Hmm.  But sometimes you have to take care of it; just think of

  foo ... bar

which gets rendered as

  foo ...  bar

for TTYs by default.  This looks *really* ugly IMHO.

Having a single source for all mdoc variants (both the source code and
documentation) would be beneficial to everyone.  Given that groff's
mdoc stuff is *not* GPLed but using the original BSD license, this
should be possible.


    Werner