Date: Tue, 17 Sep 2013 08:37:22 -0500 From: Bryan Drewery <bdrewery@FreeBSD.org> To: Bruce Evans <brde@optusnet.com.au>, Hiroki Sato <hrs@freebsd.org> Cc: svn-src-head@freebsd.org, svn-src-all@freebsd.org, src-committers@freebsd.org Subject: Re: svn commit: r255486 - in head/lib/libc: gen sys Message-ID: <52385B12.9030402@FreeBSD.org> In-Reply-To: <20130912222312.K1155@besplex.bde.org> References: <201309120053.r8C0rc7H082015@svn.freebsd.org> <20130912.203612.1272738297998644471.hrs@allbsd.org> <5231A85E.5050802@FreeBSD.org> <20130912222312.K1155@besplex.bde.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <bdrewery@FreeBSD.org> 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--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?52385B12.9030402>