Follow-up Comment #4, bug #58653 (project groff): [comment #3 comment #3:] > You say "but beginners need something simpler". I contest that. It's not because i'm an expert on mdoc(7). When learning a completely new language totally from scratch, i typically go for the formal standard / formal language definition (or the reference manual if there is no completely formal document), and certainly not for the user manual or tutorial, which usually is a total waste of time even during the first two or three hours of learning.
May I suggest that, perhaps, you are a bit of an exception? There are many different kinds of minds out there. Even if you find user manuals to be a waste of time, some of us do not. > Just train your reading skills to quickly extract the information you need from a precise, concise text without reading all the words. Perhaps part of the problem here is that we are talking about different things. You mention extracting information from formal specifications, but I'm starting out from the meta-question "Do I even want to learn this?" Good documentation lets people know right away what the cost of learning will be and what the benefits are. For example, mdoc(7) told me the benefit (semantic markup) and then showed that using it would not be complicated. > Why do you think we spent the time to get the horrible document exterminated? Honestly, I had thought the problem was that it was maintained by the Linux kernel folks and the groff team wanted something that they could keep up-to-date. "Exterminating" the quick reference guide without replacement seems a bit extreme. > [...] the high-level "what is this all about" stuff useful for beginners is easier to find in mandoc mdoc(7) than in groff_mdoc(7). Certainly no need for a third. This mandoc mdoc(7) you are speaking of, is it part of groff? I don't see it. I filed this bug report to improve the documentation for groff, but perhaps it just needs to be made easier to find. _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?58653> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/