From owner-svn-src-all@FreeBSD.ORG Tue Sep 17 13:37:31 2013 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id 29C6066E for ; Tue, 17 Sep 2013 13:37:31 +0000 (UTC) (envelope-from bdrewery@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:1900:2254:206c::16:87]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 07913263C for ; Tue, 17 Sep 2013 13:37:31 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.7/8.14.7) with ESMTP id r8HDbUbR091743 for ; Tue, 17 Sep 2013 13:37:30 GMT (envelope-from bdrewery@freefall.freebsd.org) Received: (from bdrewery@localhost) by freefall.freebsd.org (8.14.7/8.14.7/Submit) id r8HDbUNh091737 for svn-src-all@freebsd.org; Tue, 17 Sep 2013 13:37:30 GMT (envelope-from bdrewery) Received: (qmail 76059 invoked from network); 17 Sep 2013 08:37:27 -0500 Received: from unknown (HELO ?10.10.0.24?) (freebsd@shatow.net@10.10.0.24) by sweb.xzibition.com with ESMTPA; 17 Sep 2013 08:37:27 -0500 Message-ID: <52385B12.9030402@FreeBSD.org> Date: Tue, 17 Sep 2013 08:37:22 -0500 From: Bryan Drewery Organization: FreeBSD User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:17.0) Gecko/20130801 Thunderbird/17.0.8 MIME-Version: 1.0 To: Bruce Evans , Hiroki Sato Subject: Re: svn commit: r255486 - in head/lib/libc: gen sys References: <201309120053.r8C0rc7H082015@svn.freebsd.org> <20130912.203612.1272738297998644471.hrs@allbsd.org> <5231A85E.5050802@FreeBSD.org> <20130912222312.K1155@besplex.bde.org> In-Reply-To: <20130912222312.K1155@besplex.bde.org> X-Enigmail-Version: 1.5.2 OpenPGP: id=3C9B0CF9; url=http://www.shatow.net/bryan/bryan.asc Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="xABcW2KhB6G2WN7Oi0uxLsW7QMKiWm4Ie" Cc: svn-src-head@freebsd.org, svn-src-all@freebsd.org, src-committers@freebsd.org X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 17 Sep 2013 13:37:31 -0000 This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --xABcW2KhB6G2WN7Oi0uxLsW7QMKiWm4Ie Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable On 9/12/2013 8:15 AM, Bruce Evans wrote: > On Thu, 12 Sep 2013, Bryan Drewery wrote: >=20 >> On 9/12/2013 6:36 AM, Hiroki Sato wrote: >>> Bryan Drewery wrote >>> in <201309120053.r8C0rc7H082015@svn.freebsd.org>: >>> >>> bd> Author: bdrewery (ports committer) >>> bd> Date: Thu Sep 12 00:53:38 2013 >>> bd> New Revision: 255486 >>> bd> URL: http://svnweb.freebsd.org/changeset/base/255486 >>> bd> >>> bd> Log: >>> bd> Consistently reference file descriptors as "fd". 55 other manpa= ges >=20 > Inconsistently... >=20 >>> bd> used "fd", while these used "d" and "filedes". >=20 > ... About 57 man pages (counting links multiply) in /usr/share/man[23] > still use the POSIX spelling "fildes". Yes I see I did miss a few. >=20 > POSIX never uses the spelling "filedes", at least in the old 2001 > draft7.txt. But it is inconsistent between "fildes" and "fd". In the > old draft, it uses "int fildes" on 67 lines (including for most of the > functions changed in this commit). It uses "int fd" on 40 lines. But > most of the latter are not for prototypes. The only exceptions are > for posix_fadvise() and posix_fallocate(). >=20 > Anyway, this change mainly improves "d" to "fd". "filedes" -> "fd" is = not > so clearly an improvement, but "filedes" was only used in a couple of > files and thus rarely changed. >=20 > I think chroot.2 still has the grammar error "filedescriptors" in > descriptions. Normal English grammar "file descriptors" is used in > about 872 man pages (counting links multiply) in /usr/share/man[23]. I am mostly interested at the moment in updating the variable names, and not the descriptions. >=20 >>> bd> >>> bd> MFC after: 1 week >>> bd> Approved by: gjb >>> bd> Approved by: re (delphij) >>> >>> I think this kind of changes need a consensus because several POSIX >>> functions use "filedes" in the specification document. r254484 by >>> pjd was a similar change (s/type/af/ in gethostbyaddr()). >>> >>> In SUSv4, fdopen() uses "filedes" and openat() uses "fd", for >>> example. Consistency throughout our manual pages is generally good.= >>> However, I also see the benefit of using the same expression as the >>> specification even if it is inconsistent. What do you think? >=20 > Does it really use "filedes"? POSIX still never uses this in the 2007 > draft (austin-d2r.pdf). It uses "fildes" for fdopen(), but "fd" for > fdopendir() and openat(). It still uses "fd" for posix_fadvise() and > posix_fallocate(). I now think that the "fd"s in POSIX are just > style bugs. The normal "fildes" had only rotted to "fd" in 2 places > in 2001, but rotted much further in 2007. >=20 > If we ever copied the POSIX spec to improve FreeBSD man pages, then > it would be painful to make any changes to the text (other than > deshallify, and I wouldn't trust that either). FreeBSD now copies the > POSIX inconsistencies for "fildes" vs "fd" for at least fdopen() and > fdopendir(), although it doesn't copy whole sections of POSIX for these= > functions (or any at all?). >=20 >> I did notice that 'filedes' was referenced in some specs, but it's ver= y >> weird to open multiple manpages and expect 'fd' and find 'd' and rewor= k >> my brain to understand that 'd' or 'filedes' is just a 'fd'. Takes a >> second of thinking. >> >> It was "surprising" to me when I noticed it, especially given how many= >> used 'fd'. >=20 > "fd" is a good abbreviation, but "fildes" is more formal. I actually > prefer "fd" throughout. "fildes" is not such a good abbreviation, sinc= e > it is half-way. Using both is just a style bug that is not quite as > confusing as using "d" and "fd". Using "d", "fd", "fildes" and "filede= s" > was a larger style bug. >=20 > Bruce Should I revert until we can have more discussion on this and what impact it has on maintaining the manpages? --=20 Regards, Bryan Drewery --xABcW2KhB6G2WN7Oi0uxLsW7QMKiWm4Ie Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (MingW32) Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQIcBAEBAgAGBQJSOFsSAAoJEG54KsA8mwz5owsQAIN6hsWNG0m/SKYDaRz/9X/D Byu4GrEf4pb1wQp/Y0WWrPc49uKgsnegGk4cUhOKvMDcl2cG0BFMoGylBfQMKnG1 vanXwkRdwYyA5UJyZhOOWoFUaG17oevdqpRBgZfub2OOMkqvK5f4hoHbLzSMeKDH okQPgT8BitbZfT8O7WA2LnXs6DO9UJIQbvkY1JKVKpoUacl81zY34mF3JhspJTqb yV0zHBzpQZpPc1Cgfrmi0ydqdmjzxgX7RRVrdAFf5t5f/h43QUqbPxiHTm4uDzqe yp09zjGl+WfT616Ctrkx96m/bHVi4apqKyLMCuEVkrTPChJ/GL0T4SOreDLJWT4J fmDVl5rwmnUMNObPF7ls4LvcoQ9vD045JJkzs0J/UqgjuNQXni+bu4Otoyq96gkG APHMfIEqdAIVkeiqBFt4930xWq39eJOeFaIkyx3uopT86RfiIF8ejyRjw1hx50+u +PHsF+Zhp3uUrx+wF0k7KM3vr7ZJV0L34hYYUdiV5GWYZaW3YqKLqj6XVOmEGET+ HIx32naDyh9hOeYSMkKcF4ZcvYfKfkrgTiTl/feob/alN2SLhNGnLZbhEzRxEy4+ klYl7llPRVz2BEGnBqUy6lQ2mBJDE070cflINxbLOEXZ7Dx7+bteoAEXBBsHj+Gm 3gfh6dgyWmbE7pZQUcSL =E3mG -----END PGP SIGNATURE----- --xABcW2KhB6G2WN7Oi0uxLsW7QMKiWm4Ie--