Follow-up Comment #2, bug #58653 (project groff): [comment #1 comment #1:] > I *VERY* strongly oppose this idea.
Thank you, Ingo, although I do wish you had mentioned this on the mailing list when I first brought it up or at the point when someone else suggested that the groff project needs to have a bug report on it. Ingo, at your request, the Linux man pages dropped mdoc(7) last year. The fact that BSD has good documentation doesn't alleviate the need for GNU/Linux systems to also have complete and useful documentation. It is now up to the groff project to make sure that happens. > Documentation ought to be correct, complete, concise, and easy to find, which implies all in one place. Trying to balance competing goals, such as "complete" and "easy to understand", in a single document is difficult, sometimes impossible. When it does happen, it takes a lot of time and effort to get right. Also, it's a bear to maintain as inevitably changes accrue that throw it out of balance. It is much less work to have separate documents. One of them, groff_mdoc(7), can prioritize being correct and complete. The other, mdoc(7), can focus on being concise and easy to learn from. And that's what GNU/Linux had until mdoc(7) was dropped. > It is even a terrible starting point for working on something better. Experts are always disappointed by any quick reference guide: "it is incomplete and wrong!" But, that's mainly because it has been optimized for understandability to a more general audience: people like me who are *not* already experts. Such tutorials are top-loaded with broad brush strokes giving general use and "quick start for the impatient" type of information. Then they go on to the most useful features and work their way down. Nitty gritty details are pushed to the back, if covered at all. For example, from reading mdoc(7), I knew very quickly what the point of mdoc was, where to find the full documentation (groff_mdoc(7)), and even the minimal commands needed to create a valid mdoc manual page. I could see that I wouldn't have to invest much time for this package to be useful to me. Whereas, reading that far in groff_mdoc(7), my eyes had glazed over. Does one have to understand "troff idiosyncracies" to use this package? It's not clear from the document, but that's because it has a different purpose: if I need to understand mdoc in more detail, I can come back to it. > One reference manual is enough. Yes, for people who already know mdoc. For people getting started or needing to brush up, a quick reference guide serves them better. If you're writing for humans, the documentation isn't complete unless it includes an approachable guide for new users. Documentation is not like computer programming where we want to do things in exactly one place. Different people find different forms of documentation helpful and repetition phrased in alternate ways is actually better. It is not harmful to have more than one document, even if they get out of sync, as long as the informal guide explicitly links to the complete reference. (Note that mdoc(7) starts out by referencing groff_mdoc(7).) > If groff developers think groff_mdoc(7) needs an overview before diving into the specifics, i can copy the "MACRO OVERVIEW" section from > https://man.openbsd.org/mdoc#MACRO_OVERVIEW Ingo, please do not take offense, but I think perhaps you may be too expert. I say this with great respect: The fact that you don't see the point of mdoc(7), which was so helpful to a troff neophyte like me, raises the question of whether you are the right person to make groff's documentation more user friendly. I am full of humility and admiration for the work Ingo and all the groff devlopers have put in over the years. Even if you reject this bug, I thank you. --b9 _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?58653> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/