Date: Thu, 12 Sep 2013 23:15:41 +1000 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Bryan Drewery <bdrewery@freebsd.org> Cc: svn-src-head@freebsd.org, svn-src-all@freebsd.org, Hiroki Sato <hrs@freebsd.org>, src-committers@freebsd.org Subject: Re: svn commit: r255486 - in head/lib/libc: gen sys Message-ID: <20130912222312.K1155@besplex.bde.org> In-Reply-To: <5231A85E.5050802@FreeBSD.org> References: <201309120053.r8C0rc7H082015@svn.freebsd.org> <20130912.203612.1272738297998644471.hrs@allbsd.org> <5231A85E.5050802@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 12 Sep 2013, Bryan Drewery wrote: > 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 manpages Inconsistently... >> bd> used "fd", while these used "d" and "filedes". ... About 57 man pages (counting links multiply) in /usr/share/man[23] still use the POSIX spelling "fildes". 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(). 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. 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]. >> 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? 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. 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?). > I did notice that 'filedes' was referenced in some specs, but it's very > weird to open multiple manpages and expect 'fd' and find 'd' and rework > 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'. "fd" is a good abbreviation, but "fildes" is more formal. I actually prefer "fd" throughout. "fildes" is not such a good abbreviation, since 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 "filedes" was a larger style bug. Bruce
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20130912222312.K1155>