================= 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 parentheses. .. 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.rst``, 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.rst``. `The HTML bibliography `__ 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 preceded 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.