Re: Using real tables in groff_mdoc(7)

[Ingo Schwarze]

Hi Eric,

Eric S. Raymond wrote on Fri, Aug 10, 2012 at 11:22:51AM -0400:

> I've been replacing various ad-hoc simulations of tables in the groff 
> documentation with actual TBL markup.  The reason for this is that 
> TBL tables can be parsed and lifted to XML-DocBook (enabling
> generation of really high-quality HTML) whereas the various kluges
> used to simulate them cannot be.

What you are doing seems worthwhile to improve compatibility with
other mdoc(7) parsers as well, for example mandoc(1).

> Who is responsible for groff_mdoc(7)?

The mdoc(7) language first appeared as a troff macro package in 4.4BSD,
in 1993.  It was accompagnied by two manual pages, themselves written
using the mdoc(7) language:

  mdoc(7) - quick reference guide for the -mdoc macro package
  mdoc.samples(7) - tutorial sampler for writing BSD manuals with -mdoc

The oldest SCCS checkins at Berkeley i can find are:

  mdoc(7) D 1.1 91/08/05 by Cynthia Livingston (USENIX)
  mdoc.samples(7) D 1.1 90/06/22 by cael as well

When the mdoc macros were reimplemented for groff 1.17 in 2001,
people realized that the quick mdoc(7) reference was rather
brief and incomplete while mdoc.samples(7) - even though
originally intended as a tutorial - did a better job even
as a reference manual.  So mdoc(7) got dropped and mdoc.samples(7)
renamed to groff_mdoc(7).  Yet, the meat of groff_mdoc(7) is still
the same text already found in the old USENIX tutorial, and
calling anybody a "maintainer" seems like a bold claim.  So take
care what you touch, you might end up as the new maintainer.  ;-)

> Would there be any objection to me converting that page to use
> table markup for its tables?

I wouldn't really object to that, but i think there is an alternative
that might be worth considering.  In 2009, Kristaps Dzonsons set out
to write a real mdoc(7) reference manual from scratch.  We have
polished that one for three years now, and i consider it of
reasonable quality by now.  In particular, i personally made sure
that no information contained in mdoc.samples(7) is missing from
mdoc(7).  On the other hand, mdoc.samples(7) is lacking various
pieces of information, and some of the language is a bit vague,
or at least it used to be last time i checked.

Admittedly, the new mdoc(7) manual is still slightly mandoc(1)-centric,
but if you were interested in including it in the groff distribution,
i would be willing to clean that aspect up, and then we could maintain
a common reference manual in the groff, mdocml.bsd.lv and openbsd.org
trees; the latter two are already in sync now.  I think that would
provide a better quality manual with less work for everyone, and even
without causing mdoc(7) to depend on tbl(7).

Here are the code and sample output, it's ISC licensed, so inclusion
in the groff distribution would cause no issues:

  http://mdocml.bsd.lv/cgi-bin/cvsweb/mdoc.7?cvsroot=mdocml
  http://mdocml.bsd.lv/mdoc.7.html

What do you think?
  Ingo