From owner-freebsd-doc@FreeBSD.ORG Fri Oct 14 04:04:59 2011 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id BAEC21065670 for ; Fri, 14 Oct 2011 04:04:59 +0000 (UTC) (envelope-from kaduk@mit.edu) Received: from dmz-mailsec-scanner-6.mit.edu (DMZ-MAILSEC-SCANNER-6.MIT.EDU [18.7.68.35]) by mx1.freebsd.org (Postfix) with ESMTP id 599C58FC12 for ; Fri, 14 Oct 2011 04:04:58 +0000 (UTC) X-AuditID: 12074423-b7f756d0000008d0-be-4e97b4eaa533 Received: from mailhub-auth-1.mit.edu ( [18.9.21.35]) by dmz-mailsec-scanner-6.mit.edu (Symantec Messaging Gateway) with SMTP id 89.B7.02256.AE4B79E4; Fri, 14 Oct 2011 00:04:58 -0400 (EDT) Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103]) by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id p9E44wK3020992; Fri, 14 Oct 2011 00:04:58 -0400 Received: from multics.mit.edu (MULTICS.MIT.EDU [18.187.1.73]) (authenticated bits=56) (User authenticated as kaduk@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id p9E44uGu011733 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Fri, 14 Oct 2011 00:04:57 -0400 (EDT) Received: (from kaduk@localhost) by multics.mit.edu (8.12.9.20060308) id p9E44t7O022231; Fri, 14 Oct 2011 00:04:55 -0400 (EDT) Date: Fri, 14 Oct 2011 00:04:55 -0400 (EDT) From: Benjamin Kaduk To: bcr@freebsd.org In-Reply-To: <201110121030.p9CAUDxd032245@freefall.freebsd.org> Message-ID: References: <201110121030.p9CAUDxd032245@freefall.freebsd.org> User-Agent: Alpine 1.10 (GSO 962 2008-03-14) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFupnleLIzCtJLcpLzFFi42IR4hRV1n21ZbqfweY3Qhbnj6hbnDrTxWrx pu8wowOzx4xP81k8ds66yx7AFMVlk5Kak1mWWqRvl8CV8a3tP3vBNJmKNZtmsDUwThbvYuTk kBAwkdi7dB4zhC0mceHeerYuRi4OIYF9jBJbX95lhnA2MEo03J4L5Rxgkrjw5AAjSIuQQAOj xILNViA2i4C2xPJn69lBbDYBFYmZbzaygdgiAsISEyf0gdnMAm4Sy1/2gPUKCwRJTFq2CCzO KWAv8XrGZrAzeIHs5609UPPtJD6+XsoKYosK6Eis3j+FBaJGUOLkzCcsEDMtJf6t/cU6gVFw FpLULCSpBYxMqxhlU3KrdHMTM3OKU5N1i5MT8/JSi3TN9HIzS/RSU0o3MYJClt1FeQfjn4NK hxgFOBiVeHgzpaf7CbEmlhVX5h5ilORgUhLlvbYRKMSXlJ9SmZFYnBFfVJqTWnyIUYKDWUmE d2YbUI43JbGyKrUoHyYlzcGiJM4rs9PBT0ggPbEkNTs1tSC1CCYrw8GhJMFrAoxNIcGi1PTU irTMnBKENBMHJ8hwHqDhuzaBDC8uSMwtzkyHyJ9itOd43HnoJCPH3KkgctJsEHlpydGTjEIs efl5qVLivG4gowVA2jJK8+Amw9LRK0ZxoEeFeQ1AqniAqQxu9iugtUxAa1dLg60tSURISTUw rn+0h/Ffe6eG42GhKx9rTjqYfr2anH3hB1/9DaczUuKbDB5bHyiIsdC9dX/d9j86anxme/Uv lbhMTI7dHD5FfOMEh+mHZi/4s/7RhhP3bMwyrGY650v8seTpE51120F+whav0PB0qRs6Rg7X tHfc2Rtc6543IeGaGIPuG1YG90rO81q8n6d9VGIpzkg01GIuKk4EACfUEB4iAwAA Cc: Niclas Zeising , freebsd-doc@freebsd.org Subject: Re: docs/160696: style(9) should be mentioned in the devs' handbook X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 14 Oct 2011 04:04:59 -0000 On Wed, 12 Oct 2011, Niclas Zeising wrote: > The following reply was made to PR docs/160696; it has been noted by GNATS. > > From: Niclas Zeising > To: bug-followup@FreeBSD.org, radiomlodychbandytow@o2.pl > Cc: > Subject: Re: docs/160696: style(9) should be mentioned in the devs' handbook > Date: Wed, 12 Oct 2011 12:29:19 +0200 > > This is a multi-part message in MIME format. > --------------090008080408060608000208 > Content-Type: text/plain; charset=ISO-8859-1; format=flowed > Content-Transfer-Encoding: 7bit > > Hi! > Here is a patch that adds a section to the source tree guidelines and > policies chapter of the developer's handbook about code style, with > links to relevant manual pages. It has not been build tested yet, since > I'm away from my build environment. > -- > Niclas Zeising > > --------------090008080408060608000208 > Content-Type: text/plain; > name="doc.developers-handbook.policies.chapter.sgml.diff" > Content-Transfer-Encoding: 7bit > Content-Disposition: attachment; > filename="doc.developers-handbook.policies.chapter.sgml.diff" > > Index: en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml > =================================================================== > RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml,v > retrieving revision 1.37 > diff -u -d -r1.37 chapter.sgml > --- en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml 7 May 2010 06:33:09 -0000 1.37 > +++ en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml 12 Oct 2011 10:22:12 -0000 > @@ -24,6 +24,19 @@ > > This chapter documents various guidelines and policies in force for > the FreeBSD source tree. > + > + > + Style Guidlines > + style > + > + In a big programming project like the &os; project, it is important > + that everybody involved adheres to the same coding style. This ensures > + that all code looks consistent, and will improve the ability for people > + in the project to read and understand the source. In &os; there are > + two manual pages describing the code style to adhere to. These are > + &man.style.9; and &man.style.Makefile.5;, for c code and make files, C is capitalized, of course. The overall paragraph feels a bit odd, though; maybe like it's written in a more informal style than I would expect? A more standard dry, technical writing version might be: %%%%%%%%%% When working in a large codebase such as the &os; source, it is important to adhere to a common coding style. This provides uniformity amongst the entire code, improving the ability of developers to read, understand, and modify the source without needing to become familiar with different conventions in different areas of the tree. The coding style in use for &os; is described in two manual pages, &man.style.9; and &man.style.Makefile.5;, for C code and makefiles respectively — note that style guidelines are implicit in the formatting of example code as well as in rules that are explicitly mentioned. %%%%%%%%%% Hmm, is it "make file" or "makefile" in this usage? (I presume it does not get capitalized unless it is a Makefile or something like that ...) -Ben > + respectively. > + > > > <makevar>MAINTAINER</makevar> on Makefiles