some markup features
======================

What follows is a mixture of restructured text and sphinx markup
to illustrate some useful features.
Refer to the docutils and sphinx documentation for full resources.


We start out by mentioning a couple of ReST markups which sphinx
uses.  Both these are in paragraph-mode - they occur as a blank line 
followed by a line at the same indentation as the previous non-blank
line, starting with two periods.  They are

comment
   text following is ignored till the occurence of the next blank
   line::

      ..  commented text here 

link label:
   this sets up a link to this location which is able to be referenced by
   the ``:ref:`` mode below::

      .. _link_label_here:
   
   The label to reference is the text ``link_label_here``.

The form of comments and link labels is similar to but different from
the whole family of directives.  They follow.


directives 
      /paragraph mode): -  a blank line followed by a line at the same
      indentation as the previous non-blank line, beginning with::
         
         .. directive_name_here::
      
      (Each is followed by *two* colons.)
      
      There are many directive names, including:  
          ``code-block``
          ``image``
          ``include``
          ``index``
          ``literalinclude``
          ``math``
          ``note``
          ``only``
          ``seealso``
          ``table``
          ``warning``
      
      Each of these performs an operation on the argument that follows.
      There may be modifying arguments on subsequent indented lines
      (before any blank lines) which take the form::
         
         :modification: modification_argument

      See for example the form of equation-numbered
      :ref:`math-equations <math>` and :ref:`csv-tables<csv_table>`.

roles
      (inline mode): - of the form::
      
         :role_name_here:`text to be interpreted here`

      Role names include:

      :ref:`math <math>`
         inline math-mode, 

      ``obj``, ``meth``, ``class``, ... 
         will reference any documented python objects
         see the source of :ref:`Pulp example <pulp_case_study>`  for
         an illustration

      :ref:`ref <links>`
         will reference any labelled location (of the form ``..
         _link_label_here:``)


.. toctree::
   :maxdepth: 1

   code
   inclusion
   links
   tables
   images
   math
   footnotes