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

[I***@gnu.org]

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

Summary: Please add back in the mdoc(7) manual
Project: GNU troff
Submitted by: hackerb9
Submitted on: Wed 24 Jun 2020 10:13:31 PM UTC
Category: Macro - mdoc
Severity: 3 - Normal
Item Group: Documentation
Status: None
Privacy: Public
Assigned to: None
Open/Closed: Open
Discussion Lock: Any
Planned Release: None

_______________________________________________________

Details:

According to Ingo Schwarze on the groff mailing list, the groff
project recently convinced the Linux man pages project to remove their
mdoc(7) manual as it was outdated by a few decades.

However, the groff project lacks anything equivalent to mdoc(7).

Ingo suggested I try mandoc.bsd.lv, but I found it more cryptic and
less helpful.

Yes, there is a man page for groff_mdoc(7), but it is a "complete
reference" which is rather difficult for a beginner to get started
using mdoc. In contrast, mdoc(7) from the Linux man pages was a quick
reference on the macro names and their meanings, laid out in a logical
fashion. At the top, mdoc(7) informs the reader to check groff_mdoc(7)
for the nitty gritty.

groff_mdoc(7) appears to have been based upon mdoc.samples(7) which
was written as a companion to mdoc(7). Although groff_mdoc(7) removed
all references to mdoc(7), it does not stand alone well. As somone new
to the world of troff, I found mdoc(7) to be necessary when I
attempted my first serious man pages. If I had had only groff_mdoc(7)
available, I would have given up.

Please import the old mdoc(7) file into the groff project so that it
can become available on all GNU/Linux machines once again. Please do
not wait to update it before importing. Even outdated, it is extremely
useful and mostly correct. Once in Savannah, it can be iteratively
improved via bug reports.

The mdoc(7) file can be viewed online here:

https://man7.org/linux/man-pages/man7/mdoc.7.html

And the troff can be found here:


https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man7/mdoc.7?id=6474f351fd8ac68e6e0c8820bb8926c6b9e3ec97

Thanks!





_______________________________________________________

Reply to this item at:

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

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

[Ingo Schwarze]

Update of bug #58653 (project groff):

Severity: 3 - Normal => 1 - Wish
Assigned to: None => schwarze

_______________________________________________________

Follow-up Comment #1:

I *VERY* strongly oppose this idea.

Documentation ought to be correct, complete, concise, and easy to find, which
implies all in one place. This particular, totally unmaintained manual page
was full of errors, blatantly incomplete, terse to the point of
incomprehensibility, yet not concise, but putting excessive weight on aspects
of marginal importance. Besides, it caused a needless split of documentation
that can, without any downside, be in one place, causing people to miss the
real documentation. I'm not going to waste my time enumerating all the many
deficiencies of this ancient, unmaintained document. No, importing it would
not be "better than nothing", it would be a huge step backwards. It is even a
terrible starting point for working on something better.

In general, it is an extremely bad idea to have a short and a long version of
the same manual page. All that does is making it likely that both get out of
sync and eventually neither are correct. One reference manual is enough.

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
into the beginning of groff_mdoc(7), probably between A MANUAL PAGE TEMPLATE
and CONVENTIONS, but i'm open to suggestions for the exact location, and to
tweaking it if you think that's necessary.

_______________________________________________________

Reply to this item at:

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

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

[I***@gnu.org]

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

[comment #1 comment #1:]

Post by Ingo Schwarze
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.

Post by Ingo Schwarze
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.

Post by Ingo Schwarze
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.

Post by Ingo Schwarze
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).)

Post by Ingo Schwarze
If groff developers think groff_mdoc(7) needs an overview before diving into

the specifics, i can copy the "MACRO OVERVIEW" section from

Post by Ingo Schwarze
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/

[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/

[I***@gnu.org]

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

[comment #3 comment #3:]

Post by Ingo Schwarze
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.

Post by Ingo Schwarze
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.

Post by Ingo Schwarze
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.

Post by Ingo Schwarze
[...] 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/

[Ingo Schwarze]

Post by I***@gnu.org
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.

Post by I***@gnu.org
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.

Post by I***@gnu.org
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/

[I***@gnu.org]

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

[comment #5 comment #5:]

Post by Ingo Schwarze

Post by I***@gnu.org
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.

Please pardon my ignorance. I had thought you were linking to the mdoc
documentation that comes with BSD. Is that not right?

Post by Ingo Schwarze
What i oppose is adding another manual page for the same thing.

Clearly, as someone who has contributed to groff for a long time, Ingo, you
should have more say about the documentation than someone like me who has just
begun. I don't think I can convince you that a quick reference guide is not
redundant, so I will drop it.

I do think it is unfortunate that people who use groff on non-BSD systems are
left poorer, without even a pointer to better documentation.

_______________________________________________________

Reply to this item at:

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

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

[Ingo Schwarze]

I had thought you were linking to the mdoc documentation that comes with

BSD.

mandoc is portable software. It is included and used by default in these
systems (chronological order by first official use): OpenBSD, NetBSD, Illumos,
Void Linux, FreeBSD, Alpine Linux. Official packages exist for Debian,
Gentoo, and Fedora, among others; on Fedora, making it the default manual page
viewer is an officially supported option. I just used the OpenBSD link out of
habit and because it's the most carefully maintained manual page server
carrying it. These are quite similar:

https://mandoc.bsd.lv/man/mdoc.7.html
https://man.bsd.lv/mdoc.7
https://manpages.debian.org/buster/mandoc/mandoc_mdoc.7.en.html
https://man.voidlinux.org/man7/mdoc.7
https://www.freebsd.org/cgi/man.cgi?query=mdoc

I do think it is unfortunate that people who use groff
on non-BSD systems are left poorer, without even
a pointer to better documentation.

I wouldn't say either is absolutely better, it's mostly the same content in
somewhat different style. But your idea of adding pointers to each other in
the SEE ALSO sections on both sides sounds good, so people can more easily
find both and pick one according to which style they prefer. Let's see
whether i can get those two links in on both sides.


_______________________________________________________

Reply to this item at:

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

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

[Dave]

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

I'm not an mdoc user, so have no position on the specifics of its
documentation. But I have to agree with this point:

[comment #4 comment #4:]

Post by I***@gnu.org
[comment #3 comment #3:]

When learning a completely new language totally from scratch, i typically

go for the formal standard / formal language definition

Post by I***@gnu.org
May I suggest that, perhaps, you are a bit of an exception?

Ingo's approach is admirable but I don't think it's the norm, certainly not
for me and others I've worked with.

In general I think it behooves experienced users to listen to new users when
they say what has helped them get a handle on learning something. Hackerb9,
as someone who has just gone through that initial learning curve, is in a
unique position to say what has been most useful. There may be fatal flaws in
the particular mdoc(7) page he consulted, but what aspects of it were helpful,
and how can those be worked into something that's useful to beginners without
oversimplifying to the point of inaccuracy?

It's not like the groff package is any stranger to overlapping documentation,
having the Texinfo package for complete documentation for the core language,
and the groff(7) man page as a terse reference guide.

_______________________________________________________

Reply to this item at:

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

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