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

[Zack Weinberg <zackw at panix dot com>]

On 05/19/2017 05:46 AM, Rical Jasan wrote:
> 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
>> people get an error that they don't know what it means, they can
>> search the manual for it.
> 
> 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.
> 
> @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.

Yeah, that sounds good.

>> 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 meant constants.  The numbers are only part of the ABI, not the API -
they don't need to be visible in the manual at all.

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

I was thinking more like we would have subsections for standard error
constants, BSD error constants, Hurd error constants, etc., but we don't
have to make that decision right now - that can be for whoever
eventually gets around to revising this part of the manual for real.

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

That seems like a good way forward.  I'll look at your patches shortly.

zw