From grog@lemis.com Sun Feb 16 15:37:07 2003 Return-Path: Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 576A637B401; Sun, 16 Feb 2003 15:37:07 -0800 (PST) Received: from wantadilla.lemis.com (wantadilla.lemis.com [192.109.197.80]) by mx1.FreeBSD.org (Postfix) with ESMTP id 58ED543F85; Sun, 16 Feb 2003 15:37:05 -0800 (PST) (envelope-from grog@lemis.com) Received: by wantadilla.lemis.com (Postfix, from userid 1004) id A7D1451A32; Mon, 17 Feb 2003 10:07:02 +1030 (CST) Message-Id: <20030216233702.GB37125@wantadilla.lemis.com> Date: Mon, 17 Feb 2003 10:07:02 +1030 From: Greg 'groggy' Lehey To: Tom Rhodes Cc: Per Hedeland , freebsd-doc@FreeBSD.org, FreeBSD-gnats-submit@FreeBSD.org, Bruce Evans In-Reply-To: <20030216174334.2cf7984a.trhodes@FreeBSD.org> Subject: Code matching docco? (was: docs/48125: [PATCH] Incorrect errno strings in intro(2)) References: <200302162130.h1GLUGKE037248@freefall.freebsd.org> <20030216174334.2cf7984a.trhodes@FreeBSD.org> >Number: 48348 >Category: junk >Synopsis: Code matching docco? (was: docs/48125: [PATCH] Incorrect errno strings in intro(2)) >Confidential: no >Severity: serious >Priority: medium >Responsible: ceri >State: closed >Quarter: >Keywords: >Date-Required: >Class: sw-bug >Submitter-Id: current-users >Arrival-Date: Sun Feb 16 15:40:02 PST 2003 >Closed-Date: Mon Feb 17 13:02:37 PST 2003 >Last-Modified: Mon Feb 17 13:02:37 PST 2003 >Originator: Greg Lehey >Release: >Organization: >Environment: >Description: --/WwmFnJnmDyWGHa4 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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 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 --/WwmFnJnmDyWGHa4 Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.0 (FreeBSD) iD8DBQE+UCCeIubykFB6QiMRAq2aAKCCvLy710/fDxVEgIgBD3x37kxZ7QCeNkVc x+t0YPCkIlnoN/D/hJlMS0E= =EK3O -----END PGP SIGNATURE----- --/WwmFnJnmDyWGHa4-- >How-To-Repeat: >Fix: >Release-Note: >Audit-Trail: State-Changed-From-To: open->closed State-Changed-By: ceri State-Changed-When: Mon Feb 17 13:01:17 PST 2003 State-Changed-Why: Misfiled followup to docs/48125. Responsible-Changed-From-To: gnats-admin->ceri Responsible-Changed-By: ceri Responsible-Changed-When: Mon Feb 17 13:01:17 PST 2003 Responsible-Changed-Why: Take from gnats-admin. http://www.freebsd.org/cgi/query-pr.cgi?pr=48348 >Unformatted: