svn commit: r238672 - head/sys/dev/sdhci

[Bruce Evans]

On Mon, 23 Jul 2012, Garrett Cooper wrote:

> On Mon, Jul 23, 2012 at 5:07 PM, Warner Losh <imp at 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