From owner-freebsd-doc@FreeBSD.ORG Fri Oct 14 07:02:23 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 57164106564A for ; Fri, 14 Oct 2011 07:02:23 +0000 (UTC) (envelope-from yanegomi@gmail.com) Received: from mail-qw0-f54.google.com (mail-qw0-f54.google.com [209.85.216.54]) by mx1.freebsd.org (Postfix) with ESMTP id 157958FC1D for ; Fri, 14 Oct 2011 07:02:22 +0000 (UTC) Received: by qadz30 with SMTP id z30so785917qad.13 for ; Fri, 14 Oct 2011 00:02:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:content-transfer-encoding; bh=yMriOmADCgJ7yIwtPeMNZdLA3e1cXsUOdHO0UplNYps=; b=bsmrEvXa2Sij1M40iRer4i2zx3XePjyINoufWKyLpqcIfzSEAhRhF4MB2qjgK9sexN r6b3iFKT21X0GCtgHgw588MFA+094UTo3UIauIGmvv8Bxlq4JcXuHN2T/AhCJ8aAfQxt YksSvQ5LoMmBncJD3BPwXm34U5YfbNRkIiRlE= MIME-Version: 1.0 Received: by 10.224.213.2 with SMTP id gu2mr5892651qab.85.1318575742368; Fri, 14 Oct 2011 00:02:22 -0700 (PDT) Received: by 10.224.74.82 with HTTP; Fri, 14 Oct 2011 00:02:22 -0700 (PDT) In-Reply-To: References: <201110121030.p9CAUDxd032245@freefall.freebsd.org> Date: Fri, 14 Oct 2011 00:02:22 -0700 Message-ID: From: Garrett Cooper To: Warren Block Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable 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 07:02:23 -0000 On Thu, Oct 13, 2011 at 11:37 PM, Warren Block wrote: > 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? =A0A 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. =A0This provides uniform= ity >>> >>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 ^^^^^^ >>> "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 > =A0large projects like &os;. =A0Code should follow the &os; coding styles > =A0described in &man.style.9;, and &man.style.Makefile.5;. Sounds ok. > As an alternate: > > We know you've developed some fancy coding style of your own. =A0So > =A0has everybody else. =A0Hundreds of people, maybe even thousands, have > =A0contributed to &os;, and mixing all those different styles results in > =A0a mess. =A0So we're sorry, but do it as shown in &man.style.9; =A0and > =A0&man.style.Makefile.5; if you want your code to be accepted. :].