Re: Hello fdclose

On Wed, 19 Mar 2014, John Baldwin wrote:

> On Wednesday, March 19, 2014 12:38:57 am Warren Block wrote:
>> On Tue, 18 Mar 2014, John Baldwin wrote:
>>
>>> On Monday, March 17, 2014 7:23:19 pm Mariusz Zaborski wrote:
>>>> Hi,
>>>>
>>>> After our previous discuss  [1] I prepare fdclosedir(3) function which
>>>> was committed by Pawel (cc'ed) in commit r254499.
>>>>
>>>> A while ago I also prepare the fdclose function. Unfortunately, this
>>>> new function is a little bit more tricky then previous one. Can I ask
>>>> you for a review of this patch?
>>>
>>> I think the code is fine.  I have a few suggestions on the manpage wording:
>>>
>>> The
>>> +.Fn fdclose
>>> +function is equivalent to the
>>> +.Fn fclose
>>> +function except that this function returns file descriptor instead of
>>> +closing it.
>>> +.Pp
>>> +The
>>>
>>> I would move fdclose() to its own paragraph and reword this sentence as:
>>>
>>>  "The fdclose() function is equivalent to fclose() except that it does
>>>   not close the underlying file descriptor."
>>
>> .Fn fdclose
>> is equivalent to
>> .Fn fclose ,
>> but the file descriptor is returned rather than closed.
>>
>> Likewise in other sections, the markup is supposed to do the job of
>> pointing out that something is a function.
>
> Yes, but this has the 'no capital letter at the start of a sentence' problem.

I've heard that mentioned before, but have never seen any actual rule 
regarding it.  And we do have actual rules about avoiding redundant 
phrases: 
http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/book.html#writing-style-guidelines

While normal words should be capitalized as the first word in a 
sentence, special words that are case-sensitive override that (IMO).

> Also, I do think reusing the 'underlying file descriptor' language is important
> in the context of the earlier description of fclose().

Sorry, a problem with my micro-optimization:

.Fn fdclose
is equivalent to
.Fn fclose ,
but does not close the underlying file descriptor.