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

[Werner LEMBERG]

[I'm moving the discussion to address@hidden, and CCing Ruslan Ermilov,
since this is the better place to discuss such issues.]


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

Thanks for putting loose ends together.

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

Just wondering why you haven't based your work on groff's versions of
those files.  Ruslan and I have spent many hours on improving and
fixing them.

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

Great!  

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

Sounds good.

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

This is a really good thing IMHO.

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

Thanks in advance!

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

All of your activities look very promising.  If you don't mind, please
post larger patches to the groff list for review.  Unfortunately, I
can't offer much time currently for active work, but passive checking
should be possible.


    Werner