[gnome-devel-docs] refine guidelines on capitalization and ellipses, and link appropriately

[Allan Day <allanday src gnome org>]

commit 1e95f58e4f1a24f9fc49c044381c1f81837e0613
Author: Allan Day <allanpday gmail com>
Date:   Thu Sep 4 13:09:48 2014 +0100

    refine guidelines on capitalization and ellipses, and link appropriately

 hig/C/buttons.page       |    9 ++++++---
 hig/C/menus.page         |    1 +
 hig/C/writing-style.page |   30 ++++++++++++++++--------------
 3 files changed, 23 insertions(+), 17 deletions(-)
---
diff --git a/hig/C/buttons.page b/hig/C/buttons.page
index 3c2bd5c..d849344 100644
--- a/hig/C/buttons.page
+++ b/hig/C/buttons.page
@@ -46,9 +46,12 @@
 <section id="text-buttons">
 <title>Text buttons</title>
 
-<p>Label all buttons with imperative verbs, using <link xref="writing-style#capitalization">header 
capitalization</link>. For example, <gui>Save</gui>, <gui>Sort</gui> or <gui>Update Now</gui>. Provide an 
access key in the label that allows the user to directly activate the button from the keyboard.</p>
-
-<p>Use an ellipsis (…) at the end of the label if the action requires further input from the user before it 
can be carried out. For example, <gui>Save As…</gui> or <gui>Find…</gui>. Do not add an ellipsis to commands 
like <gui>Properties</gui> or <gui>Preferences</gui>, as these open windows that do not require further 
input.</p>
+<list>
+<item><p>Label all buttons with imperative verbs, using <link xref="writing-style#capitalization">header 
capitalization</link>. For example, <gui>Save</gui>, <gui>Sort</gui> or <gui>Update Now</gui>.</p></item>
+<item><p>Use <link xref="writing-style#ellipses">ellipses</link> when a button requires further input from 
the user to complete an action.</p></item>
+<item><p>Provide an <link xref="keyboard-input#access-keys">access key</link> in the label that allows the 
user to directly activate the button from the keyboard.</p></item>
+<item><p>Keep labels short, so they don't cause a button to use too much space. It is also important to 
consider how labels will change length when localized.</p></item>
+</list>
 
 </section>
 
diff --git a/hig/C/menus.page b/hig/C/menus.page
index 4e94943..cbba78d 100644
--- a/hig/C/menus.page
+++ b/hig/C/menus.page
@@ -58,6 +58,7 @@
 <list>
 <item><p>Provide an <link xref="keyboard-input#access-keys">access key</link> for every menu item. You may 
use the same access key on different menus in your application, but avoid duplicating access keys on the same 
menu. Note that unlike other controls, once a menu is displayed, its access keys may be used by just typing 
the letter; it is not necessary to press the Alt key at the same time.</p></item>
 <item><p>Label menu items with verbs for commands and adjectives for settings, using <link 
xref="writing-style#capitalization">header capitalization</link>.</p></item>
+<item><p>Use <link xref="writing-style#ellipses">ellipses</link> when a menu item requires further input 
from the user to complete an action.</p></item>
 <item><p>Two linked actions can be combined into a single menu item, by changing the label when the item is 
selected. For example, a <gui>Play</gui> item may change to <gui>Pause</gui>. However, only use this type of 
item when actions are logical opposites which are obvious to users. Likewise, do not use this technique for 
settings - use check boxes or radio buttons instead.</p></item>
 </list>
 
diff --git a/hig/C/writing-style.page b/hig/C/writing-style.page
index c23d617..6f4c6a2 100644
--- a/hig/C/writing-style.page
+++ b/hig/C/writing-style.page
@@ -47,33 +47,35 @@
 
 <p>Two styles of capitalization are used in GNOME user interfaces: header capitalization and sentence 
capitalization.</p>
 
-<section id="header-capitalization">
-<title>Header Capitalization</title>
-
-<p>Capitalize all words in the element, with the following exceptions:</p>
+<p>Header capitalization should be used for any headings, including header bar headings and page, tab and 
menu titles. It should also be used for short control labels that do not normally form proper sentences, such 
as button and switch labels and menu items.</p>
 
-<list>
-<item><p>Articles: a, an, the.</p></item>
-<item><p>Conjunctions of three or fewer letters. For example: and, but, for, not, so, yet.</p></item>
-<item><p>Prepositions of three or fewer letters. For example: at, for, by, in, to.</p></item>
-</list>
+<p>Sentence capitalization should be used for labels which form sentences or which run on to other text, 
including labels for check boxes, radio buttons, sliders, text entry boxes, field labels and combobox labels. 
Sentence capitalization should be used for explanatory or body text, such as that which is found in dialogs 
or notifications.</p>
 
-<p>(Verbs with three or fewer letters should be capitalized: Be, Are, Is, Put, See, Add.)</p>
+<section id="header-capitalization">
+<title>Header Capitalization</title>
 
-<p>For example: “Create a Document”, “Find and Replace”.</p>
+<p>Capitalize all words, except those with three or fewer letters. However, verbs of any length should be 
capitilized (such as “Be”, “Are”, “Is”, “See”, “Add”, and so on).</p>
 
-<p>Header capitalization should be used for any headings, including header bar headings and page, tab and 
menu titles. It should also be used for short control labels that do not normally form proper sentences, such 
as button and switch labels and menu items.</p>
+<p>For example: “Create a Document”, “Find and Replace”, “Document Cannot Be Found”.</p>
 
 </section>
 
 <section id="sentence-capitalisation">
 <title>Sentence Capitalization</title>
 
-<p>Capitalize the first letter of the first word and any other words normally capitalized in sentences, such 
as application names.</p>
+<p>Capitalize the first letter of the first word and any other words normally capitalized in sentences, such 
as proper nouns.</p>
 
-<p>Sentence capitalization should be used for labels which form sentences or which run on to other text, 
including labels for check boxes, radio buttons, sliders, text entry boxes, field labels and combobox labels. 
Sentence capitalization should be used for explanatory or body text, such as that which is found in dialogs 
or notifications.</p>
+<p>For example: “The document cannot be found in this location.” “Finding results for London.”</p>
 
 </section>
+</section>
+
+<section id="ellipses">
+<title>Ellipses (…)</title>
+
+<p>Use an ellipsis (…) at the end of a label if the action requires further input from the user before it 
can be carried out. For example, <gui>Save As…</gui>, <gui>Find…</gui> or <gui>Rename…</gui>.</p>
+
+<p>Do not add an ellipsis to commands like <gui>Properties</gui> or <gui>Preferences</gui>. While these 
commands open windows that can incorporate further functionality, the label does not specify a particular 
action, and therefore does not need to communicate that further input is required.</p>
 
 </section>