"image" directive: added checks for valid values of "align" option, depending on context. "figure" directive: added specialized "align" option and attribute on "figure" element. Added HTML support for ``align`` attribute on ``figure`` elements. Updated docs & tests.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3231 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

9 files changed, 65 insertions, 3 deletions

diff --git a/HISTORY.txt b/HISTORY.txt
index 412539776..95af46972 100644
--- a/HISTORY.txt
+++ b/HISTORY.txt
@@ -84,6 +84,9 @@ Changes Since 0.3.7
   - Allowed whitespace (stripped) in "image" & "figure" directive URLs.
   - Added support for the ``file_insertion_enabled`` setting in the
     "figure" directive (disables "figwidth" option).
+  - "image" directive: added checks for valid values of "align" option,
+    depending on context.  "figure" directive: added specialized
+    "align" option and attribute on "figure" element.
 
 * docutils/parsers/rst/directives/misc.py:
 
@@ -131,6 +134,7 @@ Changes Since 0.3.7
   - Added the ``field_name_limit`` & ``option_limit`` settings &
     support.
   - Added support for table stub columns.
+  - Added support for ``align`` attribute on ``figure`` elements.
 
 * docutils/writers/latex2e.py:
 
@@ -147,6 +151,7 @@ Changes Since 0.3.7
   - Added ``stub`` attribute to ``colspec`` element via the
     ``tbl.colspec.att`` parameter entity.
   - Allowed topic elements within sidebars
+  - Added ``align`` attribute to ``figure`` element.
 
 
 Release 0.3.7 (2004-12-24)
diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index 357703f04..f3a7d37ca 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -97,6 +97,12 @@ resolve to either an internal or external reference.
 <!ENTITY % fixedspace.att
   " xml:space (default | preserve) #FIXED 'preserve' ">
 
+<!ENTITY % align-h.att
+  " align     (left | center | right) #IMPLIED ">
+
+<!ENTITY % align-hv.att
+  " align     (top | middle | bottom | left | center | right) #IMPLIED ">
+
 
 <!-- Element OR-Lists
 ============================================================= -->
