Bug 48125
| Summary: | [PATCH] Incorrect errno strings in intro(2) | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | per | ||||
| Component: | Books & Articles | Assignee: | freebsd-doc (Nobody) <doc> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | ||||||
| Priority: | Normal | ||||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
I really like everything you've done here, thanks alot for the time you have spent. However I have but one comment. :) -.It Er 49 EADDRNOTAVAIL Em "Cannot assign requested address" . +.It Er 49 EADDRNOTAVAIL Em "Can't assign requested address" . Normally results from an attempt to create a socket with an address not on this machine. .It Er 50 ENETDOWN Em "Network is down" . @@ -341,7 +341,7 @@ An request to send or receive data was disallowed because the socket was not connected and (when sending on a datagram socket) no address was supplied. -.It Er 58 ESHUTDOWN Em "Cannot send after socket shutdown" . +.It Er 58 ESHUTDOWN Em "Can't send after socket shutdown" . A request to send data was disallowed because the socket had already been shut down with a previous .Xr shutdown 2 In both of these hunks we are using contractions, something we have tried to avoid completely in the doc project. Personally, this is one time I would like the code to be customed to the manual page. In other words, I would like the output errors to be changed to match the manual page instead of the other way around. I can do this sometime soon, however if you have a patch I can do it sooner :) -- Tom Rhodes Well, I'm glad you appreciated it, but it really wasn't a major effort or anything - mostly just a bit of awk'ing on the respective sources.:-) However, regarding the contractions: I can see where you're coming from, since I gather that using them in "formal" documents is frowned upon - but I must really strongly disagree with your suggestion to change the code! The output of programs should not be changed for such "frivolous" reasons - e.g. there may well be scripts etc out there that, however unwisely, rely on the exact format of error messages to function correctly. Not to mention that using contractions in error messages is a long-standing Unix tradition, even in cases where the message doesn't originate in sys_errlist. I'd suggest that either you consider these strings to not be part of the actual "document text" (which would be correct I think), and thereby exempt from considerations of "good writing style" - or if that isn't acceptable, leave the "Cannot"s in the man page and the "Can't"s in the code - this discrepancy shouldn't matter *too* much to the reader, who is unlikely to be searching the man page for "Can't" anyway... --Per Hedeland On Sun, 16 Feb 2003 13:30:16 -0800 (PST) Per Hedeland <per@hedeland.org> wrote: > However, regarding the contractions: I can see where you're coming > from, since I gather that using them in "formal" documents is frowned > upon - True, > but I must really strongly disagree with your suggestion to change > the code! The output of programs should not be changed for such > "frivolous" reasons - e.g. there may well be scripts etc out there > that, however unwisely, rely on the exact format of error messages to > function correctly. Not to mention that using contractions in error > messages is a long-standing Unix tradition, even in cases where the > message doesn't originate in sys_errlist. however to my knowledge when Bell Labs originally started producing UNIX the code was actually changed to match the documentation in many instances. People with more knowledge of UNIX history would be better to ask about that, though. I just remember reading something like that, Bruce Evans (bde) or Greg Lehey (grog) come to mind as the correct people to ask. > > I'd suggest that either you consider these strings to not be part of > the actual "document text" (which would be correct I think), and > thereby exempt from considerations of "good writing style" - or if > that isn't acceptable, leave the "Cannot"s in the man page and the > "Can't"s in the code - this discrepancy shouldn't matter *too* much > to the reader, who is unlikely to be searching the man page for > "Can't" anyway... To the best of my knowledge, use of contractions is frowned upon in FreeBSD. Again, this is an issue to take up with the respected parties. I've taken the liberty to cc: them for input. Ideas? -- Tom Rhodes Well, I think this issue taking on rather bigger proportions than it really merits, but anyway... Tom Rhodes <trhodes@FreeBSD.org> wrote: >Per Hedeland <per@hedeland.org> wrote: >> but I must really strongly disagree with your suggestion to change >> the code! The output of programs should not be changed for such >> "frivolous" reasons - e.g. there may well be scripts etc out there >> that, however unwisely, rely on the exact format of error messages to >> function correctly. Not to mention that using contractions in error >> messages is a long-standing Unix tradition, even in cases where the >> message doesn't originate in sys_errlist. > >however to my knowledge when Bell Labs originally started producing >UNIX the code was actually changed to match the documentation in many >instances. People with more knowledge of UNIX history would be better >to ask about that, though. I just remember reading something like that, >Bruce Evans (bde) or Greg Lehey (grog) come to mind as the correct >people >to ask. Whether correct or not, I don't really see the relevance of that. Of course I didn't suggest that code must *never* be changed to match documentation, only that code changes that may actually break things should not be done just to match someone's idea of "good writing style" for the man page. On the other hand, in this particular case the FreeBSD (or *BSD, I don't have another dialect to test) code might actually be a bit out-of-sync with the rest of the Unix family. A survey of two other Unices isn't exactly conclusive, and there's nothing to say that FreeBSD must be like everyone else, but anyway: Solaris 8: $ ./a.out bind: Cannot assign requested address RedHat 7.3: $ ./a.out bind: Cannot assign requested address FreeBSD 5.0-RELEASE: $ ./a.out bind: Can't assign requested address The same difference exists for the other messages that are contractions in the FreeBSD sys_errlist[]. And with that "contribution" I will respectfully leave this discussion, letting the committers sort out what should be changed where and why. --Per Adding to audit trail from pending/48348: Message-Id: <20030216233702.GB37125@wantadilla.lemis.com> Date: Mon, 17 Feb 2003 10:07:02 +1030 From: Greg 'groggy' Lehey <grog@FreeBSD.org> To: Tom Rhodes <trhodes@FreeBSD.org> Cc: Per Hedeland <per@hedeland.org>, freebsd-doc@FreeBSD.org, FreeBSD-gnats-submit@FreeBSD.org, Bruce Evans <bde@FreeBSD.org> On Sunday, 16 February 2003 at 17:43:34 -0500, Tom Rhodes wrote: > On Sun, 16 Feb 2003 13:30:16 -0800 (PST) > Per Hedeland <per@hedeland.org> wrote: > >> However, regarding the contractions: I can see where you're coming >> from, since I gather that using them in "formal" documents is frowned >> upon - > > True, > >> but I must really strongly disagree with your suggestion to change >> the code! The output of programs should not be changed for such >> "frivolous" reasons - e.g. there may well be scripts etc out there >> that, however unwisely, rely on the exact format of error messages to >> function correctly. Not to mention that using contractions in error >> messages is a long-standing Unix tradition, even in cases where the >> message doesn't originate in sys_errlist. > > however to my knowledge when Bell Labs originally started producing > UNIX the code was actually changed to match the documentation in > many instances. People with more knowledge of UNIX history would be > better to ask about that, though. I just remember reading something > like that, Bruce Evans (bde) or Greg Lehey (grog) come to mind as > the correct people to ask. This seems unlikely. The same people wrote the code and the docco; it's unlikely that changes in the docco would make it out of sync with the code base. It's possible, of course, that they occasionally wrote docco changes first with the intention to change the code, and then did it, but I don't suppose that's what you're talking about. >> I'd suggest that either you consider these strings to not be part of >> the actual "document text" (which would be correct I think), and >> thereby exempt from considerations of "good writing style" - or if >> that isn't acceptable, leave the "Cannot"s in the man page and the >> "Can't"s in the code - this discrepancy shouldn't matter *too* much >> to the reader, who is unlikely to be searching the man page for >> "Can't" anyway... > > To the best of my knowledge, use of contractions is frowned upon in > FreeBSD. Again, this is an issue to take up with the respected parties. > I've taken the liberty to cc: them for input. Ideas? I don't know about the project, but I frown on some contractions and not others. In general, if the contraction is used in normal speech ("can't") I'd think it's OK. If it isn't ("cont'd"), I'd disagree with its use. Greg -- See complete headers for address and phone numbers State Changed From-To: open->patched Applied. 1 failed (already fixed) and another required some manual merging. The contractions were not applied. State Changed From-To: patched->closed Applied! Thanks for the submission! |
Several of the strings given in intro(2) a.k.a. 'man errno' do not agree with what is actually output by programs using perror() etc, making problem resolution unnecessarily difficult. Fix: Apply patch below against $FreeBSD: src/lib/libc/sys/intro.2,v 1.36 2002/12/12 17:25:53 ru Exp $ How-To-Repeat: Do something that generates the error message "Device not configured." Try to find the corresponding errno value and explanation via 'man errno', and fail. Grep errlst.c while muttering the L-word.