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

[Rical Jasan <ricaljasan at pacific dot net>]

On 05/18/2017 05:32 AM, Zack Weinberg wrote:
> 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

We could render the error strings with @errno so that the errors, codes,
and strings are only recorded once, and also protected by the nature of
using a custom macro.

> people get an error that they don't know what it means, they can
> search the manual for it.

@errno can generate a @cindex for them too, so the string still only
needs to be recorded once, and, e.g., "Operation not permitted" winds up
in the Concept Index.

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

Yeah, the whole thing.  :)

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

Are error "numbers" (e.g., 27) system-specific, or did you mean error
constants there too (e.g., EPERM)?

I'm not exactly sure what information you would want to convey with it,
or how (thinking of rendering), but we could extend @errno in some way,
I suppose:

@errnox{EKERN_TIMEDOUT, 27, Mach, Kernel operation timed out}

Maybe defined like:

@macro errnox {err, val, sys, msg}
@cindex \msg\
\msg\.  Specific to \sys\.

@end macro

(I used @*x there since many of the errors may be common across systems,
so we may not want to render the "Specific to ..."; something that
doesn't look like a list might be better, like @syserrno.)

Is that along the lines of what you were getting at?

> 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.)

There are a lot of blank descriptions, descriptions that are nothing but
the error string repeated, long descriptions that don't repeat the error
string verbatim, missing error values, and missing errors.  I don't mind
picking this up next.

I submitted a v4 for this patchset that changes the patch for this
thread to use @errno.  It takes a conservative approach to changing
errlist.awk and errnos.awk, amounting to little more than a refactoring
of the errno.texi processing.  It will have to be rebased if your work
goes in first, but I figured it best to post it so it can get reviewed
in the meantime.

Rical