Date: Tue, 24 Jul 2012 20:38:49 +1000 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Garrett Cooper <yanegomi@gmail.com> Cc: Alexey Dokuchaev <danfe@FreeBSD.org>, src-committers@FreeBSD.org, svn-src-all@FreeBSD.org, Gleb Smirnoff <glebius@FreeBSD.org>, svn-src-head@FreeBSD.org, Warner Losh <imp@bsdimp.com> Subject: Re: svn commit: r238672 - head/sys/dev/sdhci Message-ID: <20120724201105.I2548@besplex.bde.org> In-Reply-To: <CAGH67wQGd6xWGPW4S=GYss-bjmxdY1AWjHZcBbO3v1yW_3qLsg@mail.gmail.com> References: <201207211407.q6LE7h9P042318@svn.freebsd.org> <20120721153026.GA8640@FreeBSD.org> <20120723071227.GE85230@FreeBSD.org> <CAGH67wR4aug9mF=UDc6w6AuiDyE0LQ7d38ffGDqtWQ_jRt0uKw@mail.gmail.com> <523C5041-527B-4DBC-85E1-4AE846B014E6@bsdimp.com> <CAGH67wQGd6xWGPW4S=GYss-bjmxdY1AWjHZcBbO3v1yW_3qLsg@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, 23 Jul 2012, Garrett Cooper wrote: > On Mon, Jul 23, 2012 at 5:07 PM, Warner Losh <imp@bsdimp.com> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20120724201105.I2548>