1 =============================
2 reStructuredText Directives
3 =============================
5 :Contact: docutils-develop@lists.sourceforge.net
8 :Copyright: This document has been placed in the public domain.
12 This document describes the directives implemented in the reference
13 reStructuredText parser.
15 Directives have the following syntax::
17 +-------+-------------------------------+
18 | ".. " | directive type "::" directive |
21 +-------------------------------+
23 Directives begin with an explicit markup start (two periods and a
24 space), followed by the directive type and two colons (collectively,
25 the "directive marker"). The directive block begins immediately after
26 the directive marker, and includes all subsequent indented lines. The
27 directive block is divided into arguments, options (a field list), and
28 content (in that order), any of which may appear. See the Directives_
29 section in the `reStructuredText Markup Specification`_ for syntax
32 Descriptions below list "doctree elements" (document tree element
33 names; XML DTD generic identifiers) corresponding to individual
34 directives. For details on the hierarchy of elements, please see `The
35 Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document
36 type definition. For directive implementation details, see `Creating
37 reStructuredText Directives`_.
39 .. _Directives: restructuredtext.html#directives
40 .. _reStructuredText Markup Specification: restructuredtext.html
41 .. _The Docutils Document Tree: ../doctree.html
42 .. _Docutils Generic DTD: ../docutils.dtd
43 .. _Creating reStructuredText Directives:
44 ../../howto/rst-directives.html
64 :Directive Types: "attention", "caution", "danger", "error", "hint",
65 "important", "note", "tip", "warning", "admonition"
66 :Doctree Elements: attention, caution, danger, error, hint, important,
67 note, tip, warning, admonition_, title
68 :Directive Arguments: None.
69 :Directive Options: `:class:`_, `:name:`_
70 :Directive Content: Interpreted as body elements.
72 Admonitions are specially marked "topics" that can appear anywhere an
73 ordinary body element can. They contain arbitrary body elements.
74 Typically, an admonition is rendered as an offset block in a document,
75 sometimes outlined or shaded, with a title matching the admonition
79 Beware killer rabbits!
81 This directive might be rendered something like this::
83 +------------------------+
86 | Beware killer rabbits! |
87 +------------------------+
89 The following admonition directives have been implemented:
101 Any text immediately following the directive indicator (on the same
102 line and/or indented on following lines) is interpreted as a directive
103 block and is parsed for normal body elements. For example, the
104 following "note" admonition directive contains one paragraph and a
105 bullet list consisting of two list items::
107 .. note:: This is a note admonition.
108 This is the second line of the first paragraph.
110 - The note contains all indented body elements
112 - It includes this bullet list.
118 :Directive Type: "admonition"
119 :Doctree Elements: admonition_, title
120 :Directive Arguments: One, required (admonition title)
121 :Directive Options: Possible, see below.
122 :Directive Content: Interpreted as body elements.
124 This is a generic, titled admonition. The title may be anything the
127 The author-supplied title is also used as a `"classes"`_ attribute value
128 after being converted into a valid identifier form (down-cased;
129 non-alphanumeric characters converted to single hyphens; "admonition-"
130 prefixed). For example, this admonition::
132 .. admonition:: And, by the way...
134 You can make up your own admonition too.
136 becomes the following document tree (pseudo-XML)::
138 <document source="test data">
139 <admonition classes="admonition-and-by-the-way">
143 You can make up your own admonition too.
145 The `common options`_ are recognized:
148 Overrides the computed `"classes"`_ attribute value.
151 Add `text` to the `"names"`_ attribute of the admonition element.
158 There are two image directives: "image" and "figure".
164 :Directive Type: "image"
165 :Doctree Element: image_
166 :Directive Arguments: One, required (image URI).
167 :Directive Options: Possible.
168 :Directive Content: None.
170 An "image" is a simple picture::
172 .. image:: picture.png
174 Inline images can be defined with an "image" directive in a `substitution
177 The URI for the image source file is specified in the directive
178 argument. As with hyperlink targets, the image URI may begin on the
179 same line as the explicit markup start and target name, or it may
180 begin in an indented text block immediately following, with no
181 intervening blank lines. If there are multiple lines in the link
182 block, they are stripped of leading and trailing whitespace and joined
185 Optionally, the image link block may contain a flat field list, the
186 _`image options`. For example::
188 .. image:: picture.jpeg
195 The following options are recognized:
198 Alternate text: a short description of the image, displayed by
199 applications that cannot display images, or spoken by applications
200 for visually impaired users.
202 ``height`` : `length`_
203 The desired height of the image.
204 Used to reserve space or scale the image vertically. When the "scale"
205 option is also specified, they are combined. For example, a height of
206 200px and a scale of 50 is equivalent to a height of 100px with no scale.
208 ``width`` : `length`_ or `percentage`_ of the current line width
209 The width of the image.
210 Used to reserve space or scale the image horizontally. As with "height"
211 above, when the "scale" option is also specified, they are combined.
213 .. _length: restructuredtext.html#length-units
214 .. _percentage: restructuredtext.html#percentage-units
216 ``scale`` : integer percentage (the "%" symbol is optional)
217 The uniform scaling factor of the image. The default is "100 %", i.e.
220 If no "height" or "width" options are specified, the `Python Imaging
221 Library`_ (PIL) may be used to determine them, if it is installed and
222 the image file is available.
224 ``align`` : "top", "middle", "bottom", "left", "center", or "right"
225 The alignment of the image, equivalent to the HTML ``<img>`` tag's
226 "align" attribute. The values "top", "middle", and "bottom"
227 control an image's vertical alignment (relative to the text
228 baseline); they are only useful for inline images (substitutions).
229 The values "left", "center", and "right" control an image's
230 horizontal alignment, allowing the image to float and have the
231 text flow around it. The specific behavior depends upon the
232 browser or rendering software used.
234 ``target`` : text (URI or reference name)
235 Makes the image into a hyperlink reference ("clickable"). The
236 option argument may be a URI (relative or absolute), or a
237 `reference name`_ with underscore suffix (e.g. ```a name`_``).
239 and the common options `:class:`_ and `:name:`_.
241 .. _substitution definition: restructuredtext.html#substitution-definitions
247 :Directive Type: "figure"
248 :Doctree Elements: figure_, image_, caption_, legend_
249 :Directive Arguments: One, required (image URI).
250 :Directive Options: Possible.
251 :Directive Content: Interpreted as the figure caption and an optional
254 A "figure" consists of image_ data (including `image options`_), an optional
255 caption (a single paragraph), and an optional legend (arbitrary body
256 elements). For page-based output media, figures might float to a different
257 position if this helps the page layout.
260 .. figure:: picture.png
262 :alt: map to buried treasure
264 This is the caption of the figure (a simple paragraph).
266 The legend consists of all elements after the caption. In this
267 case, the legend consists of this paragraph and the following
270 +-----------------------+-----------------------+
272 +=======================+=======================+
273 | .. image:: tent.png | Campground |
274 +-----------------------+-----------------------+
275 | .. image:: waves.png | Lake |
276 +-----------------------+-----------------------+
277 | .. image:: peak.png | Mountain |
278 +-----------------------+-----------------------+
280 There must be blank lines before the caption paragraph and before the
281 legend. To specify a legend without a caption, use an empty comment
282 ("..") in place of the caption.
284 The "figure" directive supports all of the options of the "image"
285 directive (see `image options`_ above). These options (except
286 "align") are passed on to the contained image.
288 ``align`` : "left", "center", or "right"
289 The horizontal alignment of the figure, allowing the image to
290 float and have the text flow around it. The specific behavior
291 depends upon the browser or rendering software used.
293 In addition, the following options are recognized:
295 ``figwidth`` : "image", length_, or percentage_ of current line width
296 The width of the figure.
297 Limits the horizontal space used by the figure.
298 A special value of "image" is allowed, in which case the
299 included image's actual width is used (requires the `Python Imaging
300 Library`_). If the image file is not found or the required software is
301 unavailable, this option is ignored.
303 Sets the "width" attribute of the "figure" doctree element.
305 This option does not scale the included image; use the "width"
306 `image`_ option for that. ::
308 +---------------------------+
311 |<------ figwidth --------->|
313 | +---------------------+ |
316 | |<--- width --------->| |
317 | +---------------------+ |
319 |The figure's caption should|
320 |wrap at this width. |
321 +---------------------------+
324 Set a `"classes"`_ attribute value on the figure element. See the
325 class_ directive below.
327 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
337 :Directive Type: "topic"
338 :Doctree Element: topic_
339 :Directive Arguments: 1, required (topic title).
340 :Directive Options: `:class:`_, `:name:`_
341 :Directive Content: Interpreted as the topic body.
343 A topic is like a block quote with a title, or a self-contained
344 section with no subsections. Use the "topic" directive to indicate a
345 self-contained idea that is separate from the flow of the document.
346 Topics may occur anywhere a section or transition may occur. Body
347 elements and topics may not contain nested topics.
349 The directive's sole argument is interpreted as the topic title; the
350 next line must be blank. All subsequent lines make up the topic body,
351 interpreted as body elements. For example::
353 .. topic:: Topic Title
355 Subsequent indented lines comprise
356 the body of the topic, and are
357 interpreted as body elements.
363 :Directive Type: "sidebar"
364 :Doctree Element: sidebar_
365 :Directive Arguments: One, required (sidebar title).
366 :Directive Options: Possible (see below).
367 :Directive Content: Interpreted as the sidebar body.
369 Sidebars are like miniature, parallel documents that occur inside
370 other documents, providing related or reference material. A sidebar
371 is typically offset by a border and "floats" to the side of the page;
372 the document's main text may flow around it. Sidebars can also be
373 likened to super-footnotes; their content is outside of the flow of
374 the document's main text.
376 Sidebars may occur anywhere a section or transition may occur. Body
377 elements (including sidebars) may not contain nested sidebars.
379 The directive's sole argument is interpreted as the sidebar title,
380 which may be followed by a subtitle option (see below); the next line
381 must be blank. All subsequent lines make up the sidebar body,
382 interpreted as body elements. For example::
384 .. sidebar:: Sidebar Title
385 :subtitle: Optional Sidebar Subtitle
387 Subsequent indented lines comprise
388 the body of the sidebar, and are
389 interpreted as body elements.
391 The following options are recognized:
394 The sidebar's subtitle.
396 and the common options `:class:`_ and `:name:`_.
402 .. admonition:: Deprecated
404 The "line-block" directive is deprecated. Use the `line block
407 .. _line block syntax: restructuredtext.html#line-blocks
409 :Directive Type: "line-block"
410 :Doctree Element: line_block_
411 :Directive Arguments: None.
412 :Directive Options: `:class:`_, `:name:`_
413 :Directive Content: Becomes the body of the line block.
415 The "line-block" directive constructs an element where line breaks and
416 initial indentation is significant and inline markup is supported. It
417 is equivalent to a `parsed literal block`_ with different rendering:
418 typically in an ordinary serif typeface instead of a
419 typewriter/monospaced face, and not automatically indented. (Have the
420 line-block directive begin a block quote to get an indented line
421 block.) Line blocks are useful for address blocks and verse (poetry,
422 song lyrics), where the structure of lines is significant. For
423 example, here's a classic::
425 "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by
426 Ewan McTeagle (for Lassie O'Shea):
430 Lend us a couple of bob till Thursday.
431 I'm absolutely skint.
432 But I'm expecting a postal order and I can pay you back
443 :Directive Type: "parsed-literal"
444 :Doctree Element: literal_block_
445 :Directive Arguments: None.
446 :Directive Options: `:class:`_, `:name:`_
447 :Directive Content: Becomes the body of the literal block.
449 Unlike an ordinary literal block, the "parsed-literal" directive
450 constructs a literal block where the text is parsed for inline markup.
451 It is equivalent to a `line block`_ with different rendering:
452 typically in a typewriter/monospaced typeface, like an ordinary
453 literal block. Parsed literal blocks are useful for adding hyperlinks
456 However, care must be taken with the text, because inline markup is
457 recognized and there is no protection from parsing. Backslash-escapes
458 may be necessary to prevent unintended parsing. And because the
459 markup characters are removed by the parser, care must also be taken
460 with vertical alignment. Parsed "ASCII art" is tricky, and extra
461 whitespace may be necessary.
463 For example, all the element names in this content model are links::
467 ( (title_, subtitle_?)?,
469 (docinfo_, transition_?)?,
470 `%structure.model;`_ )
475 :Directive Type: "code"
476 :Doctree Element: literal_block_, `inline elements`_
477 :Directive Arguments: One, optional (formal language).
478 :Directive Options: name, class, number-lines.
479 :Directive Content: Becomes the body of the literal block.
480 :Configuration Setting: syntax_highlight_.
482 (New in Docutils 0.9)
484 The "code" directive constructs a literal block. If the code language is
485 specified, the content is parsed by the Pygments_ syntax highlighter and
486 tokens are stored in nested `inline elements`_ with class arguments
487 according to their syntactic category. The actual highlighting can be
488 customized with a style-sheet (e.g. one `generated by Pygments`__).
490 The parsing can be turned off with the syntax_highlight_ configuration
491 setting and command line option or by specifying the language as `:class:`_
492 option instead of directive argument. This also avoids warnings
493 when Pygments_ is not installed or the language is not in the
494 `supported languages and markup formats`_.
496 __ http://pygments.org/docs/cmdline/#generating-styles
497 .. _Pygments: http://pygments.org/
498 .. _syntax_highlight: ../../user/config.html#syntax-highlight
499 .. _supported languages and markup formats: http://pygments.org/languages/
502 The following options are recognized:
504 ``number-lines`` : [start line number]
505 Precede every line with a line number.
506 The optional argument is the number of the first line (defaut 1).
508 and the common options `:class:`_ and `:name:`_.
511 The content of the following directive ::
519 is parsed and marked up as Python source code.
525 :Directive Type: "math"
526 :Doctree Element: math_block_
527 :Directive Arguments: One, optional: prepended to content.
528 :Directive Options: `:class:`_, `:name:`_
529 :Directive Content: Interpreted as math block(s).
530 Content blocks separated by a blank line are put in
531 separate math-block doctree elements.
532 :Configuration Setting: math_output_
534 (New in Docutils 0.8)
536 The "math" directive inserts block(s) with mathematical content
537 (display formulas, equations) into the document. The input format is
538 *LaTeX math syntax* (see, e.g. the `Short Math Guide`_) with support
539 for Unicode symbols, for example::
543 α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)
545 For inline math, use the `"math" role`_.
547 Support for math may be limited by the output format. If a writer does
548 not support math typesetting, the content is inserted verbatim.
549 For HTML, the output format can be set with the `math_output`_
550 configuration setting (or the corresponding ``--math-output`` command
553 .. _Short Math Guide: ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
554 .. _"math" role: roles.html#math
555 .. _math_output: ../../user/config.html#math-output
560 :Directive Type: "rubric"
561 :Doctree Element: rubric_
562 :Directive Arguments: 1, required (rubric text).
563 :Directive Options: `:class:`_, `:name:`_
564 :Directive Content: None.
568 rubric n. 1. a title, heading, or the like, in a manuscript,
569 book, statute, etc., written or printed in red or otherwise
570 distinguished from the rest of the text. ...
572 -- Random House Webster's College Dictionary, 1991
574 The "rubric" directive inserts a "rubric" element into the document
575 tree. A rubric is like an informal heading that doesn't correspond to
576 the document's structure.
582 :Directive Type: "epigraph"
583 :Doctree Element: block_quote_
584 :Directive Arguments: None.
585 :Directive Options: None.
586 :Directive Content: Interpreted as the body of the block quote.
588 An epigraph is an apposite (suitable, apt, or pertinent) short
589 inscription, often a quotation or poem, at the beginning of a document
592 The "epigraph" directive produces an "epigraph"-class block quote.
593 For example, this input::
597 No matter where you go, there you are.
601 becomes this document tree fragment::
603 <block_quote classes="epigraph">
605 No matter where you go, there you are.
613 :Directive Type: "highlights"
614 :Doctree Element: block_quote_
615 :Directive Arguments: None.
616 :Directive Options: None.
617 :Directive Content: Interpreted as the body of the block quote.
619 Highlights summarize the main points of a document or section, often
620 consisting of a list.
622 The "highlights" directive produces a "highlights"-class block quote.
623 See Epigraph_ above for an analogous example.
629 :Directive Type: "pull-quote"
630 :Doctree Element: block_quote_
631 :Directive Arguments: None.
632 :Directive Options: None.
633 :Directive Content: Interpreted as the body of the block quote.
635 A pull-quote is a small selection of text "pulled out and quoted",
636 typically in a larger typeface. Pull-quotes are used to attract
637 attention, especially in long articles.
639 The "pull-quote" directive produces a "pull-quote"-class block quote.
640 See Epigraph_ above for an analogous example.
646 :Directive Type: "compound"
647 :Doctree Element: compound_
648 :Directive Arguments: None.
649 :Directive Options: `:class:`_, `:name:`_
650 :Directive Content: Interpreted as body elements.
652 (New in Docutils 0.3.6)
654 The "compound" directive is used to create a compound paragraph, which
655 is a single logical paragraph containing multiple physical body
656 elements such as simple paragraphs, literal blocks, tables, lists,
657 etc., instead of directly containing text and inline elements. For
662 The 'rm' command is very dangerous. If you are logged
663 in as root and enter ::
668 you will erase the entire contents of your file system.
670 In the example above, a literal block is "embedded" within a sentence
671 that begins in one physical paragraph and ends in another.
675 The "compound" directive is *not* a generic block-level container
676 like HTML's ``<div>`` element. Do not use it only to group a
677 sequence of elements, or you may get unexpected results.
679 If you need a generic block-level container, please use the
680 container_ directive, described below.
682 Compound paragraphs are typically rendered as multiple distinct text
683 blocks, with the possibility of variations to emphasize their logical
686 * If paragraphs are rendered with a first-line indent, only the first
687 physical paragraph of a compound paragraph should have that indent
688 -- second and further physical paragraphs should omit the indents;
689 * vertical spacing between physical elements may be reduced;
696 :Directive Type: "container"
697 :Doctree Element: container_
698 :Directive Arguments: One or more, optional (class names).
699 :Directive Options: `:name:`_
700 :Directive Content: Interpreted as body elements.
702 (New in Docutils 0.3.10)
704 The "container" directive surrounds its contents (arbitrary body
705 elements) with a generic block-level "container" element. Combined
706 with the optional "classes_" attribute argument(s), this is an
707 extension mechanism for users & applications. For example::
709 .. container:: custom
711 This paragraph might be rendered in a custom way.
713 Parsing the above results in the following pseudo-XML::
715 <container classes="custom">
717 This paragraph might be rendered in a custom way.
719 The "container" directive is the equivalent of HTML's ``<div>``
720 element. It may be used to group a sequence of elements for user- or
721 application-specific purposes.
729 Formal tables need more structure than the reStructuredText syntax
730 supplies. Tables may be given titles with the table_ directive.
731 Sometimes reStructuredText tables are inconvenient to write, or table
732 data in a standard format is readily available. The csv-table_
733 directive supports CSV data.
739 :Directive Type: "table"
740 :Doctree Element: table_
741 :Directive Arguments: 1, optional (table title).
742 :Directive Options: `:class:`_, `:name:`_
743 :Directive Content: A normal reStructuredText table.
745 (New in Docutils 0.3.1)
747 The "table" directive is used to create a titled table, to associate a
750 .. table:: Truth table for "not"
765 :Directive Type: "csv-table"
766 :Doctree Element: table_
767 :Directive Arguments: 1, optional (table title).
768 :Directive Options: Possible (see below).
769 :Directive Content: A CSV (comma-separated values) table.
773 The "csv-table" directive's ":file:" and ":url:" options represent
774 a potential security holes. They can be disabled with the
775 "file_insertion_enabled_" runtime setting.
777 (New in Docutils 0.3.4)
779 The "csv-table" directive is used to create a table from CSV
780 (comma-separated values) data. CSV is a common data format generated
781 by spreadsheet applications and commercial databases. The data may be
782 internal (an integral part of the document) or external (a separate
787 .. csv-table:: Frozen Delights!
788 :header: "Treat", "Quantity", "Description"
791 "Albatross", 2.99, "On a stick!"
792 "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
793 crunchy, now would it?"
794 "Gannet Ripple", 1.99, "On a stick!"
796 Block markup and inline markup within cells is supported. Line ends
797 are recognized within cells.
801 * Whitespace delimiters are supported only for external CSV files.
803 * There is no support for checking that the number of columns in each
804 row is the same. However, this directive supports CSV generators
805 that do not insert "empty" entries at the end of short rows, by
806 automatically adding empty entries.
808 .. Add "strict" option to verify input?
810 The following options are recognized:
812 ``widths`` : integer [, integer...]
813 A comma- or space-separated list of relative column widths. The
814 default is equal-width columns (100%/#columns).
816 ``header-rows`` : integer
817 The number of rows of CSV data to use in the table header.
820 ``stub-columns`` : integer
821 The number of table columns to use as stubs (row titles, on the
822 left). Defaults to 0.
824 ``header`` : CSV data
825 Supplemental data for the table header, added independently of and
826 before any ``header-rows`` from the main CSV data. Must use the
827 same CSV format as the main CSV data.
829 ``file`` : string (newlines removed)
830 The local filesystem path to a CSV data file.
832 ``url`` : string (whitespace removed)
833 An Internet URL reference to a CSV data file.
835 ``encoding`` : name of text encoding
836 The text encoding of the external CSV data (file or URL).
837 Defaults to the document's encoding (if specified).
839 ``delim`` : char | "tab" | "space"
840 A one-character string used to separate fields. Defaults to ``,``
841 (comma). May be specified as a Unicode code point; see the
842 unicode_ directive for syntax details.
845 A one-character string used to quote elements containing the
846 delimiter or which start with the quote character. Defaults to
847 ``"`` (quote). May be specified as a Unicode code point; see the
848 unicode_ directive for syntax details.
851 Treat whitespace immediately following the delimiter as
852 significant. The default is to ignore such whitespace.
855 A one-character string used to escape the delimiter or quote
856 characters. May be specified as a Unicode code point; see the
857 unicode_ directive for syntax details. Used when the delimiter is
858 used in an unquoted field, or when quote characters are used
859 within a field. The default is to double-up the character,
860 e.g. "He said, ""Hi!"""
862 .. Add another possible value, "double", to explicitly indicate
865 and the common options `:class:`_ and `:name:`_.
871 :Directive Type: "list-table"
872 :Doctree Element: table_
873 :Directive Arguments: 1, optional (table title).
874 :Directive Options: Possible (see below).
875 :Directive Content: A uniform two-level bullet list.
877 (New in Docutils 0.3.8. This is an initial implementation; `further
878 ideas`__ may be implemented in the future.)
880 __ ../../dev/rst/alternatives.html#list-driven-tables
882 The "list-table" directive is used to create a table from data in a
883 uniform two-level bullet list. "Uniform" means that each sublist
884 (second-level list) must contain the same number of list items.
888 .. list-table:: Frozen Delights!
900 - If we took the bones out, it wouldn't be
901 crunchy, now would it?
906 The following options are recognized:
908 ``widths`` : integer [integer...]
909 A comma- or space-separated list of relative column widths. The
910 default is equal-width columns (100%/#columns).
912 ``header-rows`` : integer
913 The number of rows of list data to use in the table header.
916 ``stub-columns`` : integer
917 The number of table columns to use as stubs (row titles, on the
918 left). Defaults to 0.
920 and the common options `:class:`_ and `:name:`_.
932 :Directive Type: "contents"
933 :Doctree Elements: pending_, topic_
934 :Directive Arguments: One, optional: title.
935 :Directive Options: Possible.
936 :Directive Content: None.
938 The "contents" directive generates a table of contents (TOC) in a
939 topic_. Topics, and therefore tables of contents, may occur anywhere
940 a section or transition may occur. Body elements and topics may not
941 contain tables of contents.
943 Here's the directive in its simplest form::
947 Language-dependent boilerplate text will be used for the title. The
948 English default title text is "Contents".
950 An explicit title may be specified::
952 .. contents:: Table of Contents
954 The title may span lines, although it is not recommended::
956 .. contents:: Here's a very long Table of
959 Options may be specified for the directive, using a field list::
961 .. contents:: Table of Contents
964 If the default title is to be used, the options field list may begin
965 on the same line as the directive marker::
967 .. contents:: :depth: 2
969 The following options are recognized:
972 The number of section levels that are collected in the table of
973 contents. The default is unlimited depth.
975 ``local`` : flag (empty)
976 Generate a local table of contents. Entries will only include
977 subsections of the section in which the directive is given. If no
978 explicit title is given, the table of contents will not be titled.
980 ``backlinks`` : "entry" or "top" or "none"
981 Generate links from section headers back to the table of contents
982 entries, the table of contents itself, or generate no backlinks.
985 Set a `"classes"`_ attribute value on the topic element. See the
986 class_ directive below.
990 .. _section-autonumbering:
992 Automatic Section Numbering
993 ===========================
995 :Directive Type: "sectnum" or "section-autonumbering" (synonyms)
996 :Doctree Elements: pending_, generated_
997 :Directive Arguments: None.
998 :Directive Options: Possible.
999 :Directive Content: None.
1000 :Configuration Setting: sectnum_xform_
1002 The "sectnum" (or "section-autonumbering") directive automatically numbers
1003 sections and subsections in a document (if not disabled by the
1004 ``--no-section-numbering`` command line option or the `sectnum_xform`_
1005 configuration setting).
1007 Section numbers are of the "multiple enumeration" form, where each
1008 level has a number, separated by periods. For example, the title of section
1009 1, subsection 2, subsubsection 3 would have "1.2.3" prefixed.
1011 The "sectnum" directive does its work in two passes: the initial parse
1012 and a transform. During the initial parse, a "pending" element is
1013 generated which acts as a placeholder, storing any options internally.
1014 At a later stage in the processing, the "pending" element triggers a
1015 transform, which adds section numbers to titles. Section numbers are
1016 enclosed in a "generated" element, and titles have their "auto"
1017 attribute set to "1".
1019 The following options are recognized:
1022 The number of section levels that are numbered by this directive.
1023 The default is unlimited depth.
1026 An arbitrary string that is prefixed to the automatically
1027 generated section numbers. It may be something like "3.2.", which
1028 will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that
1029 any separating punctuation (in the example, a period, ".") must be
1030 explicitly provided. The default is no prefix.
1033 An arbitrary string that is appended to the automatically
1034 generated section numbers. The default is no suffix.
1037 The value that will be used for the first section number.
1038 Combined with ``prefix``, this may be used to force the right
1039 numbering for a document split over several source files. The
1042 .. _sectnum_xform: ../../user/config.html#sectnum-xform
1048 Document Header & Footer
1049 ========================
1051 :Directive Types: "header" and "footer"
1052 :Doctree Elements: decoration_, header, footer
1053 :Directive Arguments: None.
1054 :Directive Options: None.
1055 :Directive Content: Interpreted as body elements.
1057 (New in Docutils 0.3.8)
1059 The "header" and "footer" directives create document decorations,
1060 useful for page navigation, notes, time/datestamp, etc. For example::
1062 .. header:: This space for rent.
1064 This will add a paragraph to the document header, which will appear at
1065 the top of the generated web page or at the top of every printed page.
1067 These directives may be used multiple times, cumulatively. There is
1068 currently support for only one header and footer.
1072 While it is possible to use the "header" and "footer" directives to
1073 create navigational elements for web pages, you should be aware
1074 that Docutils is meant to be used for *document* processing, and
1075 that a navigation bar is not typically part of a document.
1077 Thus, you may soon find Docutils' abilities to be insufficient for
1078 these purposes. At that time, you should consider using a
1079 templating system (like ht2html_) rather than the "header" and
1080 "footer" directives.
1082 .. _ht2html: http://ht2html.sourceforge.net/
1084 In addition to the use of these directives to populate header and
1085 footer content, content may also be added automatically by the
1086 processing system. For example, if certain runtime settings are
1087 enabled, the document footer is populated with processing information
1088 such as a datestamp, a link to `the Docutils website`_, etc.
1090 .. _the Docutils website: http://docutils.sourceforge.net
1102 :Directive Type: "target-notes"
1103 :Doctree Elements: pending_, footnote_, footnote_reference_
1104 :Directive Arguments: None.
1105 :Directive Options: `:class:`_, `:name:`_
1106 :Directive Options: Possible.
1107 :Directive Content: None.
1109 The "target-notes" directive creates a footnote for each external
1110 target in the text, and corresponding footnote references after each
1111 reference. For every explicit target (of the form, ``.. _target name:
1112 URL``) in the text, a footnote will be generated containing the
1113 visible URL as content.
1119 **NOT IMPLEMENTED YET**
1121 :Directive Type: "footnotes"
1122 :Doctree Elements: pending_, topic_
1123 :Directive Arguments: None?
1124 :Directive Options: Possible?
1125 :Directive Content: None.
1133 **NOT IMPLEMENTED YET**
1135 :Directive Type: "citations"
1136 :Doctree Elements: pending_, topic_
1137 :Directive Arguments: None?
1138 :Directive Options: Possible?
1139 :Directive Content: None.
1151 :Directive Type: "meta"
1152 :Doctree Element: meta (non-standard)
1153 :Directive Arguments: None.
1154 :Directive Options: None.
1155 :Directive Content: Must contain a flat field list.
1157 The "meta" directive is used to specify HTML metadata stored in HTML
1158 META tags. "Metadata" is data about data, in this case data about web
1159 pages. Metadata is used to describe and classify web pages in the
1160 World Wide Web, in a form that is easy for search engines to extract
1163 Within the directive block, a flat field list provides the syntax for
1164 metadata. The field name becomes the contents of the "name" attribute
1165 of the META tag, and the field body (interpreted as a single string
1166 without inline markup) becomes the contents of the "content"
1167 attribute. For example::
1170 :description: The reStructuredText plaintext markup language
1171 :keywords: plaintext, markup language
1173 This would be converted to the following HTML::
1175 <meta name="description"
1176 content="The reStructuredText plaintext markup language">
1177 <meta name="keywords" content="plaintext, markup language">
1179 Support for other META attributes ("http-equiv", "scheme", "lang",
1180 "dir") are provided through field arguments, which must be of the form
1184 :description lang=en: An amusing story
1185 :description lang=fr: Une histoire amusante
1187 And their HTML equivalents::
1189 <meta name="description" lang="en" content="An amusing story">
1190 <meta name="description" lang="fr" content="Une histoire amusante">
1192 Some META tags use an "http-equiv" attribute instead of the "name"
1193 attribute. To specify "http-equiv" META tags, simply omit the name::
1196 :http-equiv=Content-Type: text/html; charset=ISO-8859-1
1200 <meta http-equiv="Content-Type"
1201 content="text/html; charset=ISO-8859-1">
1207 **NOT IMPLEMENTED YET**
1209 Non-standard element: imagemap.
1212 -----------------------------------------
1213 Directives for Substitution Definitions
1214 -----------------------------------------
1216 The directives in this section may only be used in substitution
1217 definitions. They may not be used directly, in standalone context.
1218 The `image`_ directive may be used both in substitution definitions
1219 and in the standalone context.
1227 :Directive Type: "replace"
1228 :Doctree Element: Text & `inline elements`_
1229 :Directive Arguments: None.
1230 :Directive Options: None.
1231 :Directive Content: A single paragraph; may contain inline markup.
1233 The "replace" directive is used to indicate replacement text for a
1234 substitution reference. It may be used within substitution
1235 definitions only. For example, this directive can be used to expand
1238 .. |reST| replace:: reStructuredText
1240 Yes, |reST| is a long word, so I can't blame anyone for wanting to
1243 As reStructuredText doesn't support nested inline markup, the only way
1244 to create a reference with styled text is to use substitutions with
1245 the "replace" directive::
1247 I recommend you try |Python|_.
1249 .. |Python| replace:: Python, *the* best language around
1250 .. _Python: http://www.python.org/
1255 Unicode Character Codes
1256 =======================
1258 :Directive Type: "unicode"
1259 :Doctree Element: Text
1260 :Directive Arguments: One or more, required (Unicode character codes,
1261 optional text, and comments).
1262 :Directive Options: Possible.
1263 :Directive Content: None.
1265 The "unicode" directive converts Unicode character codes (numerical
1266 values) to characters, and may be used in substitution definitions
1269 The arguments, separated by spaces, can be:
1271 * **character codes** as
1273 - decimal numbers or
1275 - hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``,
1276 ``u``, or ``\u`` or as XML-style hexadecimal character entities,
1279 * **text**, which is used as-is.
1281 Text following " .. " is a comment and is ignored. The spaces between
1282 the arguments are ignored and thus do not appear in the output.
1283 Hexadecimal codes are case-insensitive.
1285 For example, the following text::
1287 Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
1288 all rights reserved.
1290 .. |copy| unicode:: 0xA9 .. copyright sign
1291 .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
1292 .. with trademark sign
1293 .. |---| unicode:: U+02014 .. em dash
1298 Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
1299 all rights reserved.
1301 .. |copy| unicode:: 0xA9 .. copyright sign
1302 .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
1303 .. with trademark sign
1304 .. |---| unicode:: U+02014 .. em dash
1307 The following options are recognized:
1310 Whitespace to the left of the substitution reference is removed.
1313 Whitespace to the right of the substitution reference is removed.
1316 Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides
1317 of the substitution reference is removed.
1323 :Directive Type: "date"
1324 :Doctree Element: Text
1325 :Directive Arguments: One, optional (date format).
1326 :Directive Options: None.
1327 :Directive Content: None.
1329 The "date" directive generates the current local date and inserts it
1330 into the document as text. This directive may be used in substitution
1333 The optional directive content is interpreted as the desired date
1334 format, using the same codes as Python's time.strftime function. The
1335 default format is "%Y-%m-%d" (ISO 8601 date), but time fields can also
1339 .. |time| date:: %H:%M
1341 Today's date is |date|.
1343 This document was generated on |date| at |time|.
1352 Including an External Document Fragment
1353 =======================================
1355 :Directive Type: "include"
1356 :Doctree Elements: Depend on data being included
1357 (literal_block_ with ``code`` or ``literal`` option).
1358 :Directive Arguments: One, required (path to the file to include).
1359 :Directive Options: Possible.
1360 :Directive Content: None.
1361 :Configuration Setting: file_insertion_enabled_
1365 The "include" directive represents a potential security hole. It
1366 can be disabled with the "file_insertion_enabled_" runtime setting.
1368 .. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled
1370 The "include" directive reads a text file. The directive argument is
1371 the path to the file to be included, relative to the document
1372 containing the directive. Unless the options ``literal`` or ``code``
1373 are given, the file is parsed in the current document's context at the
1374 point of the directive. For example::
1376 This first example will be parsed at the document level, and can
1377 thus contain any construct, including section headers.
1379 .. include:: inclusion.txt
1381 Back in the main document.
1383 This second example will be parsed in a block quote context.
1384 Therefore it may only contain body elements. It may not
1385 contain section headers.
1387 .. include:: inclusion.txt
1389 If an included document fragment contains section structure, the title
1390 adornments must match those of the master document.
1392 Standard data files intended for inclusion in reStructuredText
1393 documents are distributed with the Docutils source code, located in
1394 the "docutils" package in the ``docutils/parsers/rst/include``
1395 directory. To access these files, use the special syntax for standard
1396 "include" data files, angle brackets around the file name::
1398 .. include:: <isonum.txt>
1400 The current set of standard "include" data files consists of sets of
1401 substitution definitions. See `reStructuredText Standard Definition
1402 Files`__ for details.
1406 The following options are recognized:
1408 ``start-line`` : integer
1409 Only the content starting from this line will be included.
1410 (As usual in Python, the first line has index 0 and negative values
1411 count from the end.)
1413 ``end-line`` : integer
1414 Only the content up to (but excluding) this line will be included.
1416 ``start-after`` : text to find in the external data file
1417 Only the content after the first occurrence of the specified text
1420 ``end-before`` : text to find in the external data file
1421 Only the content before the first occurrence of the specified text
1422 (but after any ``after`` text) will be included.
1424 ``literal`` : flag (empty)
1425 The entire included text is inserted into the document as a single
1428 ``code`` : formal language (optional)
1429 The argument and the content of the included file are passed to
1430 the code_ directive (useful for program listings).
1431 (New in Docutils 0.9)
1433 ``number-lines`` : [start line number]
1434 Precede every code line with a line number.
1435 The optional argument is the number of the first line (defaut 1).
1436 Works only with ``code`` or ``literal``.
1437 (New in Docutils 0.9)
1439 ``encoding`` : name of text encoding
1440 The text encoding of the external data file. Defaults to the
1441 document's input_encoding_.
1443 .. _input_encoding: ../../user/config.html#input-encoding
1445 ``tab-width`` : integer
1446 Number of spaces for hard tab expansion.
1447 A negative value prevents expansion of hard tabs. Defaults to the
1448 tab_width_ configuration setting.
1450 .. _tab_width: ../../user/config.html#tab-width
1453 With ``code`` or ``literal`` the common options `:class:`_ and
1454 `:name:`_ are recognized as well.
1456 Combining ``start/end-line`` and ``start-after/end-before`` is possible. The
1457 text markers will be searched in the specified lines (further limiting the
1462 Raw Data Pass-Through
1463 =====================
1465 :Directive Type: "raw"
1466 :Doctree Element: raw_
1467 :Directive Arguments: One or more, required (output format types).
1468 :Directive Options: Possible.
1469 :Directive Content: Stored verbatim, uninterpreted. None (empty) if a
1470 "file" or "url" option given.
1471 :Configuration Setting: raw_enabled_
1475 The "raw" directive represents a potential security hole. It can
1476 be disabled with the "raw_enabled_" or "file_insertion_enabled_"
1479 .. _raw_enabled: ../../user/config.html#raw-enabled
1483 The "raw" directive is a stop-gap measure allowing the author to
1484 bypass reStructuredText's markup. It is a "power-user" feature
1485 that should not be overused or abused. The use of "raw" ties
1486 documents to specific output formats and makes them less portable.
1488 If you often need to use the "raw" directive or a "raw"-derived
1489 interpreted text role, that is a sign either of overuse/abuse or
1490 that functionality may be missing from reStructuredText. Please
1491 describe your situation in a message to the Docutils-users_ mailing
1494 .. _Docutils-users: ../../user/mailing-lists.html#docutils-users
1496 The "raw" directive indicates non-reStructuredText data that is to be
1497 passed untouched to the Writer. The names of the output formats are
1498 given in the directive arguments. The interpretation of the raw data
1499 is up to the Writer. A Writer may ignore any raw output not matching
1502 For example, the following input would be passed untouched by an HTML
1507 <hr width=50 size=10>
1509 A LaTeX Writer could insert the following raw content into its
1514 \setlength{\parindent}{0pt}
1516 Raw data can also be read from an external file, specified in a
1517 directive option. In this case, the content block must be empty. For
1521 :file: inclusion.html
1523 Inline equivalents of the "raw" directive can be defined via
1524 `custom interpreted text roles`_ derived from the `"raw" role`_.
1526 The following options are recognized:
1528 ``file`` : string (newlines removed)
1529 The local filesystem path of a raw data file to be included.
1531 ``url`` : string (whitespace removed)
1532 An Internet URL reference to a raw data file to be included.
1534 ``encoding`` : name of text encoding
1535 The text encoding of the external raw data (file or URL).
1536 Defaults to the document's encoding (if specified).
1538 .. _"raw" role: roles.html#raw
1546 :Directive Type: "class"
1547 :Doctree Element: pending_
1548 :Directive Arguments: One or more, required (class names / attribute
1550 :Directive Options: None.
1551 :Directive Content: Optional. If present, it is interpreted as body
1554 The "class" directive sets the `"classes"`_ attribute value on its content
1555 or on the first immediately following non-comment element [#]_. For
1556 details of the "classes" attribute, see `its entry`__ in `The Docutils
1559 The directive argument consists of one or more space-separated class
1560 names. The names are transformed to conform to the regular expression
1561 ``[a-z](-?[a-z0-9]+)*`` by converting
1563 * alphabetic characters to lowercase,
1564 * accented characters to the base character,
1565 * non-alphanumeric characters to hyphens,
1566 * consecutive hyphens into one hyphen.
1568 For example "Rot-Gelb.Blau Grün:+2008" becomes "rot-gelb-blau grun-2008".
1569 (For the rationale_, see below.)
1571 __ ../doctree.html#classes
1577 This is a "special" paragraph.
1579 .. class:: exceptional remarkable
1581 An Exceptional Section
1582 ======================
1584 This is an ordinary paragraph.
1592 The text above is parsed and transformed into this doctree fragment::
1594 <paragraph classes="special">
1595 This is a "special" paragraph.
1596 <section classes="exceptional remarkable">
1598 An Exceptional Section
1600 This is an ordinary paragraph.
1601 <paragraph classes="multiple">
1603 <paragraph classes="multiple">
1606 .. [#] To set a "classes" attribute value on a block quote, the
1607 "class" directive must be followed by an empty comment::
1609 .. class:: highlights
1614 Without the empty comment, the indented text would be interpreted as the
1615 "class" directive's content, and the classes would be applied to each
1616 element (paragraph, in this case) individually, instead of to the block
1621 .. topic:: Rationale for "classes" Attribute Value Conversion
1624 Docutils identifiers are converted to conform to the regular
1625 expression ``[a-z](-?[a-z0-9]+)*``. For HTML + CSS compatibility,
1626 identifiers (the "classes" and "id" attributes) should have no
1627 underscores, colons, or periods. Hyphens may be used.
1629 - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens:
1631 ID and NAME tokens must begin with a letter ([A-Za-z]) and
1632 may be followed by any number of letters, digits ([0-9]),
1633 hyphens ("-"), underscores ("_"), colons (":"), and periods
1636 - The `CSS1 spec`_ defines identifiers based on the "name" token
1637 ("flex" tokenizer notation below; "latin1" and "escape" 8-bit
1638 characters have been replaced with XML entities)::
1640 unicode \\[0-9a-f]{1,4}
1641 latin1 [¡-ÿ]
1642 escape {unicode}|\\[ -~¡-ÿ]
1643 nmchar [-A-Za-z0-9]|{latin1}|{escape}
1646 The CSS rule does not include underscores ("_"), colons (":"), or
1647 periods ("."), therefore "classes" and "id" attributes should not
1648 contain these characters. Combined with HTML's requirements (the
1649 first character must be a letter; no "unicode", "latin1", or
1650 "escape" characters), this results in the regular expression
1651 ``[A-Za-z][-A-Za-z0-9]*``. Docutils adds a normalisation by
1652 downcasing and merge of consecutive hyphens.
1654 .. _HTML 4.01 spec: http://www.w3.org/TR/html401/
1655 .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1
1660 Custom Interpreted Text Roles
1661 =============================
1663 :Directive Type: "role"
1664 :Doctree Element: None; affects subsequent parsing.
1665 :Directive Arguments: Two; one required (new role name), one optional
1666 (base role name, in parentheses).
1667 :Directive Options: Possible (depends on base role).
1668 :Directive Content: depends on base role.
1670 (New in Docutils 0.3.2)
1672 The "role" directive dynamically creates a custom interpreted text
1673 role and registers it with the parser. This means that after
1674 declaring a role like this::
1678 the document may use the new "custom" role::
1680 An example of using :custom:`interpreted text`
1682 This will be parsed into the following document tree fragment::
1686 <inline classes="custom">
1689 The role must be declared in a document before it can be used.
1691 The new role may be based on an existing role, specified as a second
1692 argument in parentheses (whitespace optional)::
1694 .. role:: custom(emphasis)
1698 The parsed result is as follows::
1701 <emphasis classes="custom">
1704 A special case is the `"raw" role`_: derived roles enable
1705 inline `raw data pass-through`_, e.g.::
1707 .. role:: raw-role(raw)
1710 :raw-role:`raw text`
1712 If no base role is explicitly specified, a generic custom role is
1713 automatically used. Subsequent interpreted text will produce an
1714 "inline" element with a `"classes"`_ attribute, as in the first example
1717 With most roles, the ":class:" option can be used to set a "classes"
1718 attribute that is different from the role name. For example::
1723 :custom:`interpreted text`
1725 This is the parsed result::
1728 <inline classes="special">
1733 The following option is recognized by the "role" directive for most
1737 Set the `"classes"`_ attribute value on the element produced
1738 (``inline``, or element associated with a base class) when the
1739 custom interpreted text role is used. If no directive options are
1740 specified, a "class" option with the directive argument (role
1741 name) as the value is implied. See the class_ directive above.
1743 Specific base roles may support other options and/or directive
1744 content. See the `reStructuredText Interpreted Text Roles`_ document
1747 .. _reStructuredText Interpreted Text Roles: roles.html
1752 Setting the Default Interpreted Text Role
1753 =========================================
1755 :Directive Type: "default-role"
1756 :Doctree Element: None; affects subsequent parsing.
1757 :Directive Arguments: One, optional (new default role name).
1758 :Directive Options: None.
1759 :Directive Content: None.
1761 (New in Docutils 0.3.10)
1763 The "default-role" directive sets the default interpreted text role,
1764 the role that is used for interpreted text without an explicit role.
1765 For example, after setting the default role like this::
1767 .. default-role:: subscript
1769 any subsequent use of implicit-role interpreted text in the document
1770 will use the "subscript" role::
1772 An example of a `default` role.
1774 This will be parsed into the following document tree fragment::
1782 Custom roles may be used (see the "role_" directive above), but it
1783 must have been declared in a document before it can be set as the
1784 default role. See the `reStructuredText Interpreted Text Roles`_
1785 document for details of built-in roles.
1787 The directive may be used without an argument to restore the initial
1788 default interpreted text role, which is application-dependent. The
1789 initial default interpreted text role of the standard reStructuredText
1790 parser is "title-reference".
1793 Metadata Document Title
1794 =======================
1796 :Directive Type: "title"
1797 :Doctree Element: None.
1798 :Directive Arguments: 1, required (the title text).
1799 :Directive Options: None.
1800 :Directive Content: None.
1802 The "title" directive specifies the document title as metadata, which
1803 does not become part of the document body. It overrides a
1804 document-supplied title. For example, in HTML output the metadata
1805 document title appears in the title bar of the browser window.
1808 Restructuredtext-Test-Directive
1809 ===============================
1811 :Directive Type: "restructuredtext-test-directive"
1812 :Doctree Element: system_warning
1813 :Directive Arguments: None.
1814 :Directive Options: None.
1815 :Directive Content: Interpreted as a literal block.
1817 This directive is provided for test purposes only. (Nobody is
1818 expected to type in a name *that* long!) It is converted into a
1819 level-1 (info) system message showing the directive data, possibly
1820 followed by a literal block containing the rest of the directive
1827 Most of the directives that generate doctree elements support the following
1831 Set a `"classes"`_ attribute value on the doctree element generated by
1832 the directive. See also the class_ directive.
1835 Add `text` to the `"names"`_ attribute of the doctree element generated
1836 by the directive. This allows `hyperlink references`_ to the element
1837 using `text` as `reference name`_.
1839 Specifying the `name` option of a directive, e.g., ::
1844 is a concise syntax alternative to preceding it with a `hyperlink
1851 New in Docutils 0.8.
1854 .. _reference name: restructuredtext.html#reference-names
1855 .. _hyperlink target: restructuredtext.html#hyperlink-targets
1856 .. _hyperlink references: restructuredtext.html#hyperlink-references
1857 .. _"classes": ../doctree.html#classes
1858 .. _"names": ../doctree.html#names
1859 .. _admonition: ../doctree.html#admonition
1860 .. _block_quote: ../doctree.html#block-quote
1861 .. _caption: ../doctree.html#caption
1862 .. _compound: ../doctree.html#compound
1863 .. _container: ../doctree.html#container
1864 .. _decoration: ../doctree.html#decoration
1865 .. _figure: ../doctree.html#figure
1866 .. _footnote: ../doctree.html#footnote
1867 .. _footnote_reference: ../doctree.html#footnote-reference
1868 .. _generated: ../doctree.html#generated
1869 .. _image: ../doctree.html#image
1870 .. _inline elements: ../doctree.html#inline-elements
1871 .. _literal_block: ../doctree.html#literal-block
1872 .. _legend: ../doctree.html#legend
1873 .. _line_block: ../doctree.html#line-block
1874 .. _math_block: ../doctree.html#math-block
1875 .. _pending: ../doctree.html#pending
1876 .. _raw: ../doctree.html#raw
1877 .. _rubric: ../doctree.html#rubric
1878 .. _sidebar: ../doctree.html#sidebar
1879 .. _table: ../doctree.html#table
1880 .. _title: ../doctree.html#title
1881 .. _topic: ../doctree.html#topic
1888 indent-tabs-mode: nil
1889 sentence-end-double-space: t