Re: Using real tables in groff_mdoc(7)

[Eric S. Raymond]

Ingo Schwarze <address@hidden>:
>                                                     So take
> care what you touch, you might end up as the new maintainer.  ;-)

No, I would make very sure that potato landed in Kristaps's lap :-).
I've been in touch with him by email on some related matters which
I'll explain below.  I'm copying him on this reply.

> > 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.

You're not wrong.  The reason I've been in touch with Kristaps is
because I maintain the third of the three implementations of mdoc -
there's groff's, there's mandoc, and there's my special-purpose one in
doclifter that exists only to support translation to DocBook.  I've run
into ambiguities in the spec that need resolving.

> 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's a good plan and will cooperate with it.

>                                                  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).

Not sure I understand the last sentence.  It will still be a good idea
for the new manual to use TBL rather than the present hacks with Bd/Be.  TBL
markup can be translated structurally to XML-DocBook tables; the
macros presently used to simulate tables cannot be (well, it's
theoretically possible, but it's not practical).

> What do you think?

I'm in favor.  You, Kristaps and me are the obvious team for this.  Here
is what I will contribute:

1. TBLization of the new manual.  More generally, I will apply doclifter
to make sure it in clean for XML lifting before we merge it into the groff
tree.

2. I'll list the ambiguities in the current spec from the point of view
of an mdoc implementer, so we can be sure the new manual ends up providing
good guidance on issues like order of evaluation and parsing rules.

3. I'll also do an editing pass for good English usage.  (Your English
and Kristaps's are both quite good, but I'm an expert native speaker
and can do a somewhat better job of polishing than either of you.)

4. Pending merge of the new manual, I will test and merge my TBLization
patches for the existing one, so it will be in good state for lifting
to XML.

Kristaps: can you read Python?  It would be good to have someone's
eyes other than mine on the doclifter interpreter.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>