Hello,
Anon Loli wrote on Fri, Aug 30, 2024 at 05:22:50PM +0000:
> In my opinion, OpenBSD has lied to us, primarily that bad manual
> pages are considered as bugs.
Just to remind people here how to best report documentation bugs,
in the order of importance starting from the most important:
1. Mention the manual page in question in the Subject: of your
message, ideally in the format name(section). Still in the
Subject:, mention that you are reporting a documentation bug.
For example:
Subject: mandoc(1) fails to document the -X option
or
Subject: ENVIRONMENT in man(1) does not mention MANWIDTH
The official recommendation is to send such reports to tech@.
Actually, misc@ often works for doc bugs too. There is a risk
that stuff gets overlooked on misc@, but often it works anyway.
Using bugs@ for doc bugs is hardly recommended (too noisy),
but it certainly works, too.
2. In the body of the message, mention the name of the manual
page and the section number *again*, and be very specific
which words in which sentence in which paragraph in which
section of that manual page are incorrect, misleading, or
imcomplete. Specify the reasons why you think there is a bug
as precisely as possible. If possible, provide an example.
For example:
"The first sentence of the EXIT STATUS section of man(1) says:
The man utility exits 0 on success, and >0 if an error occurs.
This is misleading because when the option -T lint is given
to man(1), the program may exit with a code of 1 even if
there is no error, but only a style warning. For example:
$ man -cT lint sh ; echo EXIT STATUS = $?
man: /usr/share/man/man1/sh.1:735:9: STYLE: verbatim "--",
maybe consider using \(em
man: /usr/share/man/man1/sh.1:738:9: STYLE: verbatim "--",
maybe consider using \(em
EXIT STATUS = 1"
3. Optionally, if you have some idea what to do about the bug,
explain what you suggest could be done, and explain
why you think that would be a good idea, for example:
"I suggest adding a long rant explaining that man(1)
can occasionally exit with 1 or even 2 when unusual
options like -T or -W are given and the manual page(s)
being formatted trigger some warning that no user
who merely wants to read the manual page will care
about. Optionally, you could even copy the whole
EXIT STATUS section from mandoc(1) to man(1).
The benefit would be a better chance of confusing
novice readers with niche topics, and if you copy
the long EXIT STATUS section, more fun for devs
trying to maintain that monster in the future."
4. Optionally, append a patch to your mail, fixing the doc bug
in the best way you can thing of. Even if the patch turns
out to be bad: bad patches often trigger good ones.
To summarize: reporting doc bugs isn't all that different from
reporting code bugs. The key is to be specific and precise.
On first sight i do not see any manual page bug reports here:
https://marc.info/?a=171579173100001
If you know about any documentation bug, please send a specific
report. Even though it does occasionally happen that some
developers are overworked or distracted, such reports will
almost always get looked at.
Yours,
Ingo
