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

[Rical Jasan <ricaljasan@pacific.net>]

On 05/17/2017 06:21 AM, Zack Weinberg wrote:
> On Wed, May 17, 2017 at 12:44 AM, Rical Jasan <ricaljasan@pacific.net> >
>> I was unaware of these dependencies---thanks for pointing them out.
>> Nothing I've encountered indicated their existence, though "DO NOT
>> REMOVE" makes a little more sense.
>>
>> After hacking on this a bit, I think this patch should be rescinded.
>> Fixing the errlist.awks is easy, but it does nothing to help the screwy,
>> Texinfo @comment-based dependency that is just asking for trouble.  I'd
>> like to propose an @errno{} macro to handle these, and then update the
>> errlist.awks accordingly.  Something like:
>>
>>   @errno{EPERM, 1, Operation not permitted}
>>
>> should make the Awk scripts practically benign...
> 
> This seems like a reasonable plan to me.  Note that
> https://sourceware.org/ml/libc-alpha/2017-05/msg00198.html also makes
> changes in this area.

Thanks for the heads-up on the pending changes.  I've started a patch
for this, adding @errno, converting the @comments in errno.texi, and
updating sysdeps/gnu/errlist.awk so the generated errlist.c is
unchanged, but I also want to add some consistency checking to it.  I
looked at sysdeps/mach/hurd/errnos.awk; seems to be similar.  I'll get
it started and make sure to follow your work.  I'll ignore the NaCl bits
since it sounds like that's going away soon.

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

> Hurd uses these, and so it's not obvious that this part of the manual
> has ABI implications but only for Hurd.  It would be better if those
> came from a sysdeps/ file - sysdeps/mach/hurd/bits/errno.h.in maybe?
> It can't just be sysdeps/mach/hurd/bits/errno.h because the Hurd
> errnos.awk pulls additional error numbers from several other places
> (unfortunately, all of them are Mach headers that aren't in tree,
> IIRC).

This is.. interesting.  If we do make a
sysdeps/mach/hurd/bits/errno.h.in, it seems doing similarly for
sysdeps/gnu/errlist.c would be the way to go, removing the dependency on
the manual entirely (errlist.c is only generated from errno.texi).
Separate input files for each is still quite a bit of duplication though
(E* macros and error strings), so maybe an equivalent to the proposed
@errno in something like misc/errno.? that both scripts could use would
be more suitable?

For now, I'll stick with using @errno in errno.texi, and figure out a
way to validate the generated Hurd errno.h.

Rical

[1] https://sourceware.org/ml/libc-help/2016-10/msg00015.html