On 9/12/2013 8:15 AM, Bruce Evans wrote: > On Thu, 12 Sep 2013, Bryan Drewery wrote: > >> On 9/12/2013 6:36 AM, Hiroki Sato wrote: >>> Bryan Drewery <bdrew...@freebsd.org> wrote >>> in <201309120053.r8c0rc7h082...@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".
Yes I see I did miss a few. > > 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]. I am mostly interested at the moment in updating the variable names, and not the descriptions. > >>> 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 Should I revert until we can have more discussion on this and what impact it has on maintaining the manpages? -- Regards, Bryan Drewery
signature.asc
Description: OpenPGP digital signature