svn commit: r255486 - in head/lib/libc: gen sys

[Bryan Drewery]

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 <bdrewery at FreeBSD.org> wrote
>>>   in <201309120053.r8C0rc7H082015 at 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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 899 bytes
Desc: OpenPGP digital signature
URL: <http://lists.freebsd.org/pipermail/svn-src-all/attachments/20130917/b4fd836f/attachment.sig>