..                            -*- rst-mode -*-

How to label and reference a "formal" figure with RST
*****************************************************

And now for something completely different.

Handcrafted Figure numbering for HTML
=====================================

.. _mcicon:

.. figure:: mc.png
   
   Figure 1: Midnight Commander icon
   
`Figure 1`_ shows an icon for the file manager `Midnight Commander`.

The HTML output is OK, in the LaTeX->PDF output, the key ``Figure 1:`` is
repeated.


Label and Reference via LaTeX and custom roles
===============================================

After defining two custom roles and their expansion in LaTeX, its possible
to utilise LaTeX's reference mechanism.

.. role:: ref

.. role:: label

.. raw::  latex

  \newcommand*{\docutilsroleref}{\ref}
  \newcommand*{\docutilsrolelabel}{\label}


.. figure:: mc.png
   :width: 50

   :label:`mc` Midnight Commander icon enlarged 
   
Figure :ref:`mc` shows the icon for the file manager `Midnight
Commander` enlarged to a width of 50 Pixel.

The LaTeX output is OK, the HTML output can be corrected with a custom style
sheet:

* Add the key ``Figure #:`` with ``:before`` pseudo class and automatic
  numbering.
  
* Suppress the label with ``span.label{visibility: hidden;}``  

* Replacing the reference with the correct number remains unsolved.

.. List of figures

.. _Figure 1: mcicon_
