From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 49348 invoked by alias); 18 May 2017 12:32:30 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Received: (qmail 48925 invoked by uid 89); 18 May 2017 12:32:29 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.4 required=5.0 tests=AWL,BAYES_00,RCVD_IN_SORBS_SPAM,RP_MATCHES_RCVD,SPF_PASS autolearn=no version=3.3.2 spammy=joke, wind, super X-HELO: mailbackend.panix.com X-Gm-Message-State: AODbwcBY0EnYpOaiJWtBRjYFPG1Vn8qmX8JhTKBNLLdrjFxLI84In4wq RT07LAUCZ5O7kXwjt1L6EiFuSlOw4w== X-Received: by 10.36.131.137 with SMTP id d131mr4315448ite.113.1495110748616; Thu, 18 May 2017 05:32:28 -0700 (PDT) MIME-Version: 1.0 In-Reply-To: <96efa163-cda4-443e-4182-0ec281517eec@pacific.net> References: <58d7508efdc950d8b6bb53532b290845a9affa9c.1494920105.git.ricaljasan@pacific.net> <96efa163-cda4-443e-4182-0ec281517eec@pacific.net> From: Zack Weinberg Date: Thu, 18 May 2017 12:32:00 -0000 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: [PATCH v3 4/7] manual: Refactor errno @comments. To: Rical Jasan Cc: Joseph Myers , GNU C Library , "Carlos O'Donell" , Michael Kerrisk Content-Type: text/plain; charset="UTF-8" X-SW-Source: 2017-05/txt/msg00533.txt.bz2 On Thu, May 18, 2017 at 5:42 AM, Rical Jasan 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