From owner-freebsd-current@FreeBSD.ORG Wed Mar 19 20:28:17 2014 Return-Path: Delivered-To: freebsd-current@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id E3C77E30; Wed, 19 Mar 2014 20:28:17 +0000 (UTC) Received: from wonkity.com (wonkity.com [67.158.26.137]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 76C5B9C7; Wed, 19 Mar 2014 20:28:17 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.8/8.14.8) with ESMTP id s2JKSFDo053021 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO); Wed, 19 Mar 2014 14:28:15 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.8/8.14.8/Submit) with ESMTP id s2JKSF6w053018; Wed, 19 Mar 2014 14:28:15 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Wed, 19 Mar 2014 14:28:15 -0600 (MDT) From: Warren Block To: John Baldwin Subject: Re: Hello fdclose In-Reply-To: <201403191523.33275.jhb@freebsd.org> Message-ID: References: <201403181404.52197.jhb@freebsd.org> <201403191523.33275.jhb@freebsd.org> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Wed, 19 Mar 2014 14:28:15 -0600 (MDT) Cc: jilles@freebsd.org, freebsd-current@freebsd.org, Mariusz Zaborski , freebsd-arch@freebsd.org X-BeenThere: freebsd-current@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: Discussions about the use of FreeBSD-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 19 Mar 2014 20:28:18 -0000 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.