diff options
Diffstat (limited to 'docutils/docs/ref/rst/directives.txt')
| -rw-r--r-- | docutils/docs/ref/rst/directives.txt | 360 |
1 files changed, 0 insertions, 360 deletions
diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt deleted file mode 100644 index 8012ee9ed..000000000 --- a/docutils/docs/ref/rst/directives.txt +++ /dev/null @@ -1,360 +0,0 @@ -============================= - reStructuredText Directives -============================= -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ - -This document describes the directives implemented in the reference -reStructuredText parser. - - -.. contents:: - - -------------- - Admonitions -------------- - -DTD elements: attention, caution, danger, error, hint, important, -note, tip, warning. - -Directive block: directive data and all following indented text -are interpreted as body elements. - -Admonitions are specially marked "topics" that can appear anywhere an -ordinary body element can. They contain arbitrary body elements. -Typically, an admonition is rendered as an offset block in a document, -sometimes outlined or shaded, with a title matching the admonition -type. For example:: - - .. DANGER:: - Beware killer rabbits! - -This directive might be rendered something like this:: - - +------------------------+ - | !DANGER! | - | | - | Beware killer rabbits! | - +------------------------+ - -The following admonition directives have been implemented: - -- attention -- caution -- danger -- error -- hint -- important -- note -- tip -- warning - -Any text immediately following the directive indicator (on the same -line and/or indented on following lines) is interpreted as a directive -block and is parsed for normal body elements. For example, the -following "note" admonition directive contains one paragraph and a -bullet list consisting of two list items:: - - .. note:: This is a note admonition. - This is the second line of the first paragraph. - - - The note contains all indented body elements - following. - - It includes this bullet list. - - --------- - Images --------- - -There are two image directives: "image" and "figure". - - -Image -===== - -DTD element: image. - -Directive block: directive data and following indented lines (up to -the first blank line) are interpreted as image URI and optional -attributes. - -An "image" is a simple picture:: - - .. image:: picture.png - -The URI for the image source file is specified in the directive data. -As with hyperlink targets, the image URI may begin on the same line as -the explicit markup start and target name, or it may begin in an -indented text block immediately following, with no intervening blank -lines. If there are multiple lines in the link block, they are -stripped of leading and trailing whitespace and joined together. - -Optionally, the image link block may end with a flat field list, the -_`image attributes`. For example:: - - .. image:: picture.png - :height: 100 - :width: 200 - :scale: 50 - :alt: alternate text - -The following attributes are recognized: - -``alt`` : text - Alternate text: a short description of the image, displayed by - applications that cannot display images, or spoken by applications - for visually impaired users. -``height`` : integer - The height of the image in pixels, used to reserve space or scale - the image vertically. -``width`` : integer - The width of the image in pixels, used to reserve space or scale - the image horizontally. -``scale`` : integer - The uniform scaling factor of the image, a percentage (but no "%" - symbol is required or allowed). "100" means full-size. - - -Figure -====== - -DTD elements: figure, image, caption, legend. - -Directive block: directive data and all following indented text are -interpreted as an image URI, optional attributes, a caption, and an -optional legend. - -A "figure" consists of image_ data (optionally including `image -attributes`_), an optional caption (a single paragraph), and an -optional legend (arbitrary body elements):: - - .. figure:: picture.png - :scale: 50 - :alt: map to buried treasure - - This is the caption of the figure (a simple paragraph). - - The legend consists of all elements after the caption. In this - case, the legend consists of this paragraph and the following - table: - - +-----------------------+-----------------------+ - | Symbol | Meaning | - +=======================+=======================+ - | .. image:: tent.png | Campground | - +-----------------------+-----------------------+ - | .. image:: waves.png | Lake | - +-----------------------+-----------------------+ - | .. image:: peak.png | Mountain | - +-----------------------+-----------------------+ - -There must be a blank line before the caption paragraph and before the -legend. To specify a legend without a caption, use an empty comment -("..") in place of the caption. - - ----------------- - Document Parts ----------------- - -Table of Contents -================= - -DTD elements: pending, topic. - -Directive block: directive data and following indented lines (up to -the first blank line) are interpreted as the topic title and optional -attributes. - -The "contents" directive inserts a table of contents (TOC) in two -passes: initial parse and transform. During the initial parse, a -"pending" element is generated which acts as a placeholder, storing -the TOC title and any attributes internally. At a later stage in the -processing, the "pending" element is replaced by a "topic" element, a -title and the table of contents proper. - -The directive in its simplest form:: - - .. contents:: - -Language-dependent boilerplate text will be used for the title. The -English default title text is "Contents". - -An explicit title, may be specified:: - - .. contents:: Table of Contents - -The title may span lines, although it is not recommended:: - - .. contents:: Here's a very long Table of - Contents title - -Attributes may be specified for the directive, using a field list:: - - .. contents:: Table of Contents - :depth: 2 - -If the default title is to be used, the attribute field list may begin -on the same line as the directive marker:: - - .. contents:: :depth: 2 - -The following attributes are recognized: - -``depth`` : integer - The number of section levels that are collected in the table of - contents. -``local`` : empty - Generate a local table of contents. Entries will only include - subsections of the section in which the directive is given. If no - explicit title is given, the table of contents will not be titled. - - -Footnotes -========= - -DTD elements: pending, topic. - -@@@ - - -Citations -========= - -DTD elements: pending, topic. - -@@@ - - -Topic -===== - -DTD element: topic. - -@@@ - - ---------------- - HTML-Specific ---------------- - -Meta -==== - -Non-standard element: meta. - -Directive block: directive data and following indented lines (up to -the first blank line) are parsed for a flat field list. - -The "meta" directive is used to specify HTML metadata stored in HTML -META tags. "Metadata" is data about data, in this case data about web -pages. Metadata is used to describe and classify web pages in the -World Wide Web, in a form that is easy for search engines to extract -and collate. - -Within the directive block, a flat field list provides the syntax for -metadata. The field name becomes the contents of the "name" attribute -of the META tag, and the field body (interpreted as a single string -without inline markup) becomes the contents of the "content" -attribute. For example:: - - .. meta:: - :description: The reStructuredText plaintext markup language - :keywords: plaintext, markup language - -This would be converted to the following HTML:: - - <meta name="description" - content="The reStructuredText plaintext markup language"> - <meta name="keywords" content="plaintext, markup language"> - -Support for other META attributes ("http-equiv", "scheme", "lang", -"dir") are provided through field arguments, which must be of the form -"attr=value":: - - .. meta:: - :description lang=en: An amusing story - :description lang=fr: Un histoire amusant - -And their HTML equivalents:: - - <meta name="description" lang="en" content="An amusing story"> - <meta name="description" lang="fr" content="Un histoire amusant"> - -Some META tags use an "http-equiv" attribute instead of the "name" -attribute. To specify "http-equiv" META tags, simply omit the name:: - - .. meta:: - :http-equiv=Content-Type: text/html; charset=ISO-8859-1 - -HTML equivalent:: - - <meta http-equiv="Content-Type" - content="text/html; charset=ISO-8859-1"> - - -Imagemap -======== - -Non-standard element: imagemap. - - ---------------- - Miscellaneous ---------------- - -Raw Data Pass-Through -===================== - -DTD element: pending. - -Directive block: the directive data is interpreted as an output format -type, and all following indented text is stored verbatim, -uninterpreted. - -The "raw" directive indicates non-reStructuredText data that is to be -passed untouched to the Writer. The name of the output format is -given in the directive data. During the initial parse, a "pending" -element is generated which acts as a placeholder, storing the format -and raw data internally. The interpretation of the code is up to the -Writer. A Writer may ignore any raw output not matching its format. - -For example, the following input would be passed untouched by an HTML -Writer:: - - .. raw:: html - <hr width=50 size=10> - -A LaTeX Writer could insert the following raw content into its -output stream:: - - .. raw:: latex - \documentclass[twocolumn]{article} - - -Restructuredtext-Test-Directive -=============================== - -DTD element: system_warning. - -Directive block: directive data is stored, and all following indented -text is interpreted as a literal block. - -This directive is provided for test purposes only. (Nobody is -expected to type in a name *that* long!) It is converted into a -level-1 (info) system message showing the directive data, possibly -followed by a literal block containing the rest of the directive -block. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: |