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

[INVALID.NOREPLY]

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/