.. -*- rst-mode -*-

Syntax highlight with the ``listings.sty`` LaTeX package
========================================================

.. contents::
.. sectnum::

The `listings`_ LaTeX package provides highly customisable and advanced
syntax highlight, though only for LaTeX (and LaTeX derived PS|PDF). 

State of the art
----------------

Using listings_ for literal blocks is now possible with the standard latex
writer with a new option ``--literal-block-env``.

The alternate latex writer uses a slightly different implementation and a
shorter name for the option: ``--literal-env`` (as an *environment* is the
latex counterpart of a *block element* in HTML or rst nomenclature).

Alternative latex writer
------------------------

`latex2e_listings`_ 
  Sample implementation of a latex writer variant with
  support for syntax highlight with ``listings.sty``: 

Usage
~~~~~

A usage scenario is:

#. Place `latex2e_listings.py`_ in your PYTHONPATH.
#. Place `rst2latex2e_listings.py`_ in your PATH.
#. Place `listings-options.sty`_ in your TEXPATH or the pwd and configure to
   your needs.
#. Run ``rst2latex2e_listings.py`` with option 
   ``--stylesheet=listings-options.sty`` on your rst document.

Literal blocks will be typeset with listings.sty, see the example:
`test.txt`, `test.tex`, `test.pdf`.

.. _latex2e_listings: ../latex2e_listings/
.. _latex2e_listings.py: ../latex2e_listings/latex2e_listings.py
.. _rst2latex2e_listings.py: ../latex2e_listings/rst2latex2e_listings.py
.. _listings-options.sty: ../latex2e_listings/listings-options.sty

Changelog
~~~~~~~~~
:2007-06-28: In preparation, no code written yet.
:2007-10-15: First draft, works for me.
:2008-02-29: Basic usage information.

"literal-env" configuration setting
-------------------------------------------

The ``literal-enf`` config option defines, which environment is used for
typesetting literal-blocks (and with which arguments).

Some considerations about the implementation:
  
* The implementation must consider that "verbatim"-like environments
  clash with literal-blocks containing inline elements and 
  
  - use a fall-back non-verbatim environment (e.g. `alltt`), or
  
  - 'flatten' the literal-block doctree node
  
  in this case.

* class arguments of the literal-block node should overwrite the default
  language given in the config setting.
  
Another idea by Alan Isaac:

  Suppose I have a literal inclusion that produces the document tree node
  ``<literal_block source="myfile.py" xml:space="preserve">`` Would you find
  it reasonable for the LaTeX writer to simply note the source-file
  extension and based on this to use the lstlistings environment, setting
  the language to Python? This seems good to me and would be my first
  choice.


LaTeX environments for literal blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A list of candidate environments
  
===========  ========================  =================================== 
Environment  Escaping                  Required Packages
===========  ========================  =================================== 
verbatim     no			       None
Verbatim     no                        fancyvrb_
verbatimtab  no                        moreverb_
listing      no                        moreverb_
lstlisting   no                        listings_
alltt        '\\', '{' and '}'         alltt_     (standard package)
None         whitespace and	       None 
             special chars
===========  ========================  ===================================

The environments from the fancyvrb_ package ("Verbatim", "BVerbatim", ...)
do not necessarily need to be supported by this setting. Their use can be
defined in a stylesheet with ``\DefineVerbatimEnvironment`` However, the
latex writer must always place ``\begin(verbatim)`` and ``\end(verbatim)``
on a line of its own.

Some of the above packages provide commands for verbatim file input.
The ``:literal:`` option of the "include" directive should translate to:

===========  ========================  =================================== 
Environment  Input Command             Required Packages
===========  ========================  =================================== 
verbatim     verbatiminput             verbatim_
Verbatim     Verbatiminput             fancyvrb_
verbatimtab  verbatimtabinput          moreverb_
listing      listinginput              moreverb_
lstlisting   lstlistinginput           listings_
alltt        input in alltt            alltt_
             environment
quote        input
===========  ========================  ===================================



.. References
   ----------
   
.. _docutils: http://docutils.sourceforge.net/ 
.. _rest2web: http://www.voidspace.org.uk/python/rest2web/
.. _pygments: http://pygments.org/ 
.. _listings: 
   http://www.ctan.org/tex-archive/help/Catalogue/entries/listings.html
.. _fancyvrb: 
   http://www.ctan.org/tex-archive/help/Catalogue/entries/fancyvrb.html
.. _alltt: 
   http://www.ctan.org/tex-archive/help/Catalogue/entries/alltt.html
.. _moreverb: 
   http://www.ctan.org/tex-archive/help/Catalogue/entries/moreverb.html
.. _verbatim: 
   http://www.ctan.org/tex-archive/help/Catalogue/entries/verbatim.html
.. _Docutils Document Tree:
   http://docutils.sf.net/docs/ref/doctree.html#classes
.. _proposal for a code-block directive in docutils:
   http://docutils.sourceforge.net/sandbox/code-block-directive/docs/syntax-highlight.html
