=================
Custom RST Markup
=================

This file describes the rst customizations that were made for the NLTK
book, and gives examples of those customizations.

.. contents::

.. _new-directives:

New Directives
==============

Examples
--------
Use the example directive (``ex``) to define linguistic examples such
as sentences.  Examples will be automatically numbered.  Example
directives may be nested.

.. rst_example::

  .. ex:: Your likes are quite unpredictable.

  .. ex::
    .. ex:: A dog barks.
    .. ex:: ``'some x.((dog x) and (bark x))'``

Examples may be labeled as targets, and referred to later via
references; the text content of the references is automatically
replaced by the example number, in parenthases.

.. rst_example::

  .. _dislikes:

  .. ex:: Your dislikes are quite predictable.

  .. _likes:

  .. ex:: Your likes are quite unpredictable.

  Compare sentences `dislikes`_ and `likes`_.

When the book is built as a single file, a single example numbering
counter is used for the entire book.  When chapters are built
individually, a separate counter will be used for each chapter.  In
order to make sure that inter-chapter cross-references to examples are
usable in both cases, all inter-chapter example references should use
the following form:

.. rst_example::

  See Example `likes`_ in Chapter `new-directives`_.

Syntax Trees
------------
The tree directive (``tree``) can be used to render syntax trees from
treebank-style descriptions.  The tree directive is typically nested
inside an example directive.

.. rst_example::
  .. ex::
    .. tree:: (S (NP Jane) (VP (V walks)))

Feature Structures
------------------
The attribute-value matrix directive (``avm``) can be used to render
attribute-value matrices from text descriptions.  The format used is
the same as the output format for nltk feature structures.  The ``avm``
directive is usually nested inside an example directive.

.. rst_example::
  .. ex::
    .. avm::
      [ address = (1) [ number = 74           ] ]
      [               [ street = 'rue Pascal' ] ]
      [                                         ]
      [ name    = 'Lee'                         ]
      [                                         ]
      [ spouse  = [ address -> (1)  ]           ]
      [           [ name    = 'Kim' ]           ]
  
Glosses
-------
The gloss directive (``gloss``) can be used to write word-by-word
glosses.  It is typically nested inside an example directive.  The
vertical bar character (``|``) is used to define columns.  This is
automatically converted to a corresponding table, and rendered without
lines.

.. rst_example::
  .. ex:: 
    .. gloss::
       Il  | mange | une | pomme.
       He  | eats  | an  | apple.
       *He eats an apple.*

  .. ex:: 
    .. gloss::
      Dit  | is | een | voorbeeldje    | in | het | Nederlands.
      This | is | a   | little example | in |     | Dutch.
      *This is a little example in Dutch.*

Conditional Execution
---------------------
Three new directives, ``def`` (define), ``ifdef`` (if-defined), and
``ifndef`` (if-not-defined), can be used to control whether a section
of the document gets processed.  This is currently used in
``definitions.txt``, to prevent multiple imports of the same file
(which causes errors from redefinitions of symbols).

.. rst_example::

  .. def:: foo

  .. ifdef:: foo

     This is included, since ``foo``
     is defined.

  .. ifdef:: bar

     This is not included.

Citations and the Bibliography
==============================
When the standard citation markup is used (``[label]_``), the label is
automatically looked up in the bibtex file ``book.bib``.  If found, it
is replaced by a citation link to the bibliography.

.. rst_example::

  For more information, see [abney1996]_.

The LaTeX bibliography is generated automatically by LaTeX when
processing ``book.txt``.  `The HTML bibliography <bibliography.html>`__
is generated by the Makefile, using ``bib2xhtml``.

Indexing
========
Three new inline roles are defined for adding terms to the index:

- The ``idx`` role adds the selected text as an index entry; but does not
  mark the term in any way.

- The ``dt`` (define-term) role adds the selected text as an index entry,
  and displays the term in bold.

- The ``topic`` role adds the selected text as an index entry, but does
  not display the text.

The ``index`` directive can then be used to construct the index
itself.  If the optional flag ``:extern:`` is specified, then index
terms from all specified ``.ref`` files will also be included.

.. rst_example::

  :dt:`Syntax` is the study of the 
  structure of linguistic expressions.

  :topic:`cameras` :topic:`amphibians`
  John used a :idx:`telescopic lens` to 
  get detailed pictures of the turtle.

  .. index::

In the LaTeX/PDF output, the index will refer to page numbers.  In the
HTML output, the index will refer to section numbers and provide
hyperlinks.

Automatic Numbering and References
==================================

.. _some-section:

Sections
--------
Sections are automatically numbered.  The current section number can
be overridden by including a section number as the first word in a
section title.  E.g., this is used when processing individual chapters
to set the top-level section number correctly.  

Three directives can be used to adjust the section numbering:

- The ``preface`` directive resets the top-level section number to 1,
  and uses roman numerals for sections (I, II, III, IV, ...).
- The ``body`` directive resets the top-level section number to 1, and
  uses arabic numerals for sections (1, 2, 3, 4, ...).
- The ``appendix`` directive resets the top-level section number to
  1, and uses alphabet letters for sections (A, B, C, D, ...).

Sections may be labeled using the target directive::

  .. _some-section:

  Some Section
  ------------

Sections can then be referenced using the inline reference markup.
The text of each inline references to a section is replaced by its
target's section number.  If the reference is immediately preceeded by
the word "chapter" or "section," then that word will also be included
in the reference.

.. rst_example::

  See some-section_.

Figures and Tables
------------------

Figures and tables are automatically numbered.  These numbers are used
in the figure and table captions, and are used for referencing.
Figures & tables are numbered with respect to the chapter they occur
in (e.g., figure 8.3 is the third figure in chapter 8).

Like sections, figures and tables can be labeled using the target
directive; and then referenced with inline reference markup.  The text
of the inline reference to a figure/table will be replaced by the
figure/table number.

.. rst_example::

  .. _some-figure:
  .. figure:: ../images/are.png
     :scale: 30

     A field subdivided.

  See Figure some-figure_

  .. _some-table:

  +-----+-----+
  | foo | bar |
  +-----+-----+

  See Table some-table_, which has nothing to do with Sentence
  some-figure_.
 

Other Changes
=============

Doctest Blocks
--------------
Python doctest blocks are automatically colorized.

.. rst_example::
  >>> for i in range(5):
  ...     print i,
  0 1 2 3 4

If doctest blocks are indented (i.e., nested in a ``block_quote``
node), they will be automatically unindented.
