..                            -*- rst-mode -*-

.. sectnum::

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.

This also works for section numbers, e.g. this is section
:ref:`label-and-reference-via-latex-and-custom-roles`.


The LaTeX output is OK, the HTML output can be improved 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_