Follow-up Comment #5, bug #58653 (project groff): > Good documentation lets people know right away what the > cost of learning will be and what the benefits are.
Right, that's usually the first one to three sentences in a manual page. No need for a separate document. In groff_mdoc(7), the first paragraph does that, too. Admittedly, it's a bit wordy (9 sentences rather than 3), partially antiquated (translation to future documentation tools etc. - huh?), and contains some needless jargon (domain etc.). It could probably be made a bit more readable. The part "easy to learn" could probably be made obvious by including a MACRO OVERVIEW up front, as i already suggested. > Honestly, I had thought the problem was > that it was maintained by the Linux kernel folks It wasn't maintained by "the Linux kernel folks" but by the Linux manual pages project (Michael Kerrisk et al.) who generally does a good job at maintaining documentation of code he doesn't maintain himself. The problem wasn't that we were jealous about what they were doing, but that it was a relic both sides had forgotten about twenty years earlier and both sides had no interest in. On the groff side, all the information from the former mdoc(7) manual had already been merged almost twenty years ago. Werner Lemberg did that work in commit b57a7328 on Mar 24 15:04:41 2001 +0000. So there was nothing more to do here. > This mandoc mdoc(7) you are speaking of, > is it part of groff? I don't see it. No it isn't. I already posted the hyperlink: https://man.openbsd.org/mdoc.7 It is part of mandoc. It shows that what you want can easily be done within a reference manual. But as i said, i feel somewhat reluctant to do copy-editing on groff_mdoc(7) myself because if we must have two documents, having two distinct maintainers improves the chances that every user finds a version in the style they like. I don't oppose improving groff_mdoc(7). I don't even have strong preferences in which direction to tweak it, as long as it remains correct and complete and does not become even more wordy. What i oppose is adding another manual page for the same thing. _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?58653> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/
