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
