Re: .Xr mdoc(7) from groff_mdoc(7)?

[Steffen Nurpmeso]

I am off-topic.

Ingo Schwarze wrote in
<20200625214812.gf90...@athene.usta.de>:
 |given that two authoritative manual pages for the mdoc language
 |exist that describe exactly the same language, but in a somewhat
 ...
 |  The manual page groff_mdoc(7): https://man.voidlinux.org/groff_mdoc
 |  contained in the "groff" package documents exactly the same language
 |  in a somehwat different style.

Oh my god.

  ...
 |+.Pp
 |+The manual page
 |+.Lk https://man.openbsd.org/mdoc.7 "mdoc(7)"
 |+contained in the
 |+.Dq mandoc
 |+package documents exactly the same language in a somehwat different style.

Oh my god, II.
somewhat is a typo here, Ingo.

My humble opinion, luckily out-of-project.
The day the existence of the additional mandoc page starts
documenting a different language is the day that would have become
a problem.
Why only voidlinux?  What about all other humans of all sex and
colour who are main and everywhere not master and slave and
upstream / downstream?  That is sheer anarchy!
I think mdoc(7) is a roff macro package, with the potential to use
all roff commands, and therefore it belongs into roff software.

--steffen
|
|Der Kragenbaer,The moon bear,
|der holt sich munter   he cheerfully and one by one
|einen nach dem anderen runter  wa.ks himself off
|(By Robert Gernhardt)

.Xr mdoc(7) from groff_mdoc(7)?

[Ingo Schwarze]

Hi,

given that two authoritative manual pages for the mdoc language
exist that describe exactly the same language, but in a somewhat
different style, an anonymous coward calling himself "B 9" just
suggested in passing in a remark in a bugtracking ticket that it
might occasionally help users if both authoritative pages would
reference each other.  So i went ahead and added this sentence to
the SEE ALSO section of the mdoc(7) manual page in the mandoc
distribution:

  The manual page groff_mdoc(7): https://man.voidlinux.org/groff_mdoc
  contained in the "groff" package documents exactly the same language
  in a somehwat different style.

Are GNU troff developers OK with adding the reverse link to
the SEE ALSO section of the groff_mdoc(7) manual page, as in
the patch below?

Of course, i'm open to tweaks of the wording.

The point in not using .Xr in such an unusual case is two-fold: on
the one hand, people having installed groff do not necessarily have
mandoc installed and vice versa, so an .Xr can easily result in
dead links.  On the other hand, the bare manual page name mdoc(7)
without an URI could lead people to the wrong manual page, the
ancient mdoc(7) page that became obsolete twenty years ago but
unfortunately still floats in various places on the web.

This patch seemed too minor to open a ticket, i thought feedback is
likely to be quicker and simpler with just a straightforward email.

OK?
  Ingo

P.S.
Regarding the link in the mandoc mdoc(7) page, i would have preferred
an authoritative URI below https://www.gnu.org/ but couldn't find any.
Void Linux is generally very well maintained and very up-to-date,
so i see no risk that the link dies next year.  Debian would of
course work, too, but the URI
  https://manpages.debian.org/unstable/mandoc/mandoc_mdoc.7.en.html
unfortunately feels excessively ugly...


diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index 6aec5a11..03f06395 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -4245,6 +4245,12 @@ Multiple man pages (in either format) can be handled.
 .Xr man 1 ,
 .Xr troff 1 ,
 .Xr groff_man 7
+.Pp
+The manual page
+.Lk https://man.openbsd.org/mdoc.7 "mdoc(7)"
+contained in the
+.Dq mandoc
+package documents exactly the same language in a somehwat different style.
 .
 .
 .Sh BUGS

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

[Ingo Schwarze]

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

> 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:

  

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

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

[INVALID.NOREPLY]

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

[comment #5 comment #5:]
> 
> > 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? 


> 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:

  

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

[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 +.  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:

  

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

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

  

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

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

  

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

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

  

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