Bug 486520

Summary: Preface headings and revision history should use sentence caps
Product: [Community] Publican Reporter: Murray McAllister <mmcallis>
Component: publicanAssignee: Brian Forte <bforte>
Status: CLOSED WONTFIX QA Contact: Joshua Wulf <jwulf>
Severity: medium Docs Contact:
Priority: low    
Version: 2.0CC: daobrien, jfearn, lcarlon, mhideo, mmcallis, publican-list, r.landmann, vdanen
Target Milestone: ---Keywords: Documentation
Target Release: ---   
Hardware: All   
OS: Linux   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2009-10-01 20:36:22 EDT Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:

Description Murray McAllister 2009-02-19 23:28:25 EST
Description of problem:

Preface does not use sentence caps:

Preface

    1. Document Conventions

        1.1. Typographic Conventions
        1.2. Pull-quote Conventions
        1.3. Notes and Warnings

    2. We Need Feedback!

A. Revision History

Version-Release number of selected component (if applicable):
publican-0.42-0.el5


Expected results:
Headings in Preface and Revision History should use sentence caps.
Comment 1 Michael Hideo 2009-06-16 21:55:53 EDT
Hi Murray, i can't seem to find this bug, can you give me an example pointer? - Mike

(In reply to comment #0)
> Description of problem:
> 
> Preface does not use sentence caps:
> 
> Preface
> 
>     1. Document Conventions
> 
>         1.1. Typographic Conventions
>         1.2. Pull-quote Conventions
>         1.3. Notes and Warnings
> 
>     2. We Need Feedback!
> 
> A. Revision History
> 
> Version-Release number of selected component (if applicable):
> publican-0.42-0.el5
> 
> 
> Expected results:
> Headings in Preface and Revision History should use sentence caps.
Comment 2 David O'Brien 2009-06-17 00:02:46 EDT
Why? All our headings have traditionally been in title caps (if you take title caps to exclude is, on, in, and, the, and similar words). Is there any reason for the Preface and Revision History demanding a different heading style?
Comment 3 Brian Forte 2009-06-17 00:23:30 EDT
Title Case rules in English vary wildly.

1. ALL CAPS
THE WATER DAMAGE IS IN HER FAUX ARMENIAN CATHEDRAL WING

2. Initial caps for everything:
The Water Damage Is In Her Faux Armenian Cathedral Wing

3. Initial caps for everything, except non-initial articles, prepositions and conjunctions:
The Water Damage Is in Her Faux Armenian Cathedral Wing

4. Initial caps for everything, except non-initial articles; prepositions; conjunctions & ‘to be’ forms:
The Water Damage is in Her Faux Armenian Cathedral Wing

5. Initial caps for everything, except non-initial closed-class*
The Water Damage is in her Faux Armenian Cathedral Wing

6. Initial caps for nouns and the 1st word:
The Water Damage is in her faux Armenian Cathedral Wing

7. Standard sentence case (ie first word takes an initial cap as do proper nouns):
The water damage is in her faux Armenian cathedral wing

8. all lowercase
the water damage is in her faux armenian cathedral wing

Of these eight, numbers five and seven are the most common. Very roughly speaking, style five is US editorial practice and style seven is Commonwealth editorial practice.

It gets complicated, however. Even in places where style five above is the rule, long closed-class words (eg ‘between’) sometimes taking an initial cap. The *New York Times* used a ‘five with occasional long closed-class exceptions’ style for many years, for example.

And there are numerous UK publishers using style five (especially with the ‘long closed-class words are a further exception’ variation) and numerous US publishers using style seven.

Also, scientific publishers, regardless of where they are, tend to stick with style seven (sentence case).

ALL CAPS is generally a sign of very good or very poor typesetting and design, mostly the latter. It takes a real eye for type and presentation to make ALL CAPS titles work. More important, from our perspective, it takes typefaces we don’t use. All this is equally true for all lowercase titles.

Initial Caps For Everything (two above) is mostly a sign of typesetter uncertainty. The person setting the type doesn’t know styles three, four, five or six even exist but does know that Titles Are Somehow Different To Standard Text When It Comes To Capitals. Consequently, and by way of obviating the problem, they stick Initial Caps on everything.

The *New York Times* variant on style five noted above — initial caps for everything, except non-initial closed class words, unless the non-initial closed-class word is particularly long — is popular, albeit accidentally so. Most people using it are actually using a naive version of it: initial caps for everything except short words, unless the short words are nouns or names or the like.

Given the complexity even the simplest of these rules introduce, the argument for sentence case is compelling. It reduces the editorial workload and doesn’t materially effect the look of the published material.

The half-decent justification for anything other than sentence case is that titles are not contrasted clearly from body copy unless set otherwise. A better solution to that problem is to re-set the titles, not introduce complicated house rules that people will invariably forget. Titles in Red Hat books *are* set in clear and contrasting style, so we don’t have that half-decent justification for using other than standard sentence case.



*‘closed class’ word types don’t get new members all that often. For example, prepositions, postpositions, determiners, conjunctions, & pronouns. Nouns and verbs, by contrast, are open class words, taking on new members all the bloody time.
Comment 4 David O'Brien 2009-06-17 00:55:07 EDT
My question is why are we identifying Preface and Revision History? If we're going to introduce a new style for our books, look long and hard at the effect it's going to have, how much time and effort will be required, and for what gain, and discuss it with a number of people who are going to be involved.
Comment 5 Murray McAllister 2009-07-15 23:40:25 EDT
0) Identified because I used sentence case for a whole book and Preface and Revision History did not.

1) The effect is every book will have the same heading style and be consistent.

2) No time and effort required since even people like myself can remember sentence case rules.

3) For gain see 1).
Comment 6 David O'Brien 2009-07-16 00:17:42 EDT
(In reply to comment #5)
> 0) Identified because I used sentence case for a whole book and Preface and
> Revision History did not.

This would indicate that the balance of the book was at odds with our standing styles, given that the Preface (in particular) includes sections based on templates that use initial caps.

> 
> 1) The effect is every book will have the same heading style and be consistent.

You can achieve this effect by adhering to existing styles.

> 
> 2) No time and effort required since even people like myself can remember
> sentence case rules.

The time and effort is required in determining and implementing a new style and then ensuring that *it*, rather than a previous style, is adhered to.

> 
> 3) For gain see 1).  

It's true that our styles are not consistently applied across all books. That doesn't mean we need to change. It's also true that there are many styles used throughout the world. Again, doesn't mean we need to change. Review, sure. If we identify problems, if there is general agreement, and the benefit is obvious and outweighs the cost then sure, let's investigate a style change. There are far too many other aspects of our documentation that need attention besides how we present our headings.
Comment 7 Jeff Fearn 2009-07-16 20:24:25 EDT
Check this out: http://search.cpan.org/~dconway/Text-Autoformat-1.666.0/lib/Text/Autoformat.pm#Case_transformations

Maybe we could automate styling the title of the output based on a parameter ... maybe.

e.g:

Param: title_format
Values: NULL, upper, lower, sentence, title, highlight
Default: NULL

Where NULL is "don't be playing with my stylez fool"

This way we could set defaults or overrides in the Brands as required, and we wouldn't have to manually go and change 250 books :D

Big question is if this works for translations, and if so, which languages do or don't require it.

Cheers, Jeff.
Comment 8 Murray McAllister 2009-07-16 20:41:05 EDT
re comment #7 the use of values provides gateway to multiple different heading styles.
Comment 10 Jeff Fearn 2009-10-01 20:36:22 EDT
There is no consensus on what to use, so we will stick with what we have.