docs: add user documentation for latent styles

Steve Canny · Steve Canny · commit 3b3713c1a89b · 2015-02-08T00:01:46.000-08:00
diff --git a/docs/conf.py b/docs/conf.py
@@ -109,6 +109,8 @@
 
 .. |int| replace:: :class:`.int`
 
+.. |_LatentStyle| replace:: :class:`._LatentStyle`
+
 .. |LatentStyles| replace:: :class:`.LatentStyles`
 
 .. |Length| replace:: :class:`.Length`
diff --git a/docs/user/styles-understanding.rst b/docs/user/styles-understanding.rst
@@ -132,6 +132,23 @@ 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.
 
 
+.. _builtin_styles:
+
+Built-in styles
+---------------
+
+Word comes with almost 300 so-called *built-in* styles like `Normal`,
+`Heading 1`, and `List Bullet`. Style definitions are stored in the
+`styles.xml` part of a .docx package, but built-in style definitions are
+stored in the Word application itself and are not written to `styles.xml`
+until they are actually used. This is a sensible strategy because they take
+up considerable room and would be largely redundant and useless overhead in
+every .docx file otherwise.
+
+The fact that built-in styles are not written to the .docx package until used
+gives rise to the need for *latent style* definitions, explained below.
+
+
 .. _style_behavior:
 
 Style Behavior
@@ -160,6 +177,27 @@ will not appear in any list or the style gallery and cannot be applied to
 content.
 
 
+.. _latent_styles:
+
+Latent styles
+-------------
+
+The need to specify the UI behavior of built-in styles not defined in
+`styles.xml` gives rise to the need for *latent style* definitions. A latent
+style definition is basically a stub style definition that has at most the
+five behavior attributes in addition to the style name. Additional space is
+saved by defining defaults for each of the behavior attributes, so only those
+that differ from the default need be defined and styles that match all
+defaults need no latent style definition.
+
+Latent style definitions are specified using the `w:latentStyles` and
+`w:lsdException` elements appearing in `styles.xml`.
+
+A latent style definition is only required for a built-in style because only
+a built-in style can appear in the UI without a style definition in
+`styles.xml`.
+
+
 Style inheritance
 -----------------
 
diff --git a/docs/user/styles-using.rst b/docs/user/styles-using.rst
@@ -236,11 +236,11 @@ font and its paragraph indentation.
 
 There are five behavioral properties of a style:
 
-* :attr:`~.Style.hidden`
-* :attr:`~.Style.unhide_when_used`
-* :attr:`~.Style.priority`
-* :attr:`~.Style.quick_style`
-* :attr:`~.Style.locked`
+* :attr:`~.BaseStyle.hidden`
+* :attr:`~.BaseStyle.unhide_when_used`
+* :attr:`~.BaseStyle.priority`
+* :attr:`~.BaseStyle.quick_style`
+* :attr:`~.BaseStyle.locked`
 
 See the :ref:`style_behavior` section in :ref:`understanding_styles` for
 a description of how these behavioral properties interact to determine when
@@ -279,6 +279,74 @@ but allow it to remain in the recommended list::
 Working with Latent Styles
 --------------------------
 
-... describe latent styles in Understanding page ...
+See the :ref:`builtin_styles` and :ref:`latent_styles` sections in
+:ref:`understanding_styles` for a description of how latent styles define the
+behavioral properties of built-in styles that are not yet defined in the
+`styles.xml` part of a .docx file.
 
-Let's illustrate these behaviors with a few examples.
+Access the latent styles in a document
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The latent styles in a document are accessed from the styles object::
+
+    >>> document = Document()
+    >>> latent_styles = document.styles.latent_styles
+
+A |LatentStyles| object supports :meth:`len`, iteration, and dictionary-style
+access by style name::
+
+    >>> len(latent_styles)
+    161
+
+    >>> latent_style_names = [ls.name for ls in latent_styles]
+    >>> latent_style_names
+    ['Normal', 'Heading 1', 'Heading 2', ... 'TOC Heading']
+
+    >>> latent_quote = latent_styles['Quote']
+    >>> latent_quote
+    <docx.styles.latent.LatentStyle object at 0x10a7c4f50>
+    >>> latent_quote.priority
+    29
+
+Change latent style defaults
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The |LatentStyles| object also provides access to the default behavioral
+properties for built-in styles in the current document. These defaults
+provide the value for any undefined attributes of the |_LatentStyle|
+definitions and to all behavioral properties of built-in styles having no
+explicit latent style definition. See the API documentation for the
+|LatentStyles| object for the complete set of available properties::
+
+    >>> latent_styles.default_to_locked
+    False
+    >>> latent_styles.default_to_locked = True
+    >>> latent_styles.default_to_locked
+    True
+
+Add a latent style definition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A new latent style can be added using the
+:meth:`~.LatentStyles.add_latent_style` method on |LatentStyles|. This code
+adds a new latent style for the builtin style 'List Bullet', setting it to
+appear in the style gallery::
+
+    >>> latent_style = latent_styles['List Bullet']
+    KeyError: no latent style with name 'List Bullet'
+    >>> latent_style = latent_styles.add_latent_style('List Bullet')
+    >>> latent_style.hidden = False
+    >>> latent_style.priority = 2
+    >>> latent_style.quick_style = True
+
+Delete a latent style definition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A latent style definition can be deleted by calling its
+:meth:`~.LatentStyle.delete` method::
+
+    >>> latent_styles['Light Grid']
+    <docx.styles.latent.LatentStyle object at 0x10a7c4f50>
+    >>> latent_styles['Light Grid'].delete()
+    >>> latent_styles['Light Grid']
+    KeyError: no latent style with name 'Light Grid'
