[bug #58653] Please add back in the mdoc(7) manual

[INVALID.NOREPLY]

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/