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

[Ingo Schwarze]

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

> Good documentation lets people know right away what the
> cost of learning will be and what the benefits are.

Right, that's usually the first one to three sentences in a manual page.  No
need for a separate document.

In groff_mdoc(7), the first paragraph does that, too.  Admittedly, it's a bit
wordy (9 sentences rather than 3), partially antiquated (translation to future
documentation tools etc. - huh?), and contains some needless jargon (domain
etc.).  It could probably be made a bit more readable.

The part "easy to learn" could probably be made obvious by including a MACRO
OVERVIEW up front, as i already suggested.

> Honestly, I had thought the problem was
> that it was maintained by the Linux kernel folks

It wasn't maintained by "the Linux kernel folks" but by the Linux manual pages
project (Michael Kerrisk et al.) who generally does a good job at maintaining
documentation of code he doesn't maintain himself.  The problem wasn't that we
were jealous about what they were doing, but that it was a relic both sides
had forgotten about twenty years earlier and both sides had no interest in.

On the groff side, all the information from the former mdoc(7) manual had
already been merged almost twenty years ago.  Werner Lemberg did that work in
commit b57a7328 on Mar 24 15:04:41 2001 +0000.  So there was nothing more to
do here.

> This mandoc mdoc(7) you are speaking of,
> is it part of groff? I don't see it.

No it isn't.
I already posted the hyperlink: https://man.openbsd.org/mdoc.7
It is part of mandoc.

It shows that what you want can easily be done within a reference manual.  But
as i said, i feel somewhat reluctant to do copy-editing on groff_mdoc(7)
myself because if we must have two documents, having two distinct maintainers
improves the chances that every user finds a version in the style they like.

I don't oppose improving groff_mdoc(7).  I don't even have strong preferences
in which direction to tweak it, as long as it remains correct and complete and
does not become even more wordy.  What i oppose is adding another manual page
for the same thing.

    _______________________________________________________

Reply to this item at:

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

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