Date: Wed, 19 Mar 2014 14:28:15 -0600 (MDT) From: Warren Block <wblock@wonkity.com> To: John Baldwin <jhb@freebsd.org> Cc: jilles@freebsd.org, freebsd-current@freebsd.org, Mariusz Zaborski <oshogbo@freebsd.org>, freebsd-arch@freebsd.org Subject: Re: Hello fdclose Message-ID: <alpine.BSF.2.00.1403191407240.52822@wonkity.com> In-Reply-To: <201403191523.33275.jhb@freebsd.org> References: <CAGOYWV80vTTQbvSjvNa6XBzBiKy%2BjnGantkUH_RO=8prxoHmyQ@mail.gmail.com> <201403181404.52197.jhb@freebsd.org> <alpine.BSF.2.00.1403182230140.45496@wonkity.com> <201403191523.33275.jhb@freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.00.1403191407240.52822>