Let "html-base" and "xhtml11" writers wrap SVG images in <img> tags.

Edit of the SVG image functional test section.

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

1 files changed, 99 insertions, 53 deletions

diff --git a/test/functional/input/data/svg_images.txt b/test/functional/input/data/svg_images.txt
index 2bb4cba81..b84e144b1 100644
--- a/test/functional/input/data/svg_images.txt
+++ b/test/functional/input/data/svg_images.txt
@@ -6,76 +6,122 @@ SVG Images
    :height: 48 px
    :align: left
 
-Scalable vector graphics (SVG) images are not supported by all backends.
-Rendering depends partially on the backend, especially if the size is
-not explicitely given.
+Scalable vector graphics (SVG) images are the only standards-compliable way
+to include vector graphics in HTML documents. However, they are not
+supported by all backends/output formats. (E.g., LaTeX supports the
+PDF or Postscript formats for vector graphics instead.)
 
-.. image:: ../../../docs/user/rst/images/title-scaling.svg
-   :width: 50%
-   :align: left
+Rendering behaviour varies, depending on
 
-A scaling image occupying 50% of the line width (scales with the browser
-window).
+a) The SVG image itself, e.g. fixed-size vs. scaling::
 
-Whether an SVG image is scaled or clipped/padded cannot be set in the
-containing HTML.  If the image is wrapped in ``<object>`` tags, it
-depends on the viewport declaration inside its root <svg> element, if it is
-wrapped in ``<img>`` it depends on the browser.
+      width="280"              viewBox="0 0 280 27"
+      height="27"              width="100%"
+                               height="100%"
 
-.. image:: ../../../docs/user/rst/images/title.svg
-   :width: 50%
-   :height: 15 px
-   :align: left
+b) The method used to put the image in the document.
 
-A fixed-size image in a box with 50% of the line width, 15 pixles high.
+   For HTML, there are several alternatives including:
 
-.. image:: ../../../docs/user/rst/images/title-scaling.svg
-   :width: 50 %
-   :height: 1.2 em
-   :align: right
+   * using the HTML ``<img>`` tag (not for interactive/animated SVG),
+   * using the HTML ``<object>`` tag,
+   * including within SVG using the SVG ``<image>`` tag,
+   * embedd the SVG code within HTML (inlining).
 
-A scaling image occupying 50% of the line width and 1.2 em high,
-right aligned (this SVG image keeps the aspect ratio):
+   The `html4css1` writer uses ``<object>`` tags, the `html-base` and `xhtml11`
+   writers use ``<img>`` tags.
 
-.. |inline-svg| image:: ../../../docs/user/rst/images/biohazard-scaling.svg
-   :height: 0.8 em
+   .. cf. http://edutechwiki.unige.ch/en/Using_SVG_with_HTML5_tutorial
 
-* An inline SVG image |inline-svg| scaled to a height of 0.8 em.
+c) The viewing agent.
 
-.. image:: ../../../docs/user/rst/images/biohazard-scaling.svg
-   :height: 1 em
-   :align: left
+   All up-to-date HTML browsers support SVG, however not all do this fully
+   and in the same manner. Many older versions, especially IE < 9, have
+   deficiencies or require plug-ins (i.e. don't support the ``<img>`` tag).
+   
+If the image is wrapped in ``<object>`` or ``<svg>`` tags, it depends on the
+``viewBox`` declaration inside the images root ``<svg>`` element whether an
+SVG image is scaled or clipped/padded. Images wrapped in ``<img>`` are
+always scaled.
 
-A scaling image 1 em high, left aligned.
+* .. image:: ../../../docs/user/rst/images/title-scaling.svg
+     :width: 50%
+     :align: right
 
-A scaling image 5 mm x 5 mm, centered, with hyperlink reference:
+  A scaling image (scales with the browser window), occupying 50% of the line
+  width. The ``viewBox`` setting in the image file enables auto-scaling also in
+  ``<object>`` tags and embedded SVG (if width and hight are set to 100% in the
+  SVG <image> tag).
 
-.. image:: ../../../docs/user/rst/images/biohazard-scaling.svg
-   :target: Directives_
-   :width: 5 mm
-   :height: 5 mm
-   :align: center
 
-.. image:: ../../../docs/user/rst/images/biohazard.svg
-   :width: 4 cm
-   :height: 2 em
-   :align: left
+* .. image:: ../../../docs/user/rst/images/title.svg
+     :width: 50%
+     :height: 15 px
+     :align: right
+
+  A fixed-size image in a box 50% wide and 15 pixles high. This image is
+  scaled, if wrapped in an ``<img>`` tag but clipped in an ``<object>`` tag
+  or within SVG.
+
+* .. image:: ../../../docs/user/rst/images/title-scaling.svg
+     :width: 50 %
+     :height: 1.5 em
+     :align: right
+
+  A right aligned, scaling image 50% wide and 1.5 em high. (This SVG image
+  keeps the aspect ratio.)
+
+* An inline image |inline-svg| scaled to a height of 0.8 em.
+
+  .. |inline-svg| image:: ../../../docs/user/rst/images/biohazard-scaling.svg
+     :height: 0.8 em
 
-A fixed-size image in a  4 cm x 2 em box.
+* .. image:: ../../../docs/user/rst/images/biohazard-scaling.svg
+     :height: 1 em
+     :align: right
 
-.. figure:: ../../../docs/user/rst/images/title.svg
-   :alt: reStructuredText, the markup syntax
-   :width:  290 px
-   :height:  28 px
+  A scaling image 1 em high, right aligned:
 
-   SVG image in a figure.
+* A scaling image 5 mm x 5 mm, centered, with hyperlink reference:
 
-.. image:: ../../../docs/user/rst/images/biohazard-bitmap.svg
-   :width: 3em
-   :align: right
+  .. image:: ../../../docs/user/rst/images/biohazard-scaling.svg
+     :target: SVG Images_
+     :width: 5 mm
+     :height: 5 mm
+     :align: center
+
+* .. image:: ../../../docs/user/rst/images/biohazard.svg
+     :width: 4 cm
+     :height: 2 em
+     :align: right
+
+  A fixed-size image in a  4 cm x 2 em box.
 
-An SVG image with embedded bitmap, 3 em wide, right aligned.
 Older versions of `webkit` based browsers (chromium, safari, midori,
-konqueror) cannot display the contained bitmap image if the SVG is wrapped
-in ``<img>`` tags. The image does not scale properly if wrapped in
-``<object>`` tags.
+konqueror) support the ``<img>`` tag but don't display contained bitmap
+images in this case.
+
+* .. image:: ../../../docs/user/rst/images/biohazard-bitmap.svg
+     :width: 3em
+     :align: right
+
+  A small, fixed-size SVG image with embedded bitmap, The ``:width:`` is 
+  set to 3 em in the rST source. Does not scale if wrapped in ``<object>``
+  tags.
+
+
+* .. image:: ../../../docs/user/rst/images/biohazard-bitmap-scaling.svg
+     :width: 3em
+     :align: right
+
+  A scaling SVG image with embedded bitmap, 3 em wide.
+
+SVG images can also be put in figures:
+
+   .. figure:: ../../../docs/user/rst/images/title.svg
+      :alt: reStructuredText, the markup syntax
+      :width:  290 px
+      :height:  28 px
+      :align: center
+   
+      **Figure:** SVG image in a figure.