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

[Ingo Schwarze]

Hi Werner and Eric,

Werner LEMBERG wrote on Sat, Aug 11, 2012 at 08:16:26AM +0200:
> esr wrote:
>> Ingo Schwarze wrote:

>>> In particular, i personally made sure that no information
>>> contained in mdoc.samples(7) is missing from mdoc(7).

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

Actually, i did use a groff version when doing the check - it came
from groff 1.15 and contained various improvements by Aaron Campbell,
Jason McIntyre and some others.  I kind of forgot to check against
the current groff version in CVS, my bad, really.  I should probably
revisit the page and do the missed check against the current version.

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

Well, i implied that mdoc(7) is more complete and rigorous than
groff_mdoc(7) - which i have to re-check, see above - and that
maintaining one common manual in groff, mandoc, OpenBSD and FreeBSD
is less work than maintaining two vastly different ones.  Besides,
if everybody works together on one common document, quality is likely
to improve even more, maybe even the programs might improve in the
process because comparison tends to uncover bugs.

I'm not aware that mdoc(7) uses .Bd for tabular displays,
and i'm not sure what you mean by .Be.  Sure, mdoc(7) does
use a lot of .Bd/.Ed, but almost exclusively for code examples,
which is apropriate.  The tables in mdoc(7) use .Bl -column/.El
which is less powerful than tbl(7) but works quite well for
the simple tables needed in mdoc(7).

>> I'm in favor.  You, Kristaps and me are the obvious team for this.

Ok, so we should first agree in which repo to maintain the master
copy for our joint work.  I see two obvious possibilities:

 1) Use the existing mdocml.bsd.lv; both Kristaps and myself
    have commit access to that one, Kristaps is maintaining it.
    In that case, you would have to send patches.  Or Kristaps
    might be willing to create an account, i don't know.

 2) Import mdoc.7 into the groff CVS, then switch over in the
    build system once everybody is satisfied with what we have.
    Werner and Eric have commit acces there, so Kristaps and myself
    would send patches.

I'm large indifferent whether to use 1) or 2); maybe even 2) is
easier because the groff repo has anonymous CVS access which makes
sending patches easier.  In either case, i would make sure to also
feed our common patches into OpenBSD (getting additional reviews
from Jason McIntyre).

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

Still not sure that's needed, but if it is, fine.

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

Sounds good.

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

Indeed, thanks.

>> Kristaps: can you read Python?  It would be good to have someone's
>> eyes other than mine on the doclifter interpreter.

I do read Python.  Then again, i'm not sure i can afford the time
for a full doclifter code review right now due to time constraints;
from what i heard, doclifter is neither small nor trivial.  Besides,
i rather strongly dislike XML and most related tools, so doing a
full review sounds a bit like torture to my ears.  ;-)

Then again, if we run into ambiguities, i can certainly have a look
at specific parts for comparison with groff and mandoc.

Yours,
  Ingo