SVG Images
----------

.. image:: ../../../docs/user/rst/images/biohazard.svg
   :width: 48 px
   :height: 48 px
   :align: left

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.)

Rendering behaviour varies, depending on

a) The SVG image itself, e.g. fixed-size vs. scaling::

      width="280"              viewBox="0 0 280 27"
      height="27"              width="100%"
                               height="100%"

b) The method used to put the image in the document.

   For HTML, there are several alternatives including:

   * 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).

   The `html4css1` writer uses ``<object>`` tags, the `html-base` and `xhtml11`
   writers use ``<img>`` tags.

   .. cf. http://edutechwiki.unige.ch/en/Using_SVG_with_HTML5_tutorial

c) The viewing agent.

   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.

* .. image:: ../../../docs/user/rst/images/title-scaling.svg
     :width: 50%
     :align: right

  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/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

* .. image:: ../../../docs/user/rst/images/biohazard-scaling.svg
     :height: 1 em
     :align: right

  A scaling image 1 em high, right aligned:

* A scaling image 5 mm x 5 mm, centered, with hyperlink reference:

  .. 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.

Older versions of `webkit` based browsers (chromium, safari, midori,
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.