From owner-freebsd-doc@FreeBSD.ORG Fri Oct 14 06:37:30 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 ED556106564A for ; Fri, 14 Oct 2011 06:37:30 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) by mx1.freebsd.org (Postfix) with ESMTP id 8C5FD8FC08 for ; Fri, 14 Oct 2011 06:37:30 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.5/8.14.5) with ESMTP id p9E6bT18051776; Fri, 14 Oct 2011 00:37:29 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.5/8.14.5/Submit) with ESMTP id p9E6bTIE051773; Fri, 14 Oct 2011 00:37:29 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Fri, 14 Oct 2011 00:37:29 -0600 (MDT) From: Warren Block To: Garrett Cooper In-Reply-To: Message-ID: References: <201110121030.p9CAUDxd032245@freefall.freebsd.org> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: MULTIPART/MIXED; BOUNDARY="-902635197-1056568125-1318574249=:51585" X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.2.7 (wonkity.com [127.0.0.1]); Fri, 14 Oct 2011 00:37:29 -0600 (MDT) 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 06:37:31 -0000 This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. ---902635197-1056568125-1318574249=:51585 Content-Type: TEXT/PLAIN; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 8BIT On Thu, 13 Oct 2011, Garrett Cooper wrote: > On Thu, Oct 13, 2011 at 9:13 PM, Warren Block wrote: >> On Fri, 14 Oct 2011, Benjamin Kaduk wrote: >> >>> 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 >> >>               ^^^^^^ >> "conform" might be better here. > > I'm usually not touchy feely about wording like this, but unless the > rest of the document is worded in such a standoffish / cold manner, I > would just keep things polite and neutral. "Conform" sounds really > pushy and "When working in a..." sounds condescending in my opinion. Here's a rewrite: Consistent coding style is extremely important, particularly with large projects like &os;. Code should follow the &os; coding styles described in &man.style.9;, and &man.style.Makefile.5;. As an alternate: We know you've developed some fancy coding style of your own. So has everybody else. Hundreds of people, maybe even thousands, have contributed to &os;, and mixing all those different styles results in a mess. So we're sorry, but do it as shown in &man.style.9; and &man.style.Makefile.5; if you want your code to be accepted. ---902635197-1056568125-1318574249=:51585--