Re: [PATCH v3 4/7] manual: Refactor errno @comments.

[Zack Weinberg <zackw@panix.com>]

On Thu, May 18, 2017 at 5:42 AM, Rical Jasan <ricaljasan@pacific.net> wrote:
> On 05/17/2017 06:21 AM, Zack Weinberg wrote:
>
>> I think the error *numbers* shouldn't be embedded in the manual.  Only
>
> I had the same thought; very surprising to find the sources were being
> generated from the manual.  I also thought it was strange because I
> remember a conversation a while back where it was pointed out the source
> and documentation are under different licences and generally couldn't
> cross-reference each other like that. [1]  That conversation should have
> been on libc-alpha, but happened on libc-help (my fault).

Abstractly, it is important for the exact (English) text of the
strerror() messages to appear verbatim in the manual, so that when
people get an error that they don't know what it means, they can
search the manual for it. Given that, it's obviously desirable not to
have to maintain them in two places, and since errlist.c has been
generated from errnos.texi for a very long time, I don't think we have
to worry about the legalities of copying between GPL and GFDL files.

I'd personally prefer to keep the strerror messages in the manual
because then they are right next to the longer descriptions of what
the error means, and people editing the manual will know that the
longer description needs to make sense of the strerror message. This
isn't super important, since this part of the manual hasn't changed
much in many years, but on the other hand, it may be time for someone
to go through the whole manual and revise it...

A counterargument is that each kernel port may have its own additional
error constants that should be documented, and conversely, the manual
should make really clear which error numbers are system-specific.
Right now all of Linux's error constants appear in the manual, but a
whole bunch of Hurd error constants don't (the ones starting with
EMACH_, EKERN_, EMIG_, and ED_ - which may mean they don't wind up in
errlist.c and strerror() doesn't work for them, which is bad) and
quite a few constants that do appear in the manual don't have
definitions on Linux:

EAUTH
EBACKGROUND
EBADRPC
ED
EDIED
EFTYPE
EGRATUITOUS
EGREGIOUS
EIEIO
ENEEDAUTH
EPROCLIM
EPROCUNAVAIL
EPROGMISMATCH
EPROGUNAVAIL
ERPCMISMATCH

(I also notice that there are a lot of errors that don't *have* long
descriptions, but that's a separate issue.)

(Was it really necessary to have *four* joke error constants?  That's
a rhetorical question.)

zw