Index: Doc/documenting/style.rst
===================================================================
--- Doc/documenting/style.rst	(revision 86409)
+++ Doc/documenting/style.rst	(working copy)
@@ -1,15 +1,19 @@
 .. highlightlang:: rest
 
-Style Guide
+Style guide
 ===========
 
 The Python documentation should follow the `Apple Publications Style Guide`_
 wherever possible. This particular style guide was selected mostly because it
 seems reasonable and is easy to get online.
 
-Topics which are not covered in Apple's style guide will be discussed in
-this document.
+Topics which are either not covered in Apple's style guide or treated
+differently in Python documentation will be discussed in this
+document.
 
+Use of white space
+------------------
+
 All reST files use an indentation of 3 spaces.  The maximum line length is 80
 characters for normal text, but tables, deeply indented code samples and long
 links may extend beyond that.
@@ -21,6 +25,9 @@
 ignores the second space, it is customarily put in by some users, for example
 to aid Emacs' auto-fill mode.
 
+Footnotes
+---------
+
 Footnotes are generally discouraged, though they may be used when they are the
 best way to present specific information. When a footnote reference is added at
 the end of the sentence, it should follow the sentence-ending punctuation. The
@@ -34,6 +41,18 @@
 
 Footnotes may appear in the middle of sentences where appropriate.
 
+Capitalization
+--------------
+
+Apple style guide recommends the use of title case in section titles.
+However, rules for which words should be capitalized in title case
+vary greaty between publications.  In Python documentation use of
+sentence case in section titles is preferable, but consistency within
+a file is more important than following this rule.  If you add a
+section to the file where most sections are in title case you can
+either convert all titles to sentence case or use the dominant style
+in the new section title.
+
 Many special names are used in the Python documentation, including the names of
 operating systems, programming languages, standards bodies, and the like. Most
 of these entities are not assigned any special markup, but the preferred