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

[Rical Jasan <ricaljasan at pacific dot net>]

On 05/16/2017 04:06 AM, Joseph Myers wrote:
> On Tue, 16 May 2017, Rical Jasan wrote:
>> errno.texi contains a large number of standards annotations which also
>> document the error string on the same line.  The surrounding
>> commentary indicates this information should be retained, so it is
>> moved to the subsequent comment documenting the error code value.  In
>> many cases, there was a redundant "@c DO NOT REMOVE" comment, which
>> was relocated to the front.  Additionally, a number of "Linux???"
>> standards appeared under a section of the manual stating the following
>> errors came from Linux, so the question marks were removed.
> 
> Have you made sure that the generated sysdeps/gnu/errlist.c is unchanged 
> by this patch?

No.

> And sysdeps/mach/hurd/bits/errno.h (you might need to 
> figure out what commands to run by hand for that one, in the absence of a 
> way to build a cross compiler and glibc for Hurd).  (NaCl also generates 
> bits/errno.h - not checked in for NaCl - from errno.texi, but that port 
> should be going away soon.)

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

Custom macros are provided by the language for a reason, and even if we
use them merely as flags for external scripts, anyone who sees them and
wants to change them will eventually wind up in macros.texi, where a
comment can be waiting explaining what exactly depends on them and why.

In the meantime, the standards in the Summary will simply continue to be
rendered with the error string.

Rical