.. _links:

links
------

.. _hyperlinks:

www-links
^^^^^^^^^^

Sphinx renders text of the form ``http://www...`` as a web-link
without it requiring any markup.
`Alternate text <http://www.google.com>`_ appears for the link  
when of the form (note the trailing underscore - rst-format)::

   `Alternate text <http://www.google.com>`_ 

cross-references
^^^^^^^^^^^^^^^^

Sphinx extends restructured text in linking between documents.
Links to other parts of the document tree are of two forms:

   #. section links, whose label precedes the section title ::

         .. _label_here:

         section title
         -------------

      This creates a hyperlink target (label) at this section title.
         
      We then link to the section title in this or other documents
      with text of the form ::

         :ref:`<label_here>`

      A label different from the section title may be inserted too, with the form::

         :ref:`alternate title <label_here>`

      A link to the :ref:`code` section is created in this way.

   #. links to arbitrary text:

      Any text other than a section title (or figure caption) can
      be referenced similarly, except that it *must* have an explicit
      title::  

         :ref:`label name here <label_here>`


indexing
---------

Section titles are not automatically indexed.
Preceding any line with an ``index directive`` of the form::
      
   .. index:: item1, item2, item3, ...

inserts index entries for these items, which link back to this
position.

An ``index directive`` of the form::
      
   .. index:: pair: itemA; indexB

inserts two entries of the form:

   itemA
      itemB

and 

   itemB
      itemA