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

[Ingo Schwarze]

Follow-up Comment #3, bug #58653 (project groff):

You say "i wish you had mentioned this before".  Granted, it would have been
helpful, and i wanted to.  But there isn't time to answer all questions i
could usefully respond to, so it fell through the cracks.  I estimate roughly
80% fall through the cracks due to lack of time.  I tend to prioritize those
answers that allow positive action over those refuting bad ideas.  Opening
this bug forced me to answer just to make sure no harm is done.

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. 
Of course that approach doesn't work for very complex topics like quantum
field theory where you first have to understand more than half a dozen layers
of mathematical abstractions, each built on top of the simpler ones, but it
works just fine for anything that can be readily understood just based on
natural language, without any previous knowledge of any kind, like a markup
language as intentionally trivial as mdoc, and even for just about any
programming language.  Just train your reading skills to quickly extract the
information you need from a precise, concise text without reading all the
words.

You say "writing good docs that are correct, complete, and concise takes time,
and they tend to degrade over time from accretion".  Absolutely.  I write a
lot of documentation, my average time per function is over two hours (mostly
measured documenting crypto/TLS libraries, but i write lots of other stuff,
too).  Some functions take up to eight hours.  On top of that, good
documentation requires good API/UI design, or you have lost before you even
start.  Then, if the API/UI develops feature creep over time, the docs will
degrade at least as much as the code.  Fortunately, no such degradation
happened in mdoc, i took care of that during the last decade, adding just one
single macro in ten years and during the same time deprecating more than half
a dozen and removing traps from a few others.

You say "but even confusing information is still helpful".  No it is not. 
There is no time to maintain it.  Unmaintained, it causes confusion and
questions which no one has time to handle.  Why do you think we spent the time
to get the horrible document exterminated?  To save us more time and
confusion. afterwards.

You name some downsides of groff_mdoc(7).  Yes, the IDIOSYNCRASIES section is
a bit wordy, in particular being near the beginning of the page, but it's
trivial to see even for a beginner that you can skip it during the first
reading.

I work relatively little on groff documentation because i maintain mandoc
documentation.  Both have essentially identical content arranged in slightly
different style, and since i see no way to prevent this duplication, i think
we can at least make it partly useful by having it maintained by different
people, such that users can pick the style they understand more easily.  If
groff_mdoc(7) is too wordy for you, especially near the beginning, you will
probably like the more concise mandoc mdoc(7) manual better.  Also, 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.

    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?58653>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/