.. include:: /include/substitutions.txt
.. include:: /include/external_links.txt
.. include:: /include/custom_roles.txt
.. _literal text:

************
Literal Text
************

Literal text in a reStructuredText context is (loosely) text which is text in which
no markup processing is performed.



In-Line Literal Text
********************


Decorated In-Line Literal Text
==============================

.. code-block:: rst

    This is an in-line (here -->) ``literal`` string.

Result:  This is an in-line (here -->) ``literal`` string.

As you can see, the word "literal" above looks different than the surrounding text.
This is done by Sphinx (using Docutils internally) marking that text in HTML like this:

.. code-block:: html

    Result:  This is an in-line (here –>)
    <code class="docutils literal notranslate"><span class="pre">literal</span></code>
    string.

which gives a wide latitude for the (customizable) theme to perform formatting on
such text using CSS.  Indeed, what you see above is done with CSS.


Interpreted Role Literal Text
=============================

There is a built-in interpreted role that can also be used for literal text:

.. code-block:: rst

    This is :literal:`some  text  here  that  is  meant  to  be  literal  with  added  spaces`.

Result:

This is :literal:`some  text  here  that  is  meant  to  be  literal  with  added  spaces`.


Default Interpreted Role
========================

The default Interpreted-Text Role can be set so that un-decorated interpreted text
(text merely surrounded with single back-quotes).  You can do this by adding the
following line to your ``conf.py`` file:

.. code-block:: py

    default_role = 'literal'

Then text like this:

.. code-block:: rst

    This is a `literal` string.

will look like this in the output HTML:

This is a `literal` string.

.. note::

    This is generally not advised so that writers do not get into the habit of using
    single back-quotes to mean literal text.



Literal Blocks
**************

Literal blocks are defined as areas of text in which no markup processing is done.

The following are different ways of placing literal, pre-formatted blocks into your text.


Indented Literal Blocks
=======================

.. code-block:: rst

    ::

        Anything here and on subsequent lines.
        Note that the :: only has to be at the end
        of the line, so it could have text before it.

    Some text here::

        Anything here and on subsequent lines.
        Note that the :: only has to be at the end
        of the line, so it could have text before it.

            Lines can be intended relative to surrounding text in block.

Result:

::

    Anything here and on subsequent lines.
    Note that the :: only has to be at the end
    of the line, so it could have text before it.

Some text here::

    Anything here and on subsequent lines.
    Note that the :: only has to be at the end
    of the line, so it could have text before it.

        Lines can be intended relative to surrounding text in block.

The Pygments library manages the language highlighting in these paragraphs.  If you
are getting highlighting you didn't count on, check your ``conf.py`` file for the
``highlight_language`` setting.  ``highlight_language = 'text'`` can be set for
"no highlighting".

Any indentation level is acceptable.  The literal block ends with the end of the
indentation.


Quoted Literal Blocks
=====================

Quoted literal blocks are created exactly like Literal Blocks except instead of
indenting the quoted block, you begin each line of it with a printable
non-alphanumeric ASCII character.  Any of these characters can be used to lead the
quoted block, so long as each quoted line begins with the same one:

    ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

.. code-block:: rst

    John Doe wrote::

    >> Great idea!
    >
    > Why didn't I think of that?

    You just did!  ;-)

Result:

John Doe wrote::

>> Great idea!
>
> Why didn't I think of that?

You just did!  ;-)


Text Code Blocks
================

Another unusual way of generating literal text is to enclose it in a code-block
directive like this:

.. code-block:: rst

    .. code-block:: text

        Literal text here

Result:

.. code-block:: text

    Literal text here


Doctest Blocks
==============

Doctest blocks are interactive Python sessions cut-and-pasted into
docstrings.  They are meant to illustrate usage by example, and
provide an elegant and powerful testing environment via the `doctest module`_ in the Python standard library.

Doctest blocks are text blocks which begin with the Python interactive
interpreter main prompt (``>>>`` followed by a space) and end with
a blank line. Doctest blocks are treated as a special case of literal
blocks, without requiring the literal block syntax.  If both are present,
the literal block syntax takes priority over Doctest block syntax::

    This is an ordinary paragraph.

    >>> print 'this is a Doctest block'
    this is a Doctest block

Result:

This is an ordinary paragraph.

>>> print 'this is a Doctest block'
this is a Doctest block

The following is a literal block::

    >>> This is not recognized as a doctest block by
    reStructuredText.  It *will* be recognized by the doctest
    module, though!

Indentation is not required for doctest blocks.



Block Quotes
************

A text block that is indented relative to the preceding text, without preceding markup
indicating it to be a literal block or other content, is a block quote.  Do not
mistake these for literal blocks---they are not.  Reason:  all markup processing
(for body elements and inline markup) continues within the block quote.

.. code-block:: rst

    This is an ordinary paragraph, introducing a block quote.

        "It is my business to *know things*.  That is my trade."

        ---Sherlock Holmes

Result:

This is an ordinary paragraph, introducing a block quote.

    "It is my business to *know things*.  That is my trade."

    ---Sherlock Holmes

The theme may or may not use special formatting for block quotes.