added support for units in image widths and heights;

I called a number combined with a unit (e.g. 5em) a "measure"; I am not entirely
sure if that's the right term, though

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

12 files changed, 203 insertions, 7 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index b8c01db2a..5cb822a0f 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -36,10 +36,18 @@ Changes Since 0.3.9
   - Added the "default-role" and "title" directives.
   - Added standard data file syntax to the "include" directive.
 
+* docutils/parsers/rst/directives/images.py:
+
+  - Added support for image width and height units.
+
 * docutils/parsers/rst/include/: Directory added to project; contains
   standard data files for the "include" directive.  Initial contents:
   character entity substitution definition sets.
 
+* docutils/writers/html4css1.py:
+
+  - Added support for image width and height units.
+
 * docs/user/links.txt: Added to project; link list.
 
 * docs/ref/rst/substitutions.txt: "reStructuredText Standard
diff --git a/docutils/docs/ref/docutils.dtd b/docutils/docs/ref/docutils.dtd
index f3a7d37ca..fd47b6c91 100644
--- a/docutils/docs/ref/docutils.dtd
+++ b/docutils/docs/ref/docutils.dtd
@@ -39,6 +39,9 @@ by wrapper DTDs.
 <!-- Emphasize that the attribute value must be a number. -->
 <!ENTITY % number  "NMTOKEN">
 
+<!-- A number which may be immediately followed by a unit. -->
+<!ENTITY % measure "NMTOKEN">
+
 <!ENTITY % additional.basic.atts "">
 <!--
 Attributes shared by all elements in this DTD:
