From owner-svn-src-all@FreeBSD.ORG Tue Jul 24 10:40:48 2012 Return-Path: Delivered-To: svn-src-all@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id A4E12106566B; Tue, 24 Jul 2012 10:40:48 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail03.syd.optusnet.com.au (mail03.syd.optusnet.com.au [211.29.132.184]) by mx1.freebsd.org (Postfix) with ESMTP id 1C3B88FC12; Tue, 24 Jul 2012 10:40:47 +0000 (UTC) Received: from c122-106-171-246.carlnfd1.nsw.optusnet.com.au (c122-106-171-246.carlnfd1.nsw.optusnet.com.au [122.106.171.246]) by mail03.syd.optusnet.com.au (8.13.1/8.13.1) with ESMTP id q6OAcnrN009690 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Tue, 24 Jul 2012 20:38:56 +1000 Date: Tue, 24 Jul 2012 20:38:49 +1000 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Garrett Cooper In-Reply-To: Message-ID: <20120724201105.I2548@besplex.bde.org> References: <201207211407.q6LE7h9P042318@svn.freebsd.org> <20120721153026.GA8640@FreeBSD.org> <20120723071227.GE85230@FreeBSD.org> <523C5041-527B-4DBC-85E1-4AE846B014E6@bsdimp.com> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Cc: Alexey Dokuchaev , src-committers@FreeBSD.org, svn-src-all@FreeBSD.org, Gleb Smirnoff , svn-src-head@FreeBSD.org, Warner Losh Subject: Re: svn commit: r238672 - head/sys/dev/sdhci X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 24 Jul 2012 10:40:48 -0000 On Mon, 23 Jul 2012, Garrett Cooper wrote: > On Mon, Jul 23, 2012 at 5:07 PM, Warner Losh wrote: >>[>* trimmed] >> Double spacing is the one true way I learned how to type in school. Since the 1980's though, things have changed and many advocate single spaces. However, that's for folks with fancy variable pitch font and such. For fixed-witdh fonts, 2 is still preferred in some circles, including ours. > > And now that I look at style(9), there are subtleties that > demonstrate this in the roff generated text: > > ================= > > FreeBSD source tree. It is also a guide for the preferred userland code > ^^ > style. Many of the style rules are implicit in the examples. Be careful > ^^ > ^^ > to check the examples before assuming that style is silent on an issue. > > ================= Where's the indentometer when you need it? :-) roff understands formatting, and generates these 2-space sentence breaks automatically for -Tascii, and something different (more like 1.5 spaces?) for proportional fonts. This is provided you don't hard-code sentence breaks in the man page source. Not starting sentences on new lines gives hard-coded sentence breaks a their start. > I wish this point was more explicit, but like style(9), there are > other unspoken rules that should/must be adhered to. style(9) consisted entirely of examples before it was mangled to create a man page. The mangling gave zillions of whitespace errors (mainly for man pages' 5-space indentation and corresponding tab lossage (leading tabs in literal source code become 1 tab followed by 5 spaces)), but there are no examples of single-space sentence breaks in literal source code. Unfortunately, this is because there are almost no examples of sentence breaks in literal source code. There used to be about 25 such examples (in C comments of course), but most of these rotted to meta-descriptions in man page text. In the man page source, all of the latter are correctly formatted (with new sentences on new lines, so that there are no literal spaces. In the man output, these are formatted according to man/roff rules which are unrelated to C style rules and in fact differ for proportional fonts, so they don't provide examples of C style. 4 examples on 3 lines remain. The most relevant one is: " * Multi-line comments look like this. Make them real sentences. Fill ..." Single-space sentence breaks give comments that don't look like this. Bruce