docs: document Style behavior properties

Steve Canny · Steve Canny · commit 4ef1c51be15f · 2015-02-08T00:01:45.000-08:00
diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst
@@ -310,7 +310,7 @@ including its typeface, size, color, bold, italic, etc.
 
 Like paragraph styles, a character style must already be defined in the
 document you open with the ``Document()`` call (*see*
-:ref:`understandingstyles`).
+:ref:`understanding_styles`).
 
 A character style can be specified when adding a new run::
 
diff --git a/docs/user/styles-understanding.rst b/docs/user/styles-understanding.rst
@@ -1,4 +1,4 @@
-.. _understandingstyles:
+.. _understanding_styles:
 
 Understanding Styles
 ====================
@@ -132,6 +132,34 @@ the style id unless they are confident with the internals involved.
 A style's :attr:`type` is set at creation time and cannot be changed.
 
 
+.. _style_behavior:
+
+Style Behavior
+--------------
+
+In addition to collecting a set of formatting properties, a style has five
+properties that specify its *behavior*. This behavior is relatively simple,
+basically amounting to when and where the style appears in the Word or
+LibreOffice UI.
+
+The key notion to understanding style behavior is the recommended list. In
+the style pane in Word, the user can select which list of styles they want to
+see. One of these is named *Recommended* and is known as the *recommended
+list*. All five behavior properties affect some aspect of the style’s
+appearance in this list and in the style gallery.
+
+In brief, a style appears in the recommended list if its :attr:`hidden`
+property is |False| (the default). If a style is not hidden and its
+:attr:`quick_style` property is |True|, it also appears in the style gallery.
+If a hidden style's :attr:`unhide_when_used` property is |True|, its hidden
+property is set |False| the first time it is used. Styles in the style lists
+and style gallery are sorted in :attr:`priority` order, then alphabetically
+for styles of the same priority. If a style's :attr:`locked` property is
+|True| and formatting restrictions are turned on for the document, the style
+will not appear in any list or the style gallery and cannot be applied to
+content.
+
+
 Style inheritance
 -----------------
 
diff --git a/docs/user/styles-using.rst b/docs/user/styles-using.rst
@@ -3,7 +3,7 @@ Working with Styles
 ===================
 
 This page uses concepts developed in the prior page without introduction. If
-a term is unfamiliar, consult the prior page :ref:`understandingstyles` for
+a term is unfamiliar, consult the prior page :ref:`understanding_styles` for
 a definition.
 
 
@@ -242,19 +242,38 @@ There are five behavioral properties of a style:
 * :attr:`~.Style.quick_style`
 * :attr:`~.Style.locked`
 
-The key notion to understanding the behavioral properties is the *recommended
-list*. In the style pane in Word, the user can select which list of styles
-they want to see. One of those is named *Recommended*. All five behavior
-properties affect some aspect of the style's appearance in this list and in
-the style gallery.
-
-In brief, a style appears in the recommended list if its `hidden` property is
-|False|. If a style is not hidden and its `quick_style` property is |True|,
-it also appears in the style gallery. The style's `priority` value (|int|)
-determines its position in the sequence of styles. If a styles's `locked`
-property is |True| and formatting restrictions are turned on for the
-document, the style will not appear in any list or the style gallery and
-cannot be applied to content.
+See the :ref:`style_behavior` section in :ref:`understanding_styles` for
+a description of how these behavioral properties interact to determine when
+and where a style appears in the Word UI.
+
+The :attr:`priority` property takes an integer value. The other four style
+behavior properties are *tri-state*, meaning they can take the value |True|
+(on), |False| (off), or |None| (inherit).
+
+Display a style in the style gallery
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code will cause the 'Body Text' paragraph style to appear first
+in the style gallery::
+
+    >>> from docx import Document
+    >>> document = Document()
+    >>> style = document.styles['Body Text']
+
+    >>> style.hidden = False
+    >>> style.quick_style = True
+    >>> style.priorty = 1
+
+Remove a style from the style gallery
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This code will remove the 'Normal' paragraph style from the style gallery,
+but allow it to remain in the recommended list::
+
+    >>> style = document.styles['Normal']
+
+    >>> style.hidden = False
+    >>> style.quick_style = False
 
 
 Working with Latent Styles