@@ -481,8 +484,8 @@ or " ") or the text between option arguments (typically either "," or
     %align-hv.att;
     uri       CDATA     #REQUIRED
     alt       CDATA     #IMPLIED
-    height    %number;  #IMPLIED
-    width     %number;  #IMPLIED
+    height    %measure; #IMPLIED
+    width     %measure; #IMPLIED
     scale     %number;  #IMPLIED>
 
 <!ELEMENT caption %text.model;>
diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt
index cf5c20361..2235c428f 100644
--- a/docutils/docs/ref/rst/directives.txt
+++ b/docutils/docs/ref/rst/directives.txt
@@ -202,11 +202,19 @@ The following options are recognized:
     specified, they are combined.  For example, a height of 200 and a
     scale of 50 is equivalent to a height of 100 with no scale.
 
+    It is also possible to specify a `length value`_.
+
 ``width`` : integer
     The width of the image in pixels, used to reserve space or scale
     the image horizontally.  As with "height" above, when the "scale"
     option is also specified, they are combined.
 
+    It is also possible to specify a length_ or `percentage value`_.
+
+    .. _length:
+    .. _length value: restructuredtext.html#length-units
+    .. _percentage value: restructuredtext.html#percentage-units
+
 ``scale`` : integer
     The uniform scaling factor of the image, a percentage (but no "%"
     symbol is required or allowed).  "100" means full-size, and is
diff --git a/docutils/docs/ref/rst/restructuredtext.txt b/docutils/docs/ref/rst/restructuredtext.txt
index 6d21934b4..0823cc8eb 100644
--- a/docutils/docs/ref/rst/restructuredtext.txt
+++ b/docutils/docs/ref/rst/restructuredtext.txt
@@ -2781,6 +2781,46 @@ characters (see `Escaping Mechanism`_ above).
    RFC2396_ and RFC2732_.
 
 
+Units
+=====
+
+All measures consist of a positive floating point number in standard
+(non-scientific) notation and a unit, possibly separated by one or
+more spaces.
+
+Units are only supported where explicitly mentioned in the reference
+manuals.
+
+
+Length Units
+------------
+
+The following length units are supported by the reStructuredText
+parser:
+
+* em (ems, the height of the element's font)
+* ex (x-height, the height of the letter "x")
+* px (pixels, relative to the canvas resolution)
+* in (inches; 1in=2.54cm)
+* cm (centimeters; 1cm=10mm)
+* mm (millimeters)
+* pt (points; 1pt=1/72in)
+* pc (picas; 1pc=12pt)
+
+(List and explanations taken from
+http://www.htmlhelp.com/reference/css/units.html#length.)
+
+The following are all valid length values: "1.5em", "20 mm", ".5in".
+
+
+Percentage Units
+----------------
+
+Percentage values have a percent sign ("%") as unit.  Percentage
+values are relative to other values, depending on the context in which
+they occur.
+
+
 ----------------
  Error Handling
 ----------------
diff --git a/docutils/docutils/parsers/rst/directives/__init__.py b/docutils/docutils/parsers/rst/directives/__init__.py
index d78a3b9c1..dadd08e65 100644
--- a/docutils/docutils/parsers/rst/directives/__init__.py
+++ b/docutils/docutils/parsers/rst/directives/__init__.py
@@ -286,6 +286,32 @@ def nonnegative_int(argument):
         raise ValueError('negative value; must be positive or zero')
     return value
 
+length_units = ['em', 'ex', 'px', 'in', 'cm', 'mm', 'pt', 'pc']
+
+def get_measure(argument, units):
+    """
+    Check for a positive argument of one of the units and return a
+    normalized string of the form "<value><unit>" (without space in
+    between).
+    
+    To be called from directive option conversion functions.
+    """
+    match = re.match(r'^([0-9.]+) *(%s)$' % '|'.join(units), argument)
+    try:
+        assert match is not None
+        float(match.group(1))
+    except (AssertionError, ValueError):
+        raise ValueError(
+            'not a positive measure of one of the following units:\n%s'
+            % ' '.join(['"%s"' % i for i in units]))
+    return match.group(1) + match.group(2)
+
+def length_or_unitless(argument):
+    return get_measure(argument, length_units + [''])
+
+def length_or_percentage_or_unitless(argument):
+    return get_measure(argument, length_units + ['%', ''])
+
 def class_option(argument):
     """
     Convert the argument into a list of ID-compatible strings and return it.
diff --git a/docutils/docutils/parsers/rst/directives/images.py b/docutils/docutils/parsers/rst/directives/images.py
index 670f969a0..ef77c2bef 100644
--- a/docutils/docutils/parsers/rst/directives/images.py
+++ b/docutils/docutils/parsers/rst/directives/images.py
@@ -76,8 +76,8 @@ def image(name, arguments, options, content, lineno,
 
 image.arguments = (1, 0, 1)
 image.options = {'alt': directives.unchanged,
-                 'height': directives.nonnegative_int,
-                 'width': directives.nonnegative_int,
+                 'height': directives.length_or_unitless,
+                 'width': directives.length_or_percentage_or_unitless,
                  'scale': directives.nonnegative_int,
                  'align': align,
                  'target': directives.unchanged_required,
diff --git a/docutils/docutils/writers/html4css1.py b/docutils/docutils/writers/html4css1.py
index e2f36721f..1dae18b5c 100644
--- a/docutils/docutils/writers/html4css1.py
+++ b/docutils/docutils/writers/html4css1.py
@@ -890,6 +890,16 @@ class HTMLTranslator(nodes.NodeVisitor):
             if atts.has_key('height'):
                 atts['height'] = int(round(node['height']
                                            * (float(node['scale']) / 100)))
+        style = []
+        for att_name in 'width', 'height':
+            if atts.has_key(att_name):
+                if re.match(r'^[0-9.]+$', atts[att_name]):
+                    # Interpret unitless values as pixels.
+                    atts[att_name] += 'px'
+                style.append('%s: %s;' % (att_name, atts[att_name]))
+                del atts[att_name]
+        if style:
+            atts['style'] = ' '.join(style)
         atts['alt'] = node.get('alt', atts['src'])
         if node.has_key('align'):
             atts['align'] = self.attval(node['align'])
diff --git a/docutils/test/functional/expected/standalone_rst_html4css1.html b/docutils/test/functional/expected/standalone_rst_html4css1.html
index ba5d7784d..e624dacb0 100644
--- a/docutils/test/functional/expected/standalone_rst_html4css1.html
+++ b/docutils/test/functional/expected/standalone_rst_html4css1.html
@@ -550,7 +550,7 @@ document (a document-wide <a class="reference" href="#table-of-contents">table o
 <span id="image-target-2"></span><span id="image-target-1"></span><img alt="../../../docs/user/rst/images/title.png" id="image-target-3" name="image-target-3" src="../../../docs/user/rst/images/title.png" />
 <p>A figure directive:</p>
 <div align="right" class="figclass1 figclass2 figure">
-<img alt="reStructuredText, the markup syntax" class="class1 class2" src="../../../docs/user/rst/images/biohazard.png" width="50" />
+<img alt="reStructuredText, the markup syntax" class="class1 class2" src="../../../docs/user/rst/images/biohazard.png" style="width: 50px;" />
 <p class="caption">A figure is an image with a caption and/or a legend:</p>
 <div class="legend">
 <table border="1" class="docutils">
@@ -576,7 +576,7 @@ document (a document-wide <a class="reference" href="#table-of-contents">table o
 <p>This paragraph might flow around the figure...</p>
 <p>A centered figure:</p>
 <div align="center" class="figure">
-<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" width="50" />
+<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 50px;" />
 <p class="caption">This is the caption.</p>
 <div class="legend">
 <p>This is the legend.</p>
@@ -586,7 +586,7 @@ document (a document-wide <a class="reference" href="#table-of-contents">table o
 <p>This paragraph might flow around the figure...</p>
 <p>A left-aligned figure:</p>
 <div align="left" class="figure">
-<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" width="50" />
+<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 50px;" />
 <p class="caption">This is the caption.</p>
 <div class="legend">
 <p>This is the legend.</p>
@@ -594,6 +594,15 @@ document (a document-wide <a class="reference" href="#table-of-contents">table o
 </div>
 </div>
 <p>This paragraph might flow around the figure...</p>
+<p>Now widths:</p>
+<p>An image 2 em wide:</p>
+<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 2em;" />
+<p>An image 2 em wide and 30 pixel high:</p>
+<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 2em; height: 30px;" />
+<p>An image occupying 70% of the line width:</p>
+<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 70%;" />
+<p>An image 3 cm high:</p>
+<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="height: 3cm;" />
 </div>
 <div class="section" id="admonitions">
 <h3><a class="toc-backref" href="#id64" name="admonitions">2.14.3&nbsp;&nbsp;&nbsp;Admonitions</a></h3>
diff --git a/docutils/test/functional/expected/standalone_rst_latex.tex b/docutils/test/functional/expected/standalone_rst_latex.tex
index 3abaf8a9e..06e00ab67 100644
--- a/docutils/test/functional/expected/standalone_rst_latex.tex
+++ b/docutils/test/functional/expected/standalone_rst_latex.tex
@@ -925,6 +925,24 @@ The legend may consist of several paragraphs.
 
 This paragraph might flow around the figure...
 
+Now widths:
+
+An image 2 em wide:
+
+\includegraphics{../../../docs/user/rst/images/biohazard.png}
+
+An image 2 em wide and 30 pixel high:
+
+\includegraphics{../../../docs/user/rst/images/biohazard.png}
+
+An image occupying 70{\%} of the line width:
+
+\includegraphics{../../../docs/user/rst/images/biohazard.png}
+
+An image 3 cm high:
+
+\includegraphics{../../../docs/user/rst/images/biohazard.png}
+
 
 %___________________________________________________________________________
 
diff --git a/docutils/test/functional/expected/standalone_rst_pseudoxml.txt b/docutils/test/functional/expected/standalone_rst_pseudoxml.txt
index 62f923a03..d7f4d0103 100644
--- a/docutils/test/functional/expected/standalone_rst_pseudoxml.txt
+++ b/docutils/test/functional/expected/standalone_rst_pseudoxml.txt
@@ -1191,6 +1191,20 @@
                             The legend may consist of several paragraphs.
                 <paragraph>
                     This paragraph might flow around the figure...
+                <paragraph>
+                    Now widths:
+                <paragraph>
+                    An image 2 em wide:
+                <image uri="../../../docs/user/rst/images/biohazard.png" width="2em">
+                <paragraph>
+                    An image 2 em wide and 30 pixel high:
+                <image height="30px" uri="../../../docs/user/rst/images/biohazard.png" width="2em">
+                <paragraph>
+                    An image occupying 70% of the line width:
+                <image uri="../../../docs/user/rst/images/biohazard.png" width="70%">
+                <paragraph>
+                    An image 3 cm high:
+                <image height="3cm" uri="../../../docs/user/rst/images/biohazard.png">
             <section ids="admonitions" names="admonitions">
                 <title auto="1" refid="id64">
                     <generated classes="sectnum">
diff --git a/docutils/test/functional/input/data/standard.txt b/docutils/test/functional/input/data/standard.txt
index cfcc6e7f7..140be35c7 100644
--- a/docutils/test/functional/input/data/standard.txt
+++ b/docutils/test/functional/input/data/standard.txt
@@ -485,6 +485,30 @@ A left-aligned figure:
 
 This paragraph might flow around the figure...
 
+Now widths:
+
+An image 2 em wide:
+
+.. image:: ../../../docs/user/rst/images/biohazard.png
+   :width: 2 em
+
+An image 2 em wide and 30 pixel high:
+
+.. image:: ../../../docs/user/rst/images/biohazard.png
+   :width: 2em
+   :height: 30 px
+
+An image occupying 70% of the line width:
+
+.. image:: ../../../docs/user/rst/images/biohazard.png
+   :width: 70%
+
+An image 3 cm high:
+
+.. image:: ../../../docs/user/rst/images/biohazard.png
+   :height: 3 cm
+
+
 Admonitions
 ```````````
 
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_images.py b/docutils/test/test_parsers/test_rst/test_directives/test_images.py
index 3e0c89344..4e4c429f6 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_images.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_images.py
@@ -98,6 +98,42 @@ totest['images'] = [
 """],
 ["""\
 .. image:: picture.png
+   :width: 200px
+   :height: 100 em
+""",
+"""\
+<document source="test data">
+    <image height="100em" uri="picture.png" width="200px">
+"""],
+["""\
+.. image:: picture.png
+   :width: 50%
+   :height: 10mm
+""",
+"""\
+<document source="test data">
+    <image height="10mm" uri="picture.png" width="50%">
+"""],
+["""\
+.. image:: picture.png
+   :width: 50%
+   :height: 40%
+""",
+"""\
+<document source="test data">
+    <system_message level="3" line="1" source="test data" type="ERROR">
+        <paragraph>
+            Error in "image" directive:
+            invalid option value: (option: "height"; value: \'40%\')
+            not a positive measure of one of the following units:
+            "em" "ex" "px" "in" "cm" "mm" "pt" "pc" "".
+        <literal_block xml:space="preserve">
+            .. image:: picture.png
+               :width: 50%
+               :height: 40%
+"""],
+["""\
+.. image:: picture.png
    :height: 100
    :width: 200
    :scale: 50