@@ -465,12 +471,14 @@ or " ") or the text between option arguments (typically either "," or
 <!ELEMENT figure (image, ((caption, legend?) | legend)) >
 <!ATTLIST figure
     %basic.atts;
+    %align-h.att;
     width     %number;  #IMPLIED>
 
 <!-- Also an inline element. -->
 <!ELEMENT image EMPTY>
 <!ATTLIST image
     %basic.atts;
+    %align-hv.att;
     uri       CDATA     #REQUIRED
     alt       CDATA     #IMPLIED
     height    %number;  #IMPLIED
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 737cbe97a..f888ef556 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -309,6 +309,11 @@ options are recognized:
     Set a "class" attribute value on the figure element.  See the
     class_ directive below.
 
+``align`` : "left", "center", or "right"
+    The horizontal alignment of the figure, allowing the image to
+    float and have the text flow around it.  The specific behavior
+    depends upon the browser or rendering software used.
+
 .. [#PIL] `Python Imaging Library`_.
 
 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
diff --git a/docutils/parsers/rst/directives/images.py b/docutils/parsers/rst/directives/images.py
index d4cd20a7f..7efb2588d 100644
--- a/docutils/parsers/rst/directives/images.py
+++ b/docutils/parsers/rst/directives/images.py
@@ -22,13 +22,33 @@ try:
 except ImportError:
     Image = None
 
-align_values = ('top', 'middle', 'bottom', 'left', 'center', 'right')
+align_h_values = ('left', 'center', 'right')
+align_v_values = ('top', 'middle', 'bottom')
+align_values = align_v_values + align_h_values
 
 def align(argument):
     return directives.choice(argument, align_values)
 
 def image(name, arguments, options, content, lineno,
           content_offset, block_text, state, state_machine):
+    if options.has_key('align'):
+        # check for align_v values only
+        if isinstance(state, states.SubstitutionDef):
+            if options['align'] not in align_v_values:
+                error = state_machine.reporter.error(
+                    'Error in "%s" directive: "%s" is not a valid value for '
+                    'the "align" option within a substitution definition.  '
+                    'Valid values for "align" are: "%s".'
+                    % (name, options['align'], '", "'.join(align_v_values)),
+                    nodes.literal_block(block_text, block_text), line=lineno)
+                return [error]
+        elif options['align'] not in align_h_values:
+            error = state_machine.reporter.error(
+                'Error in "%s" directive: "%s" is not a valid value for '
+                'the "align" option.  Valid values for "align" are: "%s".'
+                % (name, options['align'], '", "'.join(align_h_values)),
+                nodes.literal_block(block_text, block_text), line=lineno)
+            return [error]
     messages = []
     reference = directives.uri(arguments[0])
     options['uri'] = reference
@@ -63,12 +83,17 @@ image.options = {'alt': directives.unchanged,
                  'target': directives.unchanged_required,
                  'class': directives.class_option}
 
+def figure_align(argument):
+    return directives.choice(argument, align_h_values)
+
 def figure(name, arguments, options, content, lineno,
            content_offset, block_text, state, state_machine):
     figwidth = options.setdefault('figwidth')
     figclasses = options.setdefault('figclass')
+    align = options.setdefault('align')
     del options['figwidth']
     del options['figclass']
+    del options['align']
     (image_node,) = image(name, arguments, options, content, lineno,
                          content_offset, block_text, state, state_machine)
     if isinstance(image_node, nodes.system_message):
@@ -88,6 +113,8 @@ def figure(name, arguments, options, content, lineno,
         figure_node['width'] = figwidth
     if figclasses:
         figure_node['classes'] += figclasses
+    if align:
+        figure_node['align'] = align
     if content:
         node = nodes.Element()          # anonymous container for parsing
         state.nested_parse(content, content_offset, node)
@@ -116,4 +143,5 @@ figure.arguments = (1, 0, 1)
 figure.options = {'figwidth': figwidth_value,
                   'figclass': directives.class_option}
 figure.options.update(image.options)
+figure.options['align'] = figure_align
 figure.content = 1
diff --git a/docutils/writers/html4css1.py b/docutils/writers/html4css1.py
index 3e465d3d3..cdc8bf583 100644
--- a/docutils/writers/html4css1.py
+++ b/docutils/writers/html4css1.py
@@ -715,6 +715,8 @@ class HTMLTranslator(nodes.NodeVisitor):
         atts = {'class': 'figure'}
         if node.get('width'):
             atts['style'] = 'width: %spx' % node['width']
+        if node.get('align'):
+            atts['align'] = node['align']
         self.body.append(self.starttag(node, 'div', **atts))
 
     def depart_figure(self, node):
diff --git a/test/functional/expected/standalone_rst_html4css1.html b/test/functional/expected/standalone_rst_html4css1.html
index 66879b19f..8ea472629 100644
--- a/test/functional/expected/standalone_rst_html4css1.html
+++ b/test/functional/expected/standalone_rst_html4css1.html
@@ -546,7 +546,7 @@ document (a document-wide <a class="reference" href="#table-of-contents">table o
 <p>An image directive (also clickable -- a hyperlink reference):</p>
 <div class="image class1 class2 image-reference"><a class="reference" href="#directives"><img alt="../../../docs/user/rst/images/title.png" class="class1 class2" src="../../../docs/user/rst/images/title.png" /></a></div>
 <p>A figure directive:</p>
-<div class="figclass1 figclass2 figure">
+<div align="left" class="figclass1 figclass2 figure">
 <div class="image class1 class2"><img alt="reStructuredText, the markup syntax" class="class1 class2" src="../../../docs/user/rst/images/title.png" /></div>
 <p class="caption">A figure is an image with a caption and/or a legend:</p>
 <div class="legend">
diff --git a/test/functional/expected/standalone_rst_pseudoxml.txt b/test/functional/expected/standalone_rst_pseudoxml.txt
index b4d510854..6fd48b818 100644
--- a/test/functional/expected/standalone_rst_pseudoxml.txt
+++ b/test/functional/expected/standalone_rst_pseudoxml.txt
@@ -1121,7 +1121,7 @@
                     <image classes="class1 class2" uri="../../../docs/user/rst/images/title.png">
                 <paragraph>
                     A figure directive:
-                <figure classes="figclass1 figclass2">
+                <figure align="left" classes="figclass1 figclass2">
                     <image alt="reStructuredText, the markup syntax" classes="class1 class2" uri="../../../docs/user/rst/images/title.png">
                     <caption>
                         A figure is an image with a caption and/or a legend:
diff --git a/test/functional/input/data/standard.txt b/test/functional/input/data/standard.txt
index 092a0ae44..507838b88 100644
--- a/test/functional/input/data/standard.txt
+++ b/test/functional/input/data/standard.txt
@@ -429,6 +429,7 @@ A figure directive:
    :figclass: figclass1 figclass2
    :class: class1 class2
    :alt: reStructuredText, the markup syntax
+   :align: left
 
    A figure is an image with a caption and/or a legend:
 
diff --git a/test/test_parsers/test_rst/test_directives/test_figures.py b/test/test_parsers/test_rst/test_directives/test_figures.py
index 821841e07..38c6e821f 100755
--- a/test/test_parsers/test_rst/test_directives/test_figures.py
+++ b/test/test_parsers/test_rst/test_directives/test_figures.py
@@ -106,6 +106,19 @@ totest['figures'] = [
             A picture with image options on individual lines, and this caption.
 """],
 ["""\
+.. figure:: picture.png
+   :align: center
+
+   A figure with explicit alignment.
+""",
+"""\
+<document source="test data">
+    <figure align="center">
+        <image uri="picture.png">
+        <caption>
+            A figure with explicit alignment.
+"""],
+["""\
 This figure lacks a caption. It may still have a
 "Figure 1."-style caption appended in the output.