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

[Ingo Schwarze]

Hi Werner,

Werner LEMBERG wrote on Sat, Aug 11, 2012 at 09:26:55PM +0200:

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

> Uh, this is *very* old.  Most of our improvements have happened after
> version 1.17.

>> Well, i implied that mdoc(7) is more complete and rigorous than
>> groff_mdoc(7) - which i have to re-check, see above

> Please do so.  AFAIK, groff_mdoc is complete, this is, it documents
> *every* aspect of doc.tmac.

Indeed, the current groff_mdoc(7) is vastly superior to what
mdoc.samples(7) used to be, so i have to retract my statement
that the documentation can be improved significantly by simply
replacing groff_mdoc(7) with mdoc(7).  To the contrary, it may be
that groff_mdoc(7) now is providing even more details than mdoc(7).

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 think making sure that everything explained in *modern* groff_mdoc(7)
is also in mdoc(7) will take noticable time.  From a first brief
look, it seems the comparison work will have to be interrupted at
many points to do actual functional comparisons and commit code
changes to mandoc(1) to bring various details in line with groff(1).

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

> Before deciding this, please check a recent version of groff_mdoc.

Here are some initial observations from reading through parts of
groff_mdoc(7) and checking mdoc(7) completeness.

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

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

The mdoc(7) manual doesn't document some style nits, like
discouraging blank lines outside literal context, relaying on
the fact that such input produces warnings.  Maybe some more
of those should be explicitly documented.

Probably, more conceptual differences can be added to this
list...

>> In either case, i would make sure to also feed our common patches
>> into OpenBSD (getting additional reviews from Jason McIntyre).

> Very good.

So, what's the steps?

First, going through groff_mdoc(7) and checking that everything
documented there is also documented in mdocml mdoc(7) and roff(7),
at the same time fixing the mandoc(1) program where needed.
That effort is in no case wasted as it makes mandoc(1) and mdoc(7)
better.  At the same time, keep a list of content elements that
are in groff_mdoc(7) but, for various reasons, cannot go into
mdoc(7) and roff(7), and submit patches for groff_mdoc(7) when
running into issues with it; i guess that still makes sense
because it won't go away as quickly as i thought.

As the second step, find a way to organize pointers from mdoc(7)
to other roff documentation such that they work both with groff
and in the mdocml environment, which will be tricky.

Finally, decide whether and how to manage the transition in the
groff repository, if we then deem it worthwhile.

The whole project is much more difficult than i thought at first.
Clearly, work has to start in the bsd.lv and openbsd.org repos.

Yours,
  Ingo