From 101671ae44e1686680c80cd07b452aabeb88fb63 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 20 Apr 2002 03:01:52 +0000 Subject: Initial revision git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@18 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 344 ++++++ docs/ref/docutils.dtd | 514 ++++++++ docs/ref/rst/directives.txt | 360 ++++++ docs/ref/rst/introduction.txt | 307 +++++ docs/ref/rst/restructuredtext.txt | 2344 +++++++++++++++++++++++++++++++++++++ docs/ref/soextblx.dtd | 312 +++++ 6 files changed, 4181 insertions(+) create mode 100644 docs/ref/doctree.txt create mode 100644 docs/ref/docutils.dtd create mode 100644 docs/ref/rst/directives.txt create mode 100644 docs/ref/rst/introduction.txt create mode 100644 docs/ref/rst/restructuredtext.txt create mode 100644 docs/ref/soextblx.dtd (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt new file mode 100644 index 000000000..90aea7054 --- /dev/null +++ b/docs/ref/doctree.txt @@ -0,0 +1,344 @@ +================================== + Docutils Document Tree Structure +================================== +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +This document describes the internal data structure representing +document trees in Docutils. The data structure is defined by the +hierarchy of classes in the ``docutils.nodes`` module. It is also +formally described by the `Docutils Generic DTD`_ XML document type +definition, docutils.dtd_, which is the definitive source for element +hierarchy details. + +Below is a simplified diagram of the hierarchy of element types in the +Docutils document tree structure. An element may contain any other +elements immediately below it in the diagram. Text in square brackets +are notes. Element types in parentheses indicate recursive or +one-to-many relationships; sections may contain (sub)sections, tables +contain further body elements, etc. :: + + +--------------------------------------------------------------------+ + | document [may begin with a title, subtitle, docinfo] | + | +--------------------------------------+ + | | sections [each begins with a title] | + +-----------------------------+-------------------------+------------+ + | [body elements:] | (sections) | + | | - literal | - lists | | - hyperlink +------------+ + | | blocks | - tables | | targets | + | para- | - doctest | - block | foot- | - sub. defs | + | graphs | blocks | quotes | notes | - comments | + +---------+-----------+----------+-------+--------------+ + | [text]+ | [text] | (body elements) | [text] | + | (inline +-----------+------------------+--------------+ + | markup) | + +---------+ + + +------------------- + Element Hierarchy +------------------- + +A class hierarchy has been implemented in nodes.py where the position +of the element (the level at which it can occur) is significant. +E.G., Root, Structural, Body, Inline classes etc. Certain +transformations will be easier because we can use isinstance() on +them. + +The elements making up Docutils document trees can be categorized into +the following groups: + +- _`Root element`: document_ + +- _`Title elements`: title_, subtitle_ + +- _`Bibliographic elements`: docinfo_, author_, authors_, + organization_, contact_, version_, revision_, status_, date_, + copyright_ + +- _`Structural elements`: document_, section_, topic_, transition_ + +- _`Body elements`: + + - _`General body elements`: paragraph_, literal_block_, + block_quote_, doctest_block_, table_, figure_, image_, footnote_ + + - _`Lists`: bullet_list_, enumerated_list_, definition_list_, + field_list_, option_list_ + + - _`Admonitions`: note_, tip_, warning_, error_, caution_, danger_, + important_ + + - _`Special body elements`: target_, substitution_definition_, + comment_, system_warning_ + +- _`Inline elements`: emphasis_, strong_, interpreted_, literal_, + reference_, target_, footnote_reference_, substitution_reference_, + image_, problematic_ + + +``Node`` +======== + + +``Text`` +======== + + +``Element`` +=========== + + +``TextElement`` +=============== + + +------------------- + Element Reference +------------------- + +``document`` +============ +description + +contents + +External attributes +------------------- +`Common external attributes`_. + + +Internal attributes +------------------- +- `Common internal attributes`_. +- ``explicittargets`` +- ``implicittargets`` +- ``externaltargets`` +- ``indirecttargets`` +- ``refnames`` +- ``anonymoustargets`` +- ``anonymousrefs`` +- ``autofootnotes`` +- ``autofootnoterefs`` +- ``reporter`` + + +--------------------- + Attribute Reference +--------------------- + +External Attributes +=================== + +Through the `%basic.atts;`_ parameter entity, all elements share the +following _`common external attributes`: id_, name_, dupname_, +source_. + + +``anonymous`` +------------- +The ``anonymous`` attribute + + +``auto`` +-------- +The ``auto`` attribute + + +``dupname`` +----------- +The ``dupname`` attribute + + +``id`` +------ +The ``id`` attribute + + +``name`` +-------- +The ``name`` attribute + + +``refid`` +--------- +The ``refid`` attribute + + +``refname`` +----------- +The ``refname`` attribute + + +``refuri`` +---------- +The ``refuri`` attribute + + +``source`` +---------- +The ``source`` attribute + + +``xml:space`` +------------- +The ``xml:space`` attribute + + +Internal Attributes +=================== + +All element objects share the following _`common internal attributes`: +rawsource_, children_, attributes_, tagname_. + + +------------------------ + DTD Parameter Entities +------------------------ + +``%basic.atts;`` +================ +The ``%basic.atts;`` parameter entity lists attributes common to all +elements. See `Common Attributes`_. + + +``%body.elements;`` +=================== +The ``%body.elements;`` parameter entity + + +``%inline.elements;`` +==================== +The ``%inline.elements;`` parameter entity + + +``%reference.atts;`` +==================== +The ``%reference.atts;`` parameter entity + + +``%structure.model;`` +===================== +The ``%structure.model;`` parameter entity + + +``%text.model;`` +================ +The ``%text.model;`` parameter entity + + +-------------------------------- + Appendix: Miscellaneous Topics +-------------------------------- + +Representation of Horizontal Rules +================================== + +Having added the "horizontal rule" construct to the reStructuredText_ +spec, a decision had to be made as to how to reflect the construct in +the implementation of the document tree. Given this source:: + + Document + ======== + + Paragraph + + -------- + + Paragraph + +The horizontal rule indicates a "transition" (in prose terms) or the +start of a new "division". Before implementation, the parsed document +tree would be:: + + +
+ + Document + <paragraph> + Paragraph + -------- <--- error here + <paragraph> + Paragraph + +There are several possibilities for the implementation. Solution 3 +was chosen. + +1. Implement horizontal rules as "divisions" or segments. A + "division" is a title-less, non-hierarchical section. The first + try at an implementation looked like this:: + + <document> + <section name="document"> + <title> + Document + <paragraph> + Paragraph + <division> + <paragraph> + Paragraph + + But the two paragraphs are really at the same level; they shouldn't + appear to be at different levels. There's really an invisible + "first division". The horizontal rule splits the document body + into two segments, which should be treated uniformly. + +2. Treating "divisions" uniformly brings us to the second + possibility:: + + <document> + <section name="document"> + <title> + Document + <division> + <paragraph> + Paragraph + <division> + <paragraph> + Paragraph + + With this change, documents and sections will directly contain + divisions and sections, but not body elements. Only divisions will + directly contain body elements. Even without a horizontal rule + anywhere, the body elements of a document or section would be + contained within a division element. This makes the document tree + deeper. This is similar to the way HTML treats document contents: + grouped within a <BODY> element. + +3. Implement them as "transitions", empty elements:: + + <document> + <section name="document"> + <title> + Document + <paragraph> + Paragraph + <transition> + <paragraph> + Paragraph + + A transition would be a "point element", not containing anything, + only identifying a point within the document structure. This keeps + the document tree flatter, but the idea of a "point element" like + "transition" smells bad. A transition isn't a thing itself, it's + the space between two divisions. + + This solution has been chosen for incorporation into the document + tree. + + +.. _Docutils Generic DTD: +.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd +.. _reStructuredText: + http://docutils.sourceforge.net/spec/rst/reStructuredText.html + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd new file mode 100644 index 000000000..d47238b4d --- /dev/null +++ b/docs/ref/docutils.dtd @@ -0,0 +1,514 @@ +<!-- +====================================================================== + Docutils Generic DTD +====================================================================== +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ +:Copyright: This DTD has been placed in the public domain. +:Filename: docutils.dtd + +More information about this DTD (document type definition) and the +Docutils project can be found at http://docutils.sourceforge.net/. +The latest version of this DTD is available from +http://docutils.sourceforge.net/spec/docutils.dtd. + +The proposed formal public identifier for this DTD is:: + + +//IDN python.org//DTD Docutils Generic//EN//XML +--> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Parameter Entities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Parameter entities are used to simplify the DTD (reduce duplication) +and to allow the DTD to be customized by wrapper DTDs. Parameter +entities beginning with 'additional' are meant to allow easy extension +by wrapper DTDs. +--> + +<!-- Attributes +================================================================== --> + +<!-- Boolean: no if zero(s), yes if any other value. --> +<!ENTITY % yesorno "NMTOKEN"> + +<!ENTITY % additional.basic.atts ""> +<!-- +Attributes shared by all elements in this DTD: + +- `id` is a unique identifier, typically assigned by the system. +- `name` is an identifier assigned in the markup. +- `dupname` is the same as `name`, used when it's a duplicate. +- `source` is the name of the source of this document or fragment. +- `class` is used to transmit individuality information forward. +--> +<!ENTITY % basic.atts + " id ID #IMPLIED + name CDATA #IMPLIED + dupname CDATA #IMPLIED + source CDATA #IMPLIED + class CDATA #IMPLIED + %additional.basic.atts; "> + +<!-- External reference to a URI/URL. --> +<!ENTITY % refuri.att + " refuri CDATA #IMPLIED "> + +<!-- Internal reference to the `id` attribute of an element. --> +<!ENTITY % refid.att + " refid IDREF #IMPLIED "> + +<!-- Space-separated list of id references, for backlinks. --> +<!ENTITY % backrefs.att + " backrefs IDREFS #IMPLIED "> + +<!-- +Internal reference to the `name` attribute of an element. On a +'target' element, 'refname' indicates an indirect target which may +resolve to either an internal or external reference. +--> +<!ENTITY % refname.att + " refname CDATA #IMPLIED "> + +<!ENTITY % additional.reference.atts ""> +<!-- Collected hyperlink reference attributes. --> +<!ENTITY % reference.atts + " %refuri.att; + %refid.att; + %refname.att; + %additional.reference.atts; "> + +<!-- Unnamed hyperlink. --> +<!ENTITY % anonymous.att + " anonymous %yesorno; #IMPLIED "> + +<!-- Auto-numbered footnote. --> +<!ENTITY % auto.att + " auto %yesorno; #IMPLIED "> + +<!-- XML standard attribute for whitespace-preserving elements. --> +<!ENTITY % fixedspace.att + " xml:space (default | preserve) #FIXED 'preserve' "> + + +<!-- Element OR-Lists +============================================================= --> + +<!ENTITY % additional.bibliographic.elements ""> +<!ENTITY % bibliographic.elements + " author | authors | organization | contact + | version | revision | status | date | copyright + %additional.bibliographic.elements; "> + +<!ENTITY % additional.structural.elements ""> +<!ENTITY % structural.elements + " section + %additional.structural.elements; "> + +<!ENTITY % additional.body.elements ""> +<!ENTITY % body.elements + " paragraph | literal_block | block_quote | doctest_block| table + | figure | image | footnote | citation + | bullet_list | enumerated_list | definition_list | field_list + | option_list + | attention | caution | danger | error | hint | important | note + | tip | warning + | target | substitution_definition | comment | pending + | system_message | raw + %additional.body.elements; "> + +<!ENTITY % additional.inline.elements ""> +<!ENTITY % inline.elements + " emphasis | strong | interpreted | literal + | reference | footnote_reference | citation_reference + | substitution_reference | target | image | problematic | raw + %additional.inline.elements; "> + +<!-- Element Content Models +================================================================== --> + +<!ENTITY % structure.model + " ( ( (%body.elements; | topic)+, + (transition, (%body.elements; | topic)+ )*, + (%structural.elements;)* ) + | (%structural.elements;)+ ) "> + +<!ENTITY % text.model + " (#PCDATA | %inline.elements;)* "> + +<!-- Table Model +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This DTD uses the Exchange subset of the CALS-table model (OASIS +Technical Memorandum 9901:1999 "XML Exchange Table Model DTD", +http://www.oasis-open.org/html/tm9901.htm). +--> + +<!ENTITY % calstblx PUBLIC + "-//OASIS//DTD XML Exchange Table Model 19990315//EN" + "soextblx.dtd"> + +<!-- These parameter entities customize the table model DTD. --> +<!ENTITY % bodyatt " %basic.atts; "> <!-- table elt --> +<!ENTITY % tbl.tgroup.att " %basic.atts; "> +<!ENTITY % tbl.thead.att " %basic.atts; "> +<!ENTITY % tbl.tbody.att " %basic.atts; "> +<!ENTITY % tbl.colspec.att " %basic.atts; "> +<!ENTITY % tbl.row.att " %basic.atts; "> +<!ENTITY % tbl.entry.mdl " (%body.elements;)* "> +<!ENTITY % tbl.entry.att + " %basic.atts; + morecols NMTOKEN #IMPLIED "> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Root Element +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!-- Optional elements may be generated by internal processing. --> +<!ELEMENT document + ((title, subtitle?)?, docinfo?, %structure.model;)> +<!ATTLIST document %basic.atts;> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Title Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!ELEMENT title %text.model;> +<!ATTLIST title + %basic.atts; + %refid.att;> + +<!ELEMENT subtitle %text.model;> +<!ATTLIST subtitle %basic.atts;> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Bibliographic Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!-- Container for bibliographic elements. May not be empty. --> +<!ELEMENT docinfo (%bibliographic.elements;)+> +<!ATTLIST docinfo %basic.atts;> + +<!ELEMENT author %text.model;> +<!ATTLIST author %basic.atts;> + +<!ELEMENT authors ((author, organization?, contact?)+)> +<!ATTLIST authors %basic.atts;> + +<!ELEMENT organization %text.model;> +<!ATTLIST organization %basic.atts;> + +<!ELEMENT contact %text.model;> +<!ATTLIST contact %basic.atts;> + +<!ELEMENT version %text.model;> +<!ATTLIST version %basic.atts;> + +<!ELEMENT revision %text.model;> +<!ATTLIST revision %basic.atts;> + +<!ELEMENT status %text.model;> +<!ATTLIST status %basic.atts;> + +<!ELEMENT date %text.model;> +<!ATTLIST date %basic.atts;> + +<!ELEMENT copyright %text.model;> +<!ATTLIST copyright %basic.atts;> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Structural Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!ELEMENT section (title, %structure.model;)> +<!ATTLIST section %basic.atts;> + +<!ELEMENT topic (title?, (%body.elements;)+)> +<!ATTLIST topic %basic.atts;> + +<!ELEMENT transition EMPTY> +<!ATTLIST transition %basic.atts;> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Body Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!ELEMENT paragraph %text.model;> +<!ATTLIST paragraph %basic.atts;> + +<!ELEMENT bullet_list (list_item+)> +<!ATTLIST bullet_list + %basic.atts; + bullet CDATA #IMPLIED> + +<!ELEMENT enumerated_list (list_item+)> +<!ATTLIST enumerated_list + %basic.atts; + enumtype (arabic | loweralpha | upperalpha + | lowerroman | upperroman) + #IMPLIED + prefix CDATA #IMPLIED + suffix CDATA #IMPLIED + start NUMBER #IMPLIED> + +<!ELEMENT list_item (%body.elements;)+> +<!ATTLIST list_item %basic.atts;> + +<!ELEMENT definition_list (definition_list_item+)> +<!ATTLIST definition_list %basic.atts;> + +<!ELEMENT definition_list_item (term, classifier?, definition)> +<!ATTLIST definition_list_item %basic.atts;> + +<!ELEMENT term %text.model;> +<!ATTLIST term %basic.atts;> + +<!ELEMENT classifier %text.model;> +<!ATTLIST classifier %basic.atts;> + +<!ELEMENT definition (%body.elements;)+> +<!ATTLIST definition %basic.atts;> + +<!ELEMENT field_list (field+)> +<!ATTLIST field_list %basic.atts;> + +<!ELEMENT field (field_name, field_argument*, field_body)> +<!ATTLIST field %basic.atts;> + +<!ELEMENT field_name (#PCDATA)> +<!ATTLIST field_name %basic.atts;> + +<!-- Support for Javadoc-style tags with arguments. --> +<!ELEMENT field_argument (#PCDATA)> +<!ATTLIST field_argument %basic.atts;> + +<!ELEMENT field_body (%body.elements;)+> +<!ATTLIST field_body %basic.atts;> + +<!ELEMENT option_list (option_list_item+)> +<!ATTLIST option_list %basic.atts;> + +<!ELEMENT option_list_item (option_group, description)> +<!ATTLIST option_list_item %basic.atts;> + +<!ELEMENT option_group (option+)> +<!ATTLIST option_group %basic.atts;> + +<!ELEMENT option (option_string, option_argument*)> +<!ATTLIST option %basic.atts;> + +<!ELEMENT option_string (#PCDATA)> +<!ATTLIST option_string %basic.atts;> + +<!-- +`delimiter` contains the string preceding the `option_argument`: +either the string separating it from the `option` (typically either +"=" or " ") or the string between option arguments (typically either +"," or " "). +--> +<!ELEMENT option_argument (#PCDATA)> +<!ATTLIST option_argument + %basic.atts; + delimiter CDATA #IMPLIED> + +<!ELEMENT description (%body.elements;)+> +<!ATTLIST description %basic.atts;> + +<!ELEMENT literal_block (#PCDATA)> +<!ATTLIST literal_block + %basic.atts; + %fixedspace.att;> + +<!ELEMENT block_quote (%body.elements;)+> +<!ATTLIST block_quote %basic.atts;> + +<!ELEMENT doctest_block (#PCDATA)> +<!ATTLIST doctest_block + %basic.atts; + %fixedspace.att;> + +<!ELEMENT attention (%body.elements;)+> +<!ATTLIST attention %basic.atts;> + +<!ELEMENT caution (%body.elements;)+> +<!ATTLIST caution %basic.atts;> + +<!ELEMENT danger (%body.elements;)+> +<!ATTLIST danger %basic.atts;> + +<!ELEMENT error (%body.elements;)+> +<!ATTLIST error %basic.atts;> + +<!ELEMENT hint (%body.elements;)+> +<!ATTLIST hint %basic.atts;> + +<!ELEMENT important (%body.elements;)+> +<!ATTLIST important %basic.atts;> + +<!ELEMENT note (%body.elements;)+> +<!ATTLIST note %basic.atts;> + +<!ELEMENT tip (%body.elements;)+> +<!ATTLIST tip %basic.atts;> + +<!ELEMENT warning (%body.elements;)+> +<!ATTLIST warning %basic.atts;> + +<!ELEMENT footnote (label?, (%body.elements;)+)> +<!ATTLIST footnote + %basic.atts; + %backrefs.att; + %auto.att;> + +<!ELEMENT citation (label, (%body.elements;)+)> +<!ATTLIST citation + %basic.atts; + %backrefs.att;> + +<!ELEMENT label (#PCDATA)> +<!ATTLIST label %basic.atts;> + +<!-- Empty except when used as an inline element. --> +<!ELEMENT target (%text.model;)> +<!ATTLIST target + %basic.atts; + %reference.atts; + %anonymous.att;> + +<!ELEMENT substitution_definition (%text.model;)> +<!ATTLIST substitution_definition %basic.atts;> + +<!ELEMENT comment (#PCDATA)> +<!ATTLIST comment + %basic.atts; + %fixedspace.att;> + +<!ELEMENT pending EMPTY> +<!ATTLIST pending %basic.atts;> + +<!ELEMENT figure (image, ((caption, legend?) | legend) > +<!ATTLIST figure %basic.atts;> + +<!-- Also an inline element. --> +<!ELEMENT image EMPTY> +<!ATTLIST image + %basic.atts; + uri CDATA #REQUIRED + alt CDATA #IMPLIED + height NMTOKEN #IMPLIED + width NMTOKEN #IMPLIED + scale NMTOKEN #IMPLIED> + +<!ELEMENT caption %text.model;> +<!ATTLIST caption %basic.atts;> + +<!ELEMENT legend (%body.elements;)+> +<!ATTLIST legend %basic.atts;> + +<!-- +Table elements: table, tgroup, colspec, thead, tbody, row, entry. +--> +%calstblx; + +<!-- Used to record processing information. --> +<!ELEMENT system_message (%body.elements;)+> +<!ATTLIST system_message + %basic.atts; + %backrefs.att; + level NMTOKEN #IMPLIED + type CDATA #IMPLIED> + +<!-- Used to pass raw data through the system. Also inline. --> +<!ELEMENT raw %text.model;> +<!ATTLIST raw + %basic.atts; + %fixedspace.att; + format CDATA #IMPLIED> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Inline Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Inline elements occur within the text contents of body elements. Some +nesting of inline elements is allowed by these definitions, with the +following caveats: + +- An inline element may not contain a nested element of the same type + (e.g. <strong> may not contain another <strong>). +- Nested inline elements may or may not be supported by individual + applications using this DTD. +- The inline elements <footnote_reference>, <citation_reference>, + <literal>, and <image> do not support nesting. +--> + +<!ELEMENT emphasis (%text.model;)> +<!ATTLIST emphasis %basic.atts;> + +<!ELEMENT strong (%text.model;)> +<!ATTLIST strong %basic.atts;> + +<!ELEMENT interpreted (%text.model;)> +<!ATTLIST interpreted + %basic.atts; + type CDATA #IMPLIED> + +<!ELEMENT literal (#PCDATA)> +<!ATTLIST literal %basic.atts;> + +<!ELEMENT reference (%text.model;)> +<!ATTLIST reference + %basic.atts; + %reference.atts; + %anonymous.att;> + +<!ELEMENT footnote_reference (#PCDATA)> +<!ATTLIST footnote_reference + %basic.atts; + %reference.atts; + %auto.att;> + +<!ELEMENT citation_reference (#PCDATA)> +<!ATTLIST citation_reference + %basic.atts; + %reference.atts;> + +<!ELEMENT substitution_reference (%text.model;)> +<!ATTLIST substitution_reference + %basic.atts; + %refname.att;> + +<!ELEMENT problematic (%text.model;)> +<!ATTLIST problematic + %basic.atts; + %refid.att;> + + +<!-- +Local Variables: +mode: sgml +indent-tabs-mode: nil +fill-column: 70 +End: +--> diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt new file mode 100644 index 000000000..cbb8b4609 --- /dev/null +++ b/docs/ref/rst/directives.txt @@ -0,0 +1,360 @@ +============================= + 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 Components +--------------------- + +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: diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt new file mode 100644 index 000000000..3d7cfc5f8 --- /dev/null +++ b/docs/ref/rst/introduction.txt @@ -0,0 +1,307 @@ +===================================== + An Introduction to reStructuredText +===================================== +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get +plaintext markup syntax and parser system. It is useful for in-line +program documentation (such as Python docstrings), for quickly +creating simple web pages, and for standalone documents. +reStructuredText_ is a proposed revision and reinterpretation of the +StructuredText_ and Setext_ lightweight markup systems. + +reStructuredText is designed for extensibility for specific +application domains. Its parser is a component of Docutils_. + +This document defines the goals_ of reStructuredText and provides a +history_ of the project. It is written using the reStructuredText +markup, and therefore serves as an example of its use. Please also +see an analysis of the `problems with StructuredText`_ and the +`reStructuredText markup specification`_ itself at project's web page, +http://docutils.sourceforge.net/rst.html. + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _StructuredText: + http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage +.. _Setext: http://docutils.sourceforge.net/mirror/setext.html +.. _Docutils: http://docutils.sourceforge.net/ +.. _Problems with StructuredText: problems.html +.. _reStructuredText Markup Specification: reStructuredText.html + + +Goals +===== + +The primary goal of reStructuredText_ is to define a markup syntax for +use in Python docstrings and other documentation domains, that is +readable and simple, yet powerful enough for non-trivial use. The +intended purpose of the reStructuredText markup is twofold: + +- the establishment of a set of standard conventions allowing the + expression of structure within plaintext, and + +- the conversion of such documents into useful structured data + formats. + +The secondary goal of reStructuredText is to be accepted by the Python +community (by way of being blessed by PythonLabs and the BDFL [#]_) as +a standard for Python inline documentation (possibly one of several +standards, to account for taste). + +.. [#] Python's creator and "Benevolent Dictator For Life", + Guido van Rossum. + +To clarify the primary goal, here are specific design goals, in order, +beginning with the most important: + +1. Readable. The marked-up text must be easy to read without any + prior knowledge of the markup language. It should be as easily + read in raw form as in processed form. + +2. Unobtrusive. The markup that is used should be as simple and + unobtrusive as possible. The simplicity of markup constructs + should be roughly proporional to their frequency of use. The most + common constructs, with natural and obvious markup, should be the + simplest and most unobtrusive. Less common contstructs, for which + there is no natural or obvious markup, should be distinctive. + +3. Unambiguous. The rules for markup must not be open for + interpretation. For any given input, there should be one and only + one possible output (including error output). + +4. Unsurprising. Markup constructs should not cause unexpected output + upon processing. As a fallback, there must be a way to prevent + unwanted markup processing when a markup construct is used in a + non-markup context (for example, when documenting the markup syntax + itself). + +5. Intuitive. Markup should be as obvious and easily remembered as + possible, for the author as well as for the reader. Constructs + should take their cues from such naturally occurring sources as + plaintext email messages, newsgroup postings, and text + documentation such as README.txt files. + +6. Easy. It should be easy to mark up text using any ordinary text + editor. + +7. Scalable. The markup should be applicable regardless of the length + of the text. + +8. Powerful. The markup should provide enough constructs to produce a + reasonably rich structured document. + +9. Language-neutral. The markup should apply to multiple natural (as + well as artificial) languages, not only English. + +10. Extensible. The markup should provide a simple syntax and + interface for adding more complex general markup, and custom + markup. + +11. Output-format-neutral. The markup will be appropriate for + processing to multiple output formats, and will not be biased + toward any particular format. + +The design goals above were used as criteria for accepting or +rejecting syntax, or selecting between alternatives. + +It is emphatically *not* the goal of reStructuredText to define +docstring semantics, such as docstring contents or docstring length. +These issues are orthogonal to the markup syntax and beyond the scope +of this specification. + +Also, it is not the goal of reStructuredText to maintain compatibility +with StructuredText_ or Setext_. reStructuredText shamelessly steals +their great ideas and ignores the not-so-great. + +Author's note: + + Due to the nature of the problem we're trying to solve (or, + perhaps, due to the nature of the proposed solution), the above + goals unavoidably conflict. I have tried to extract and distill + the wisdom accumulated over the years in the Python Doc-SIG_ + mailing list and elsewhere, to come up with a coherent and + consistent set of syntax rules, and the above goals by which to + measure them. + + There will inevitably be people who disagree with my particular + choices. Some desire finer control over their markup, others + prefer less. Some are concerned with very short docstrings, + others with full-length documents. This specification is an + effort to provide a reasonably rich set of markup constructs in a + reasonably simple form, that should satisfy a reasonably large + group of reasonable people. + + David Goodger (goodger@users.sourceforge.net), 2001-04-20 + +.. _Doc-SIG: http://www.python.org/sigs/doc-sig/ + + +History +======= + +reStructuredText_, the specification, is based on StructuredText_ and +Setext_. StructuredText was developed by Jim Fulton of `Zope +Corporation`_ (formerly Digital Creations) and first released in 1996. +It is now released as a part of the open-source 'Z Object Publishing +Environment' (ZOPE_). Ian Feldman's and Tony Sanders' earlier Setext_ +specification was either an influence on StructuredText or, by their +similarities, at least evidence of the correctness of this approach. + +I discovered StructuredText_ in late 1999 while searching for a way to +document the Python modules in one of my projects. Version 1.1 of +StructuredText was included in Daniel Larsson's pythondoc_. Although +I was not able to get pythondoc to work for me, I found StructuredText +to be almost ideal for my needs. I joined the Python Doc-SIG_ +(Documentation Special Interest Group) mailing list and found an +ongoing discussion of the shortcomings of the StructuredText +'standard'. This discussion has been going on since the inception of +the mailing list in 1996, and possibly predates it. + +I decided to modify the original module with my own extensions and +some suggested by the Doc-SIG members. I soon realized that the +module was not written with extension in mind, so I embarked upon a +general reworking, including adapting it to the 're' regular +expression module (the original inspiration for the name of this +project). Soon after I completed the modifications, I discovered that +StructuredText.py was up to version 1.23 in the ZOPE distribution. +Implementing the new syntax extensions from version 1.23 proved to be +an exercise in frustration, as the complexity of the module had become +overwhelming. + +In 2000, development on StructuredTextNG_ ("Next Generation") began at +`Zope Corporation`_ (then Digital Creations). It seems to have many +improvements, but still suffers from many of the problems of classic +StructuredText. + +I decided that a complete rewrite was in order, and even started a +`reStructuredText SourceForge project`_ (now inactive). My +motivations (the 'itches' I aim to 'scratch') are as follows: + +- I need a standard format for inline documentation of the programs I + write. This inline documentation has to be convertible to other + useful formats, such as HTML. I believe many others have the same + need. + +- I believe in the Setext/StructuredText idea and want to help + formalize the standard. However, I feel the current specifications + and implementations have flaws that desperately need fixing. + +- reStructuredText could form part of the foundation for a + documentation extraction and processing system, greatly benefitting + Python. But it is only a part, not the whole. reStructuredText is + a markup language specification and a reference parser + implementation, but it does not aspire to be the entire system. I + don't want reStructuredText or a hypothetical Python documentation + processor to die stillborn because of overambition. + +- Most of all, I want to help ease the documentation chore, the bane + of many a programmer. + +Unfortunately I was sidetracked and stopped working on this project. +In November 2000 I made the time to enumerate the problems of +StructuredText and possible solutions, and complete the first draft of +a specification. This first draft was posted to the Doc-SIG in three +parts: + +- `A Plan for Structured Text`__ +- `Problems With StructuredText`__ +- `reStructuredText: Revised Structured Text Specification`__ + +__ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html +__ http://mail.python.org/pipermail/doc-sig/2000-November/001240.html +__ http://mail.python.org/pipermail/doc-sig/2000-November/001241.html + +In March 2001 a flurry of activity on the Doc-SIG spurred me to +further revise and refine my specification, the result of which you +are now reading. An offshoot of the reStructuredText project has been +the realization that a single markup scheme, no matter how well +thought out, may not be enough. In order to tame the endless debates +on Doc-SIG, a flexible `Docstring Processing System framework`_ needed +to be constructed. This framework has become the more important of +the two projects; reStructuredText_ has found its place as one +possible choice for a single component of the larger framework. + +The project web site and the first project release were rolled out in +June 2001, including posting the second draft of the spec [#spec-2]_ +and the first draft of PEPs 256, 257, and 258 [#peps-1]_ to the +Doc-SIG. These documents and the project implementation proceeded to +evolve at a rapid pace. Implementation history details can be found +in the project file, HISTORY.txt_. + +In November 2001, the reStructuredText parser was nearing completion. +Development of the parser continued with the addition of small +convenience features, improvements to the syntax, the filling in of +gaps, and bug fixes. After a long holiday break, in early 2002 most +development moved over to the other Docutils components, the +"Readers", "Writers", and "Transforms". A "standalone" reader +(processes standalone text file documents) was completed in February, +and a basic HTML writer (producing HTML 4.01, using CSS-1) was +completed in early March. + +`PEP 287`_, "reStructuredText Standard Docstring Format", was created +to formally propose reStructuredText as a standard format for Python +docstrings, PEPs, and other files. It was first posted to +comp.lang.python_ and the Python-dev_ mailing list on 2002-04-02. + +Version 0.4 of the reStructuredText__ and `Docstring Processing +System`_ projects were released in April 2002. The two projects were +immediately merged, renamed to "Docutils_", and a 0.1 release soon +followed. + +.. __: `reStructuredText SourceForge project`_ + +.. [#spec-2] + - `An Introduction to reStructuredText`__ + - `Problems With StructuredText`__ + - `reStructuredText Markup Specification`__ + - `Python Extensions to the reStructuredText Markup + Specification`__ + + __ http://mail.python.org/pipermail/doc-sig/2001-June/001858.html + __ http://mail.python.org/pipermail/doc-sig/2001-June/001859.html + __ http://mail.python.org/pipermail/doc-sig/2001-June/001860.html + __ http://mail.python.org/pipermail/doc-sig/2001-June/001861.html + +.. [#peps-1] + - `PEP 256: Docstring Processing System Framework`__ + - `PEP 258: DPS Generic Implementation Details`__ + - `PEP 257: Docstring Conventions`__ + + Current working versions of the PEPs can be found in + http://docutils.sourceforge.net/spec/, and official versions can be + found in the `master PEP repository`_. + + __ http://mail.python.org/pipermail/doc-sig/2001-June/001855.html + __ http://mail.python.org/pipermail/doc-sig/2001-June/001856.html + __ http://mail.python.org/pipermail/doc-sig/2001-June/001857.html + + +.. _Zope Corporation: http://www.zope.com +.. _ZOPE: http://www.zope.org +.. _reStructuredText SourceForge project: + http://structuredtext.sourceforge.net/ +.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ +.. _StructuredTextNG: + http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG +.. _HISTORY.txt: + http://docutils.sourceforge.net/HISTORY.txt +.. _PEP 287: http://docutils.sourceforge.net/spec/pep-0287.txt +.. _Docstring Processing System framework: + http://docutils.sourceforge.net/spec/pep-0256.txt +.. _comp.lang.python: news:comp.lang.python +.. _Python-dev: http://mail.python.org/pipermail/python-dev/ +.. _Docstring Processing System: http://docstring.sourceforge.net/ +.. _Docutils: http://docutils.sourceforge.net/ +.. _master PEP repository: http://www.python.org/peps/ + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt new file mode 100644 index 000000000..149ef3fd4 --- /dev/null +++ b/docs/ref/rst/restructuredtext.txt @@ -0,0 +1,2344 @@ +======================================= + reStructuredText Markup Specification +======================================= +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +reStructuredText_ is plain text that uses simple and intuitive +constructs to indicate the structure of a document. These constructs +are equally easy to read in raw and processed forms. This document is +itself an example of reStructuredText (raw, if you are reading the +text file, or processed, if you are reading an HTML document, for +example). The reStructuredText parser is a component of Docutils_. + +Simple, implicit markup is used to indicate special constructs, such +as section headings, bullet lists, and emphasis. The markup used is +as minimal and unobtrusive as possible. Less often-used constructs +and extensions to the basic reStructuredText syntax may have more +elaborate or explicit markup. + +reStructuredText is applicable to documents of any length, from the +very small (such as inline program documentation fragments, e.g. +Python docstrings) to the quite large (this document). + +The first section gives a quick overview of the syntax of the +reStructuredText markup by example. A complete specification is given +in the `Syntax Details`_ section. + +`Literal blocks`_ (in which no markup processing is done) are used for +examples throughout this document, to illustrate the plain text +markup. + + +.. contents:: + + +----------------------- + Quick Syntax Overview +----------------------- + +A reStructuredText document is made up of body or block-level +elements, and may be structured into sections. Sections_ are +indicated through title style (underlines & optional overlines). +Sections contain body elements and/or subsections. Some body elements +contain further elements, such as lists containing list items, which +in turn may contain paragraphs and other body elemens. Others, such +as paragraphs, contain text and `inline markup`_ elements. + +Here are examples of `body elements`_: + +- Paragraphs_ (and `inline markup`_):: + + Paragraphs contain text and may contain inline markup: + *emphasis*, **strong emphasis**, `interpreted text`, ``inline + literals``, standalone hyperlinks (http://www.python.org), + external hyperlinks (Python_), internal cross-references + (example_), footnote references ([1]_), citation references + ([CIT2002]_), substitution references (|example|), and _`inline + hyperlink targets`. + + Paragraphs are separated by blank lines and are left-aligned. + +- Five types of lists: + + 1. `Bullet lists`_:: + + - This is a bullet list. + + - Bullets can be "-", "*", or "+". + + 2. `Enumerated lists`_:: + + 1. This is an enumerated list. + + 2. Enumerators may be arabic numbers, letters, or roman + numerals. + + 3. `Definition lists`_:: + + what + Definition lists associate a term with a definition. + + how + The term is a one-line phrase, and the definition is one + or more paragraphs or body elements, indented relative to + the term. + + 4. `Field lists`_:: + + :what: Field lists map field names to field bodies, like + database records. They are often part of an extension + syntax. + + :how: The field marker is a colon, the field name, optional + field arguments, and a colon. + + The field body may contain one or more body elements, + indented relative to the field marker. + + 5. `Option lists`_, for listing command-line options:: + + -a command-line option "a" + -b file options can have arguments + and long descriptions + --long options can be long also + --input=file long options can also have + arguments + /V DOS/VMS-style options too + + There must be at least two spaces between the option and the + description. + +- `Literal blocks`_:: + + Literal blocks are indented, and indicated with a double-colon + ("::") at the end of the preceding paragraph (right here -->):: + + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None + +- `Block quotes`_:: + + Block quotes consist of indented body elements: + + This theory, that is mine, is mine. + + Anne Elk (Miss) + +- `Doctest blocks`_:: + + >>> print 'Python-specific usage examples; begun with ">>>"' + Python-specific usage examples; begun with ">>>" + >>> print '(cut and pasted from interactive Python sessions)' + (cut and pasted from interactive Python sessions) + +- Tables_:: + + +------------------------+------------+----------+ + | Header row, column 1 | Header 2 | Header 3 | + +========================+============+==========+ + | body row 1, column 1 | column 2 | column 3 | + +------------------------+------------+----------+ + | body row 2 | Cells may span | + +------------------------+-----------------------+ + +- `Explicit markup blocks`_ all begin with an explicit block marker, + two periods and a space: + + - Footnotes_:: + + .. [1] A footnote contains body elements, consistently + indented by at least 3 spaces. + + - Citations_:: + + .. [CIT2002] Just like a footnote, except the label is + textual. + + - `Hyperlink targets`_:: + + .. _Python: http://www.python.org + + .. _example: + + The "_example" target above points to this paragraph. + + - Directives_:: + + .. image:: mylogo.png + + - `Substitution definitions`_:: + + .. |symbol here| image:: symbol.png + + - Comments_:: + + .. Comments begin with two dots and a space. Anything may + follow, except for the syntax of footnotes/citations, + hyperlink targets, directives, or substitution definitions. + + +---------------- + Syntax Details +---------------- + +Descriptions below list "DTD elements" (XML "generic identifiers") +corresponding to syntax constructs. For details on the hierarchy of +elements, please see `Docutils Document Tree Structure`_ and the +`Generic Plaintext Document Interface DTD`_ XML document type +definition. + + +Whitespace +========== + +Spaces are recommended for indentation_, but tabs may also be used. +Tabs will be converted to spaces. Tab stops are at every 8th column. + +Other whitespace characters (form feeds [chr(12)] and vertical tabs +[chr(11)]) are converted to single spaces before processing. + + +Blank Lines +----------- + +Blank lines are used to separate paragraphs and other elements. +Multiple successive blank lines are equivalent to a single blank line, +except within literal blocks (where all whitespace is preserved). +Blank lines may be omitted when the markup makes element separation +unambiguous, in conjunction with indentation. The first line of a +document is treated as if it is preceded by a blank line, and the last +line of a document is treated as if it is followed by a blank line. + + +Indentation +----------- + +Indentation is used to indicate, and is only significant in +indicating: + +- multi-line contents of list items, +- multiple body elements within a list item (including nested lists), +- the definition part of a definition list item, +- block quotes, +- the extent of literal blocks, and +- the extent of explicit markup blocks. + +Any text whose indentation is less than that of the current level +(i.e., unindented text or "dedents") ends the current level of +indentation. + +Since all indentation is significant, the level of indentation must be +consistent. For example, indentation is the sole markup indicator for +`block quotes`_:: + + This is a top-level paragraph. + + This paragraph belongs to a first-level block quote. + + Paragraph 2 of the first-level block quote. + +Multiple levels of indentation within a block quote will result in +more complex structures:: + + This is a top-level paragraph. + + This paragraph belongs to a first-level block quote. + + This paragraph belongs to a second-level block quote. + + Another top-level paragraph. + + This paragraph belongs to a second-level block quote. + + This paragraph belongs to a first-level block quote. The + second-level block quote above is inside this first-level + block quote. + +When a paragraph or other construct consists of more than one line of +text, the lines must be left-aligned:: + + This is a paragraph. The lines of + this paragraph are aligned at the left. + + This paragraph has problems. The + lines are not left-aligned. In addition + to potential misinterpretation, warning + and/or error messages will be generated + by the parser. + +Several constructs begin with a marker, and the body of the construct +must be indented relative to the marker. For constructs using simple +markers (`bullet lists`_, `enumerated lists`_, footnotes_, citations_, +`hyperlink targets`_, directives_, and comments_), the level of +indentation of the body is determined by the position of the first +line of text, which begins on the same line as the marker. For +example, bullet list bodies must be indented by at least two columns +relative to the left edge of the bullet:: + + - This is the first line of a bullet list + item's paragraph. All lines must align + relative to the first line. [1]_ + + This indented paragraph is interpreted + as a block quote. + + Because it is not sufficiently indented, + this paragraph does not belong to the list + item. + + .. [1] Here's a footnote. The second line is aligned + with the beginning of the footnote label. The ".." + marker is what determines the indentation. + +For constructs using complex markers (`field lists`_ and `option +lists`_), where the marker may contain arbitrary text, the indentation +of the first line *after* the marker determines the left edge of the +body. For example, field lists may have very long markers (containing +the field names):: + + :Hello: This field has a short field name, so aligning the field + body with the first line is feasible. + + :Number-of-African-swallows-requried-to-carry-a-coconut: It would + be very difficult to align the field body with the left edge + of the first line. It may even be preferable not to begin the + body on the same line as the marker. + + +Escaping Mechanism +================== + +The character set universally available to plain text documents, 7-bit +ASCII, is limited. No matter what characters are used for markup, +they will already have multiple meanings in written text. Therefore +markup characters *will* sometimes appear in text **without being +intended as markup**. Any serious markup system requires an escaping +mechanism to override the default meaning of the characters used for +the markup. In reStructuredText we use the backslash, commonly used +as an escaping character in other domains. + +A backslash followed by any character escapes that character. The +escaped character represents the character itself, and is prevented +from playing a role in any markup interpretation. The backslash is +removed from the output. A literal backslash is represented by two +backslashes in a row (the first backslash "escapes" the second, +preventing it being interpreted in an "escaping" role). + +There are two contexts in which backslashes have no special meaning: +literal blocks and inline literals. In these contexts, a single +backslash represents a literal backslash, without having to double up. + +Please note that the reStructuredText specification and parser do not +address the issue of the representation or extraction of text input +(how and in what form the text actually *reaches* the parser). +Backslashes and other characters may serve a character-escaping +purpose in certain contexts and must be dealt with appropriately. For +example, Python uses backslashes in strings to escape certain +characters, but not others. The simplest solution when backslashes +appear in Python docstrings is to use raw docstrings:: + + r"""This is a raw docstring. Backslashes (\) are not touched.""" + + +Reference Names +=============== + +Simple reference names are single words consisting of alphanumerics +plus internal hypens, underscores, and periods; no whitespace or other +characters are allowed. Footnote labels (Footnotes_ & `Footnote +References`_), citation labels (Citations_ & `Citation References`_), +`interpreted text`_ roles, and some `hyperlink references`_ use the +simple reference name syntax. + +Reference names using punctuation or whose names are phrases (two or +more space-separated words) are called "phrase-references". +Phrase-references are expressed by enclosing the phrase in backquotes +and treating the backquoted text as a reference name:: + + Want to learn about `my favorite programming language`_? + + .. _my favorite programming language: http://www.python.org + +Simple reference names may also optionally use backquotes. + +Reference names are whitespace-neutral and case-insensitive. When +resolving reference names internally: + +- whitespace is normalized (one or more spaces, horizontal or vertical + tabs, newlines, carriage returns, or form feeds, are interpreted as + a single space), and + +- case is normalized (all alphabetic characters are converted to + lowercase). + +For example, the following `hyperlink references`_ are equivalent:: + + - `A HYPERLINK`_ + - `a hyperlink`_ + - `A + Hyperlink`_ + +Hyperlinks_, footnotes_, and citations_ all share the same namespace +for reference names. The labels of citations (simple reference names) +and manually-numbered footnotes (numbers) are entered into the same +database as other hyperlink names. This means that a footnote +(defined as "``.. [1]``") which can be referred to by a footnote +reference (``[1]_``), can also be referred to by a plain hyperlink +reference (1_). Of course, each type of reference (hyperlink, +footnote, citation) may be processed and rendered differently. Some +care should be taken to avoid reference name conflicts. + + +Document Structure +================== + +Document +-------- + +DTD element: document. + +The top-level element of a parsed reStructuredText document is the +"document" element. After initial parsing, the document element is a +simple container for a document fragment, consisting of `body +elements`_, transitions_, and sections_, but lacking a document title +or other bibliographic elements. The code that calls the parser may +choose to run one or more optional post-parse transforms_, +rearranging the document fragment into a complete document with a +title and possibly other metadata elements (author, date, etc.; see +`Bibliographic Fields`_). + +Specifically, there is no way to specify a document title and subtitle +explicitly in reStructuredText. Instead, a lone top-level section +title (see Sections_ below) can be treated as the document +title. Similarly, a lone second-level section title immediately after +the "document title" can become the document subtitle. See the +`DocTitle transform`_ for details. + + +Sections +-------- + +DTD elements: section, title. + +Sections are identified through their titles, which are marked up with +adornment: "underlines" below the title text, and, in some cases, +matching "overlines" above the title. An underline/overline is a +single repeated punctuation character that begins in column 1 and +forms a line extending at least as far as the right edge of the title +text. Specifically, an underline/overline character may be any +non-alphanumeric printable 7-bit ASCII character [#]_. An +underline/overline must be at least 4 characters long (to avoid +mistaking ellipses ["..."] for overlines). When an overline is used, +the length and character used must match the underline. There may be +any number of levels of section titles, although some output formats +may have limits (HTML has 6 levels). + +.. [#] The following are all valid section title adornment + characters:: + + ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ + + Some characters are more suitable than others. The following are + recommended:: + + = - ` : ' " ~ ^ _ * + # < > + +Rather than imposing a fixed number and order of section title +adornment styles, the order enforced will be the order as encountered. +The first style encountered will be an outermost title (like HTML H1), +the second style will be a subtitle, the third will be a subsubtitle, +and so on. + +Below are examples of section title styles:: + + =============== + Section Title + =============== + + --------------- + Section Title + --------------- + + Section Title + ============= + + Section Title + ------------- + + Section Title + ````````````` + + Section Title + ''''''''''''' + + Section Title + ............. + + Section Title + ~~~~~~~~~~~~~ + + Section Title + ************* + + Section Title + +++++++++++++ + + Section Title + ^^^^^^^^^^^^^ + +When a title has both an underline and an overline, the title text may +be inset, as in the first two examples above. This is merely +aesthetic and not significant. Underline-only title text may *not* be +inset. + +A blank line after a title is optional. All text blocks up to the +next title of the same or higher level are included in a section (or +subsection, etc.). + +All section title styles need not be used, nor need any specific +section title style be used. However, a document must be consistent +in its use of section titles: once a hierarchy of title styles is +established, sections must use that hierarchy. + +Each section title automatically generates a hyperlink target pointing +to the section. The text of the hyperlink target (the "reference +name") is the same as that of the section title. See `Implicit +Hyperlink Targets`_ for a complete description. + +Sections may contain `body elements`_, transitions_, and nested +sections. + + +Transitions +----------- + +DTD element: transition. + + Instead of subheads, extra space or a type ornament between + paragraphs may be used to mark text divisions or to signal + changes in subject or emphasis. + + (The Chicago Manual of Style, 14th edition, section 1.80) + +Transitions are commonly seen in novels and short fiction, as a gap +spanning one or more lines, with or without a type ornament such as a +row of asterisks. Transitions separate other body elements. A +transition should not begin or end a section or document, nor should +two transitions be immediately adjacent. + +The syntax for a transition marker is a horizontal line of 4 or more +repeated punctuation characters. The syntax is the same as section +title underlines without title text. Transition markers require blank +lines before and after:: + + Para. + + ---------- + + Para. + +Unlike section title underlines, no hierarchy of transition markers is +enforced, nor do differences in transition markers accomplish +anything. It is recommended that a single consistent style be used. + +The processing system is free to render transitions in output in any +way it likes. For example, horizontal rules (``<HR>``) in HTML output +would be an obvious choice. + + +Body Elements +============= + +Paragraphs +---------- + +DTD element: paragraph. + +Paragraphs consist of blocks of left-aligned text with no markup +indicating any other body element. Blank lines separate paragraphs +from each other and from other body elements. Paragraphs may contain +`inline markup`_. + +Syntax diagram:: + + +------------------------------+ + | paragraph | + | | + +------------------------------+ + + +------------------------------+ + | paragraph | + | | + +------------------------------+ + + +Bullet Lists +------------ + +DTD elements: bullet_list, list_item. + +A text block which begins with a "-", "*", or "+", followed by +whitespace, is a bullet list item (a.k.a. "unordered" list item). +List item bodies must be left-aligned and indented relative to the +bullet; the text immediately after the bullet determines the +indentation. For example:: + + - This is the first bullet list item. The blank line above the + first list item is required; blank lines between list items + (such as below this paragraph) are optional. + + - This is the first paragraph in the second item in the list. + + This is the second paragraph in the second item in the list. + The blank line above this paragraph is required. The left edge + of this paragraph lines up with the paragraph above, both + indented relative to the bullet. + + - This is a sublist. The bullet lines up with the left edge of + the text blocks above. A sublist is a new list so requires a + blank line above and below. + + - This is the third item of the main list. + + This paragraph is not part of the list. + +Here are examples of **incorrectly** formatted bullet lists:: + + - This first line is fine. + A blank line is required between list items and paragraphs. + (Warning) + + - The following line appears to be a new sublist, but it is not: + - This is a paragraph contination, not a sublist (since there's + no blank line). This line is also incorrectly indented. + - Warnings may be issued by the implementation. + +Syntax diagram:: + + +------+-----------------------+ + | "- " | list item | + +------| (body elements)+ | + +-----------------------+ + + +Enumerated Lists +---------------- + +DTD elements: enumerated_list, list_item. + +Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists, +but use enumerators instead of bullets. An enumerator consists of an +enumeration sequence member and formatting, followed by whitespace. +The following enumeration sequences are recognized: + +- arabic numerals: 1, 2, 3, ... (no upper limit). +- uppercase alphabet characters: A, B, C, ..., Z. +- lower-case alphabet characters: a, b, c, ..., z. +- uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999). +- lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999). + +The following formatting types are recognized: + +- suffixed with a period: "1.", "A.", "a.", "I.", "i.". +- surrounded by parentheses: "(1)", "(A)", "(a)", "(I)", "(i)". +- suffixed with a right-parenthesis: "1)", "A)", "a)", "I)", "i)". + +A system message will be generated for each of the following cases: + +- The enumerators do not all have the same format and sequence type. + +- The enumerators are not in sequence (i.e., "1.", "3." generates a + level-1 [info] system message and produces two separate lists). + +It is recommended that the enumerator of the first list item be +ordinal-1 ("1", "A", "a", "I", or "i"). Although other start-values +will be recognized, they may not be supported by the output format. + +Lists using Roman numerals must begin with "I"/"i" or a +multi-character value, such as "II" or "XV". Any other +single-character Roman numeral ("V", "X", etc.) will be interpreted as +a letter of the alphabet, not as a Roman numeral. Likewise, lists +using letters of the alphabet may not begin with "I"/"i", since these +are recognized as Roman numeral 1. + +Nested enumerated lists must be created with indentation. For +example:: + + 1. Item 1. + + a) Item 1a. + b) Item 1b. + +Example syntax diagram:: + + +-------+----------------------+ + | "1. " | list item | + +-------| (body elements)+ | + +----------------------+ + + +Definition Lists +---------------- + +DTD elements: definition_list, definition_list_item, term, classifier, +definition. + +Each definition list item contains a term, an optional classifier, and +a definition. A term is a simple one-line word or phrase. An +optional classifier may follow the term on the same line, after " : " +(space, colon, space). A definition is a block indented relative to +the term, and may contain multiple paragraphs and other body elements. +There may be no blank line between a term and a definition (this +distinguishes definition lists from `block quotes`_). Blank lines are +required before the first and after the last definition list item, but +are optional in-between. For example:: + + term 1 + Definition 1. + + term 2 + Definition 2, paragraph 1. + + Definition 2, paragraph 2. + + term 3 : classifier + Definition 3. + +A definition list may be used in various ways, including: + +- As a dictionary or glossary. The term is the word itself, a + classifier may be used to indicate the usage of the term (noun, + verb, etc.), and the definition follows. + +- To describe program variables. The term is the variable name, a + classifier may be used to indicate the type of the variable (string, + integer, etc.), and the definition describes the variable's use in + the program. This usage of definition lists supports the classifier + syntax of Grouch_, a system for describing and enforcing a Python + object schema. + +Syntax diagram:: + + +---------------------------+ + | term [ " : " classifier ] | + +--+------------------------+--+ + | definition | + | (body elements)+ | + +---------------------------+ + + +Field Lists +----------- + +DTD elements: field_list, field, field_name, field_argument, +field_body. + +Field lists are mappings from field names to field bodies, modeled on +RFC822_ headers. A field name is made up of one or more letters, +numbers, and punctuation, except colons (":") and whitespace. Field +names are case-insensitive. There may be additional data separated +from the field name, called field arguments. The field name and +optional field argument(s), along with a single colon prefix and +suffix, together form the field marker. The field marker is followed +by whitespace and the field body. The field body may contain multiple +body elements, indented relative to the field marker. The first line +after the field name marker determines the indentation of the field +body. For example:: + + :Date: 2001-08-16 + :Version: 1 + :Authors: - Me + - Myself + - I + :Indentation: Since the field marker may be quite long, the second + and subsequent lines of the field body do not have to line up + with the first line, but they must be indented relative to the + field name marker, and they must line up with each other. + :Parameter i: integer + +Field arguments are separated from the field name and each other by +whitespace, and may not contain colons (":"). The interpretation of +field arguments is up to the application. For example:: + + :name1 word number=1: + Both "word" and "number=1" are single words. + +The syntax for field arguments may be extended in the future. For +example, quoted phrases may be treated as a single argument, and +direct support for the "name=value" syntax may be added. + +Applications of reStructuredText may recognize field names and +transform fields or field bodies in certain contexts; they are often +used as part of an extension syntax. See `Bibliographic Fields`_ +below for one example, or the "image" directive in `reStructuredText +Directives`_ for another. + +Standard RFC822 headers cannot be used for this construct because they +are ambiguous. A word followed by a colon at the beginning of a line +is common in written text. However, in well-defined contexts such as +when a field list invariably occurs at the beginning of a document +(PEPs and email messages), standard RFC822 headers could be used. + +Syntax diagram (simplified):: + + +------------------------------+------------+ + | ":" name (" " argument)* ":" | field body | + +-------+----------------------+ | + | (body elements)+ | + +-----------------------------------+ + + +Bibliographic Fields +```````````````````` + +DTD elements: docinfo, author, authors, organization, contact, +version, status, date, copyright, topic. + +When a field list is the first non-comment element in a document +(after the document title, if there is one), it may have certain +specific fields transformed to document bibliographic data. This +bibliographic data corresponds to the front matter of a book, such as +the title page and copyright page. + +Certain field names (listed below) are recognized and transformed to +the corresponding DTD elements, most becoming child elements of the +"docinfo" element. No ordering is required of these fields, although +they may be rearranged to fit the document structure, as noted. +Unless otherwise indicated in the list below, each of the +bibliographic elements' field bodies may contain a single paragraph +only. Field bodies may be checked for `RCS keywords`_ and cleaned up. +Any unrecognized fields will remain in a generic field list in the +document body. + +The registered bibliographic field names and their corresponding DTD +elements are as follows: + +- Field name "Author": author element. +- "Authors": authors. May contain either: a single paragraph + consisting of a list of authors, separated by ";" or ","; or a + bullet list whose elements each contain a single paragraph per + author. +- "Organization": organization. +- "Contact": contact. +- "Version": version. +- "Status": status. +- "Date": date. +- "Copyright": copyright. +- "Abstract": topic. May contain arbitrary body elements. Only one + abstract is allowed. The abstract becomes a topic element with + title "Abstract" (or language equivalent) immediately following the + docinfo element. + +This field-name-to-element mapping can be extended, or replaced for +other languages. See the `DocInfo transform`_ implementation +documentation for details. + + +RCS Keywords +```````````` + +`Bibliographic fields`_ recognized by the parser are normally checked +for RCS [#]_ keywords and cleaned up [#]_. RCS keywords may be +entered into source files as "$keyword$", and once stored under RCS or +CVS [#]_, they are expanded to "$keyword: expansion text $". For +example, a "Status" field will be transformed to a "status" element:: + + :Status: $keyword: expansion text $ + +.. [#] Revision Control System. +.. [#] RCS keyword processing can be turned off (unimplemented). +.. [#] Concurrent Versions System. CVS uses the same keywords as RCS. + +Processed, the "status" element's text will become simply "expansion +text". The dollar sign delimiters and leading RCS keyword name are +removed. + +The RCS keyword processing only kicks in when all of these conditions +hold: + +1. The field list is in bibliographic context (first non-comment + contstruct in the document, after a document title if there is + one). + +2. The field name is a recognized bibliographic field name. + +3. The sole contents of the field is an expanded RCS keyword, of the + form "$Keyword: data $". + + +Option Lists +------------ + +DTD elements: option_list, option_list_item, option_group, option, +option_string, option_argument, description. + +Option lists are two-column lists of command-line options and +descriptions, documenting a program's options. For example:: + + -a Output all. + -b Output both (this description is + quite long). + -c arg Output just arg. + --long Output all day long. + + -p This option has two paragraphs in the description. + This is the first. + + This is the second. Blank lines may be omitted between + options (as above) or left in (as here and below). + + --very-long-option A VMS-syle option. Note the adjustment for + the required two spaces. + + --an-even-longer-option + The description can also start on the next line. + + -2, --two This option has two variants. + + -f FILE, --file=FILE These two options are synonyms; both have + arguments. + + /V A VMS/DOS-style option. + +There are several types of options recognized by reStructuredText: + +- Short POSIX options consist of one dash and an option letter. +- Long POSIX options consist of two dashes and an option word; some + systems use a single dash. +- Old GNU-style "plus" options consist of one plus and an option + letter ("plus" options are deprecated now, their use discouraged). +- DOS/VMS options consist of a slash and an option letter or word. + +Please note that both POSIX-style and DOS/VMS-style options may be +used by DOS or Windows software. These and other variations are +sometimes used mixed together. The names above have been chosen for +convenience only. + +The syntax for short and long POSIX options is based on the syntax +supported by Python's getopt.py_ module, which implements an option +parser similar to the `GNU libc getopt_long()`_ function but with some +restrictions. There are many variant option systems, and +reStructuredText option lists do not support all of them. + +Although long POSIX and DOS/VMS option words may be allowed to be +truncated by the operating system or the application when used on the +command line, reStructuredText option lists do not show or support +this with any special syntax. The complete option word should be +given, supported by notes about truncation if and when applicable. + +Options may be followed by an argument placeholder, whose role and +syntax should be explained in the description text. Either a space or +an equals sign may be used as a delimiter between options and option +argument placeholders. + +Multiple option "synonyms" may be listed, sharing a single +description. They must be separated by comma-space. + +There must be at least two spaces between the option(s) and the +description. The description may contain multiple body elements. The +first line after the option marker determines the indentation of the +description. As with other types of lists, blank lines are required +before the first option list item and after the last, but are optional +between option entries. + +Syntax diagram (simplified):: + + +----------------------------+-------------+ + | option [" " argument] " " | description | + +-------+--------------------+ | + | (body elements)+ | + +----------------------------------+ + + +Literal Blocks +-------------- + +DTD element: literal_block. + +A paragraph consisting of two colons ("::") signifies that all +following **indented** text blocks comprise a literal block. No +markup processing is done within a literal block. It is left as-is, +and is typically rendered in a monospaced typeface:: + + This is a typical paragraph. A literal block follows. + + :: + + for a in [5,4,3,2,1]: # this is program code, shown as-is + print a + print "it's..." + # a literal block continues until the indentation ends + + This text has returned to the indentation of the first paragraph, + is outside of the literal block, and is therefore treated as an + ordinary paragraph. + +The paragraph containing only "::" will be completely removed from the +output; no empty paragraph will remain. + +As a convenience, the "::" is recognized at the end of any paragraph. +If immediately preceded by whitespace, both colons will be removed +from the output (this is the "partially minimized" form). When text +immediately precedes the "::", *one* colon will be removed from the +output, leaving only one colon visible (i.e., "::" will be replaced by +":"; this is the "fully minimized" form). + +In other words, these are all equivalent (please pay attention to the +colons after "Paragraph"): + +1. Expanded form:: + + Paragraph: + + :: + + Literal block + +2. Partially minimized form:: + + Paragraph: :: + + Literal block + +3. Fully minimized form:: + + Paragraph:: + + Literal block + +The minimum leading whitespace will be removed from each line of the +literal block. Other than that, all whitespace (including line +breaks) is preserved. Blank lines are required before and after a +literal block, but these blank lines are not included as part of the +literal block. + +Syntax diagram:: + + +------------------------------+ + | paragraph | + | (ends with "::") | + +------------------------------+ + +---------------------------+ + | literal block | + +---------------------------+ + + +Block Quotes +------------ + +DTD element: block_quote. + +A text block that is indented relative to the preceding text, without +markup indicating it to be a literal block, is a block quote. All +markup processing (for body elements and inline markup) continues +within the block quote:: + + This is an ordinary paragraph, introducing a block quote. + + "It is my business to know things. That is my trade." + + -- Sherlock Holmes + +Blank lines are required before and after a block quote, but these +blank lines are not included as part of the block quote. + +Syntax diagram:: + + +------------------------------+ + | (current level of | + | indentation) | + +------------------------------+ + +---------------------------+ + | block quote | + | (body elements)+ | + +---------------------------+ + + +Doctest Blocks +-------------- + +DTD element: doctest_block. + +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, 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 + + 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. + + +Tables +------ + +DTD elements: table, tgroup, colspec, thead, tbody, row, entry. + +Tables are described with a visual outline made up of the characters +"-", "=", "|", and "+". The hyphen ("-") is used for horizontal lines +(row separators). The equals sign ("=") may be used to separate +optional header rows from the table body. The vertical bar ("|") is +used for vertical lines (column separators). The plus sign ("+") is +used for intersections of horizontal and vertical lines. + +Each table cell is treated as a miniature document; the top and bottom +cell boundaries act as delimiting blank lines. Each cell contains +zero or more body elements. Cell contents may include left and/or +right margins, which are removed before processing. Example:: + + +------------------------+------------+----------+----------+ + | Header row, column 1 | Header 2 | Header 3 | Header 4 | + | (header rows optional) | | | | + +========================+============+==========+==========+ + | body row 1, column 1 | column 2 | column 3 | column 4 | + +------------------------+------------+----------+----------+ + | body row 2 | Cells may span columns. | + +------------------------+------------+---------------------+ + | body row 3 | Cells may | - Table cells | + +------------------------+ span rows. | - contain | + | body row 4 | | - body elements. | + +------------------------+------------+---------------------+ + +As with other body elements, blank lines are required before and after +tables. Tables' left edges should align with the left edge of +preceding text blocks; otherwise, the table is considered to be part +of a block quote. + +Some care must be taken with tables to avoid undesired interactions +with cell text in rare cases. For example, the following table +contains a cell in row 2 spanning from column 2 to column 4:: + + +--------------+----------+-----------+-----------+ + | row 1, col 1 | column 2 | column 3 | column 4 | + +--------------+----------+-----------+-----------+ + | row 2 | | + +--------------+----------+-----------+-----------+ + | row 3 | | | | + +--------------+----------+-----------+-----------+ + +If a vertical bar is used in the text of that cell, it could have +unintended effects if accidentally aligned with column boundaries:: + + +--------------+----------+-----------+-----------+ + | row 1, col 1 | column 2 | column 3 | column 4 | + +--------------+----------+-----------+-----------+ + | row 2 | Use the command ``ls | more``. | + +--------------+----------+-----------+-----------+ + | row 3 | | | | + +--------------+----------+-----------+-----------+ + +Several solutions are possible. All that is needed is to break the +continuity of the cell outline rectangle. One possibility is to shift +the text by adding an extra space before:: + + +--------------+----------+-----------+-----------+ + | row 1, col 1 | column 2 | column 3 | column 4 | + +--------------+----------+-----------+-----------+ + | row 2 | Use the command ``ls | more``. | + +--------------+----------+-----------+-----------+ + | row 3 | | | | + +--------------+----------+-----------+-----------+ + +Another possibility is to add an extra line to row 2:: + + +--------------+----------+-----------+-----------+ + | row 1, col 1 | column 2 | column 3 | column 4 | + +--------------+----------+-----------+-----------+ + | row 2 | Use the command ``ls | more``. | + | | | + +--------------+----------+-----------+-----------+ + | row 3 | | | | + +--------------+----------+-----------+-----------+ + + +Explicit Markup Blocks +---------------------- + +An explicit markup block is a text block: + +- whose first line begins with ".." followed by whitespace (the + "explicit markup start"), +- whose second and subsequent lines (if any) are indented relative to + the first, and +- which ends before an unindented line. + +Explicit markup blocks are analogous to bullet list items, with ".." +as the bullet. The text immediately after the explicit markup start +determines the indentation of the block body. Blank lines are +required between explicit markup blocks and other elements, but are +optional between explicit markup blocks where unambiguous. + +The explicit markup syntax is used for footnotes, citations, hyperlink +targets, directives, and comments. + + +Footnotes +````````` + +DTD elements: footnote, label. + +Each footnote consists of an explicit markup start (".. "), a left +square bracket, the footnote label, a right square bracket, and +whitespace, followed by indented body elements. A footnote label can +be: + +- a whole decimal number consisting of one or more digits, + +- a single "#" (denoting `auto-numbered footnotes`_), + +- a "#" followed by a simple reference name (an `autonumber label`_), + or + +- a single "*" (denoting `auto-symbol footnotes`_). + +If the first body element within a footnote is a simple paragraph, it +may begin on the same line as the footnote label. Other elements must +begin on a new line, consistently indented (by at least 3 spaces) and +left-aligned. + +Footnotes may occur anywhere in the document, not only at the end. +Where or how they appear in the processed output depends on the +processing system. + +Here is a manually numbered footnote:: + + .. [1] Body elements go here. + +Each footnote automatically generates a hyperlink target pointing to +itself. The text of the hyperlink target name is the same as that of +the footnote label. `Auto-numbered footnotes`_ generate a number as +their footnote label and reference name. See `Implicit Hyperlink +Targets`_ for a complete description of the mechanism. + +Syntax diagram:: + + +-------+-------------------------+ + | ".. " | "[" label "]" footnote | + +-------+ | + | (body elements)+ | + +-------------------------+ + + +Auto-Numbered Footnotes +....................... + +A number sign ("#") may be used as the first character of a footnote +label to request automatic numbering of the footnote or footnote +reference. + +The first footnote to request automatic numbering is assigned the +label "1", the second is assigned the label "2", and so on (assuming +there are no manually numbered footnotes present; see `Mixed Manual +and Auto-Numbered Footnotes`_ below). A footnote which has +automatically received a label "1" generates an implicit hyperlink +target with name "1", just as if the label was explicitly specified. + +.. _autonumber label: `autonumber labels`_ + +A footnote may specify a label explicitly while at the same time +requesting automatic numbering: ``[#label]``. These labels are called +_`autonumber labels`. Autonumber labels do two things: + +- On the footnote itself, they generate a hyperlink target whose name + is the autonumber label (doesn't include the "#"). + +- They allow an automatically numbered footnote to be referred to more + than once, as a footnote reference or hyperlink reference. For + example:: + + If [#note]_ is the first footnote reference, it will show up as + "[1]". We can refer to it again as [#note]_ and again see + "[1]". We can also refer to it as note_ (an ordinary internal + hyperlink reference). + + .. [#note] This is the footnote labeled "note". + +The numbering is determined by the order of the footnotes, not by the +order of the references. For footnote references without autonumber +labels (``[#]_``), the footnotes and footnote references must be in +the same relative order but need not alternate in lock-step. For +example:: + + [#]_ is a reference to footnote 1, and [#]_ is a reference to + footnote 2. + + .. [#] This is footnote 1. + .. [#] This is footnote 2. + .. [#] This is footnote 3. + + [#]_ is a reference to footnote 3. + +Special care must be taken if footnotes themselves contain +auto-numbered footnote references, or if multiple references are made +in close proximity. Footnotes and references are noted in the order +they are encountered in the document, which is not necessarily the +same as the order in which a person would read them. + + +Auto-Symbol Footnotes +..................... + +An asterisk ("*") may be used for footnote labels to request automatic +symbol generation for footnotes and footnote references. The asterisk +may be the only character in the label. For example:: + + Here is a symbolic footnote reference: [*]_. + + .. [*] This is the footnote. + +A transform will insert symbols as labels into corresponding footnotes +and footnote references. + +The standard Docutils system uses the following symbols for footnote +marks [#]_: + +- asterisk/star ("*") +- dagger (HTML character entity "†") +- double dagger ("‡") +- section mark ("§") +- pilcrow or paragraph mark ("¶") +- number sign ("#") +- spade suit ("♠") +- heart suit ("♥") +- diamond suit ("♦") +- club suit ("♣") + +.. [#] This list was inspired by the list of symbols for "Note + Reference Marks" in The Chicago Manual of Style, 14th edition, + section 12.51. "Parallels" ("\|\|") were given in CMoS instead of + the pilcrow. The last four symbols (the card suits) were added + arbitrarily. + +If more than ten symbols are required, the same sequence will be +reused, doubled and then tripled, and so on ("**" etc.). + + +Mixed Manual and Auto-Numbered Footnotes +........................................ + +Manual and automatic footnote numbering may both be used within a +single document, although the results may not be expected. Manual +numbering takes priority. Only unused footnote numbers are assigned +to auto-numbered footnotes. The following example should be +illustrative:: + + [2]_ will be "2" (manually numbered), + [#]_ will be "3" (anonymous auto-numbered), and + [#label]_ will be "1" (labeled auto-numbered). + + .. [2] This footnote is labeled manually, so its number is fixed. + + .. [#label] This autonumber-labeled footnote will be labeled "1". + It is the first auto-numbered footnote and no other footnote + with label "1" exists. The order of the footnotes is used to + determine numbering, not the order of the footnote references. + + .. [#] This footnote will be labeled "3". It is the second + auto-numbered footnote, but footnote label "2" is already used. + + +Citations +````````` + +Citations are identical to footnotes except that they use only +non-numeric labels such as ``[note]`` or ``[GVR2001]``. Citation +labels are simple `reference names`_ (case-insensitive single words +consisting of alphanumerics plus internal hyphens, underscores, and +periods; no whitespace). Citations may be rendered separately and +differently from footnotes. For example:: + + Here is a citation reference: [CIT2002]_. + + .. [CIT2002] This is the citation. It's just like a footnote, + except the label is textual. + + +.. _hyperlinks: + +Hyperlink Targets +````````````````` + +DTD element: target. + +These are also called _`explicit hyperlink targets`, to differentiate +them from `implicit hyperlink targets`_ defined below. + +Hyperlink targets identify a location within or outside of a document, +which may be linked to by `hyperlink references`_. + +Hyperlink targets may be named or anonymous. Named hyperlink targets +consist of an explicit markup start (".. "), an underscore, the +reference name (no trailing underscore), a colon, whitespace, and a +link block:: + + .. _hyperlink-name: link-block + +Reference names are whitespace-neutral and case-insensitive. See +`Reference Names`_ for details and examples. + +Anonymous hyperlink targets consist of an explicit markup start +(".. "), two underscores, a colon, whitespace, and a link block; there +is no reference name:: + + .. __: anonymous-hyperlink-target-link-block + +An alternate syntax for anonymous hyperlinks consists of two +underscores, a space, and a link block:: + + __ anonymous-hyperlink-target-link-block + +See `Anonymous Hyperlinks`_ below. + +There are three types of hyperlink targets: internal, external, and +indirect. + +1. _`Internal hyperlink targets` have empty link blocks. They provide + an end point allowing a hyperlink to connect one place to another + within a document. An internal hyperlink target points to the + element following the target. For example:: + + Clicking on this internal hyperlink will take us to the target_ + below. + + .. _target: + + The hyperlink target above points to this paragraph. + + Internal hyperlink targets may be "chained". Multiple adjacent + internal hyperlink targets all point to the same element:: + + .. _target1: + .. _target2: + + The targets "target1" and "target2" are synonyms; they both + point to this paragraph. + + If the element "pointed to" is an external hyperlink target (with a + URI in its link block; see #2 below) the URI from the external + hyperlink target is propagated to the internal hyperlink targets; + they will all "point to" the same URI. There is no need to + duplicate a URI. For example, all three of the following hyperlink + targets refer to the same URI:: + + .. _Python DOC-SIG mailing list archive: + .. _archive: + .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/ + + An inline form of internal hyperlink target is available; see + `Inline Hyperlink Targets`_. + +2. _`External hyperlink targets` have an absolute or relative URI in + their link blocks. For example, take the following input:: + + See the Python_ home page for info. + + .. _Python: http://www.python.org + + After processing into HTML, the hyperlink might be expressed as:: + + See the <A HREF="http://www.python.org">Python</A> home page + for info. + + An external hyperlink's 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 concatenated. + The following external hyperlink targets are equivalent:: + + .. _one-liner: http://docutils.sourceforge.net/rst.html + + .. _starts-on-this-line: http:// + docutils.sourceforge.net/rst.html + + .. _entirely-below: + http://docutils. + sourceforge.net/rst.html + + If an external hyperlink target's URI contains an underscore as its + last character, it must be escaped to avoid being mistaken for an + indirect hyperlink target:: + + This link_ refers to a file called ``underscore_``. + + .. _link: underscore\_ + +3. _`Indirect hyperlink targets` have a hyperlink reference in their + link blocks. In the following example, target "one" indirectly + references whatever target "two" references, and target "two" + references target "three", an internal hyperlink target. In + effect, all three reference the same thing:: + + .. _one: two_ + .. _two: three_ + .. _three: + + Just as with `hyperlink references`_ anywhere else in a document, + if a phrase-reference is used in the link block it must be enclosed + in backquotes. As with `external hyperlink targets`_, the link + block of an indirect hyperlink target may begin on the same line as + the explicit markup start or the next line. It may also be split + over multiple lines, in which case the lines are joined with + whitespace before being normalized. + + For example, the following indirect hyperlink targets are + equivalent:: + + .. _one-liner: `A HYPERLINK`_ + .. _entirely-below: + `a hyperlink`_ + .. _split: `A + Hyperlink`_ + +If a reference name contains a colon followed by whitespace, either: + +- the phrase must be enclosed in backquotes:: + + .. _`FAQTS: Computers: Programming: Languages: Python`: + http://python.faqts.com/ + +- or the colon(s) must be backslash-escaped in the link target:: + + .. _Chapter One\: "Tadpole Days": + + It's not easy being green... + +See `Implicit Hyperlink Targets`_ below for the resolution of +duplicate reference names. + +Syntax diagram:: + + +-------+----------------------+ + | ".. " | "_" name ":" link | + +-------+ block | + | | + +----------------------+ + + +Anonymous Hyperlinks +.................... + +The `World Wide Web Consortium`_ recommends in its `HTML Techniques +for Web Content Accessibility Guidelines`_ that authors should +"clearly identify the target of each link." Hyperlink references +should be as verbose as possible, but duplicating a verbose hyperlink +name in the target is onerous and error-prone. Anonymous hyperlinks +are designed to allow convenient verbose hyperlink references, and are +analogous to `Auto-Numbered Footnotes`_. They are particularly useful +in short or one-off documents. + +Anonymous `hyperlink references`_ are specified with two underscores +instead of one:: + + See `the web site of my favorite programming language`__. + +Anonymous targets begin with ".. __:"; no reference name is required +or allowed:: + + .. __: http://www.python.org + +As a convenient alternative, anonymous targets may begin with "__" +only:: + + __ http://www.python.org + +The reference name of the reference is not used to match the reference +to its target. Instead, the order of anonymous hyperlink references +and targets within the document is significant: the first anonymous +reference will link to the first anonymous target. The number of +anonymous hyperlink references in a document must match the number of +anonymous targets. + + +Directives +`````````` + +DTD elements: depend on the directive. + +Directives are indicated by an explicit markup start (".. ") followed +by the directive type, two colons, and whitespace. Directive types +are case-insensitive single words (alphanumerics plus internal +hyphens, underscores, and periods; no whitespace). Two colons are +used after the directive type for these reasons: + +- To avoid clashes with common comment text like:: + + .. Danger: modify at your own risk! + +- If an implementation of reStructuredText does not recognize a + directive (i.e., the directive-handler is not installed), the entire + directive block (including the directive itself) will be treated as + a literal block, and a level-3 (error) system message generated. + Thus "::" is a natural choice. + +Any text on the first line after the directive indicator is directive +data. The interpretation of directive data is up to the directive +code. Directive data may be interpreted as arguments to the +directive, or simply as the first line of the directive's text block. + +Actions taken in response to directives and the interpretation of text +in the directive block or subsequent text block(s) are +directive-dependent. Indented text following a directive may be +interpreted as a directive block. Simple directives may not require +any text beyond the directive data (if that), and will not process any +following indented text. + +Directives which have been implemented and registered in the reference +reStructuredText parser are described in the `reStructuredText +Directives`_ document. Below are examples of implemented directives. + +Directives are meant for the arbitrary processing of their contents +(the directive data & text block), which can be transformed into +something possibly unrelated to the original text. Directives are +used as an extension mechanism for reStructuredText, a way of adding +support for new constructs without adding new syntax. For example, +here's how an image may be placed:: + + .. image:: mylogo.png + +A figure (a graphic with a caption) may placed like this:: + + .. figure:: larch.png + The larch. + +An admonition (note, caution, etc.) contains other body elements:: + + .. note:: This is a paragraph + + - Here is a bullet list. + +It may also be possible for directives to be used as pragmas, to +modify the behavior of the parser, such as to experiment with +alternate syntax. There is no parser support for this functionality +at present; if a reasonable need for pragma directives is found, they +may be supported. + +Directives normally do not survive as "directive" elements past the +parsing stage; they are a *parser construct* only, and have no +intrinsic meaning outside of reStructuredText. Instead, the parser +will transform recognized directives into (possibly specialized) +document elements. Unknown directives will trigger level-3 (error) +system messages. + +Syntax diagram:: + + +-------+--------------------------+ + | ".. " | directive type "::" data | + +-------+ directive block | + | | + +--------------------------+ + + +Substitution Definitions +```````````````````````` + +DTD element: substitution_definition. + +Substitution definitions are indicated by an explicit markup start +(".. ") followed by a vertical bar, the substitution text, another +vertical bar, whitespace, and the definition block. Substitution text +may not begin or end with whitespace. A substitution definition block +contains an embedded inline-compatible directive (without the leading +".. "), such as an image. For example:: + + The |biohazard| symbol must be used on containers used to + dispose of medical waste. + + .. |biohazard| image:: biohazard.png + +It is an error for a substitution definition block to directly or +indirectly contain a circular substitution reference. + +`Substitution references`_ are replaced in-line by the processed +contents of the corresponding definition (linked by matching +substitution text). Substitution definitions allow the power and +flexibility of block-level directives_ to be shared by inline text. +They are a way to include arbitrarily complex inline structures within +text, while keeping the details out of the flow of text. They are the +equivalent of SGML/XML's named entities or programming language +macros. + +Without the substitution mechanism, every time someone wants an +application-specific new inline structure, they would have to petition +for a syntax change. In combination with existing directive syntax, +any inline structure can be coded without new syntax (except possibly +a new directive). + +Syntax diagram:: + + +-------+-----------------------------------------------------+ + | ".. " | "|" substitution text "| " directive type "::" data | + +-------+ directive block | + | | + +-----------------------------------------------------+ + +Following are some use cases for the substitution mechanism. Please +note that most of the embedded directives shown are examples only and +have not been implemented. + +Objects + Substitution references may be used to associate ambiguous text + with a unique object identifier. + + For example, many sites may wish to implement an inline "user" + directive:: + + |Michael| and |Jon| are our widget-wranglers. + + .. |Michael| user:: mjones + .. |Jon| user:: jhl + + Depending on the needs of the site, this may be used to index the + document for later searching, to hyperlink the inline text in + various ways (mailto, homepage, mouseover Javascript with profile + and contact information, etc.), or to customize presentation of + the text (include username in the inline text, include an icon + image with a link next to the text, make the text bold or a + different color, etc.). + + The same approach can be used in documents which frequently refer + to a particular type of objects with unique identifiers but + ambiguous common names. Movies, albums, books, photos, court + cases, and laws are possible. For example:: + + |The Transparent Society| offers a fascinating alternate view + on privacy issues. + + .. |The Transparent Society| book:: isbn=0738201448 + + Classes or functions, in contexts where the module or class names + are unclear and/or interpreted text cannot be used, are another + possibility:: + + 4XSLT has the convenience method |runString|, so you don't + have to mess with DOM objects if all you want is the + transformed output. + + .. |runString| function:: module=xml.xslt class=Processor + +Images + Images are a common use for substitution references:: + + West led the |H| 3, covered by dummy's |H| Q, East's |H| K, + and trumped in hand with the |S| 2. + + .. |H| image:: /images/heart.png + :height: 11 + :width: 11 + .. |S| image:: /images/spade.png + :height: 11 + :width: 11 + + * |Red light| means stop. + * |Green light| means go. + * |Yellow light| means go really fast. + + .. |Red light| image:: red_light.png + .. |Green light| image:: green_light.png + .. |Yellow light| image:: yellow_light.png + + |-><-| is the official symbol of POEE_. + + .. |-><-| image:: discord.png + .. _POEE: http://www.poee.org/ + + The "image" directive has been implemented. + +Styles [#]_ + Substitution references may be used to associate inline text with + an externally defined presentation style:: + + Even |the text in Texas| is big. + + .. |the text in Texas| style:: big + + The style name may be meaningful in the context of some particular + output format (CSS class name for HTML output, LaTeX style name + for LaTeX, etc), or may be ignored for other output formats (often + for plain text). + + .. @@@ This needs to be rethought & rewritten or removed: + + Interpreted text is unsuitable for this purpose because the set + of style names cannot be predefined - it is the domain of the + content author, not the author of the parser and output + formatter - and there is no way to associate a stylename + argument with an interpreted text style role. Also, it may be + desirable to use the same mechanism for styling blocks:: + + .. style:: motto + At Bob's Underwear Shop, we'll do anything to get in + your pants. + + .. style:: disclaimer + All rights reversed. Reprint what you like. + + .. [#] There may be sufficient need for a "style" mechanism to + warrant simpler syntax such as an extension to the interpreted + text role syntax. The substitution mechanism is cumbersome for + simple text styling. + +Templates + Inline markup may be used for later processing by a template + engine. For example, a Zope_ author might write:: + + Welcome back, |name|! + + .. |name| tal:: replace user/getUserName + + After processing, this ZPT output would result:: + + Welcome back, + <span tal:replace="user/getUserName">name</span>! + + Zope would then transform this to something like "Welcome back, + David!" during a session with an actual user. + +Replacement text + The substitution mechanism may be used for simple macro + substitution. This may be appropriate when the replacement text + is repeated many times throughout one or more documents, + especially if it may need to change later. A short example is + unavoidably contrived:: + + |RST| is a little annoying to type over and over, especially + when writing about |RST| itself, and spelling out the + bicapitalized word |RST| every time isn't really necessary for + |RST| source readability. + + .. |RST| replace:: reStructuredText_ + .. _reStructuredText: http://docutils.sourceforge.net/rst.html + + Substitution is also appropriate when the replacement text cannot + be represented using other inline constructs, or is obtrusively + long:: + + But still, that's nothing compared to a name like + |j2ee-cas|__. + + .. |j2ee-cas| replace:: + the Java `TM`:super: 2 Platform, Enterprise Edition Client + Access Services + __ http://developer.java.sun.com/developer/earlyAccess/ + j2eecas/ + + +Comments +```````` + +DTD element: comment. + +Arbitrary indented text may follow the explicit markup start and will +be processed as a comment element. No further processing is done on +the comment block text; a comment contains a single "text blob". +Depending on the output formatter, comments may be removed from the +processed output. The only restriction on comments is that they not +use the same syntax as directives, footnotes, citations, or hyperlink +targets. + +A explicit markup start followed by a blank line and nothing else +(apart from whitespace) is an "empty comment". It serves to terminate +a preceding construct, and does **not** consume any indented text +following. To have a block quote follow a list or any indented +construct, insert an unindented empty comment in-between. + +Syntax diagram:: + + +-------+----------------------+ + | ".. " | comment | + +-------+ block | + | | + +----------------------+ + + +Implicit Hyperlink Targets +========================== + +Implicit hyperlink targets are generated by section titles, footnotes, +and citations, and may also be generated by extension constructs. +Implicit hyperlink targets otherwise behave identically to explicit +`hyperlink targets`_. + +Problems of ambiguity due to conflicting duplicate implicit and +explicit reference names are avoided by following this procedure: + +1. `Explicit hyperlink targets`_ override any implicit targets having + the same reference name. The implicit hyperlink targets are + removed, and level-1 (info) system messages are inserted. + +2. Duplicate implicit hyperlink targets are removed, and level-1 + (info) system messages inserted. For example, if two or more + sections have the same title (such as "Introduction" subsections of + a rigidly-structured document), there will be duplicate implicit + hyperlink targets. + +3. Duplicate explicit hyperlink targets are removed, and level-2 + (warning) system messages are inserted. Exception: duplicate + `external hyperlink targets`_ (identical hyperlink names and + referenced URIs) do not conflict, and are not removed. + +System messages are inserted where target links have been removed. +See "Error Handling" in `PEP 258`_. + +The parser must return a set of *unique* hyperlink targets. The +calling software (such as the Docutils_) can warn of unresolvable +links, giving reasons for the messages. + + +Inline Markup +============= + +In reStructuredText, inline markup applies to words or phrases within +a text block. The same whitespace and punctuation that serves to +delimit words in written text is used to delimit the inline markup +syntax constructs. The text within inline markup may not begin or end +with whitespace. Arbitrary character-level markup is not supported; +it is not possible to mark up individual characters within a word. +Inline markup cannot be nested. + +There are nine inline markup constructs. Five of the constructs use +identical start-strings and end-strings to indicate the markup: + +- emphasis_: "*" +- `strong emphasis`_: "**" +- `interpreted text`_: "`" +- `inline literals`_: "``" +- `substitution references`_: "|" + +Three constructs use different start-strings and end-strings: + +- `inline hyperlink targets`_: "_`" and "`" +- `footnote references`_: "[" and "]_" +- `hyperlink references`_: "`" and "\`_" (phrases), or just a + trailing "_" (single words) + +`Standalone hyperlinks`_ are recognized implicitly, and use no extra +markup. + +The inline markup start-string and end-string recognition rules are as +follows. If any of the conditions are not met, the start-string or +end-string will not be recognized or processed. + +1. Inline markup start-strings must start a text block or be + immediately preceded by whitespace, single or double quotes, "(", + "[", "{", or "<". + +2. Inline markup start-strings must be immediately followed by + non-whitespace. + +3. Inline markup end-strings must be immediately preceded by + non-whitespace. + +4. Inline markup end-strings must end a text block or be immediately + followed by whitespace or one of:: + + ' " . , : ; ! ? - ) ] } > + +5. If an inline markup start-string is immediately preceded by a + single or double quote, "(", "[", "{", or "<", it must not be + immediately followed by the corresponding single or double quote, + ")", "]", "}", or ">". + +6. An inline markup end-string must be separated by at least one + character from the start-string. + +7. An unescaped backslash preceding a start-string or end-string will + disable markup recognition, except for the end-string of `inline + literals`_. See `Escaping Mechanism`_ above for details. + +For example, none of the following are recognized as containing inline +markup start-strings: " * ", '"*"', "'*'", "(*)", "(* ", "[*]", "{*}", +"\*", " ` ", etc. + +The inline markup recognition rules were devised intentionally to +allow 90% of non-markup uses of "*", "`", "_", and "|" *without* +resorting to backslashes. For 9 of the remaining 10%, use inline +literals or literal blocks:: + + "``\*``" -> "\*" (possibly in another font or quoted) + +Only those who understand the escaping and inline markup rules should +attempt the remaining 1%. ;-) + +Inline markup delimiter characters are used for multiple constructs, +so to avoid ambiguity there must be a specific recognition order for +each character. The inline markup recognition order is as follows: + +- Asterisks: `Strong emphasis`_ ("**") is recognized before emphasis_ + ("*"). + +- Backquotes: `Inline literals`_ ("``"), `inline hyperlink targets`_ + (leading "_`", trailing "`"), are mutually independent, and are + recognized before phrase `hyperlink references`_ (leading "`", + trailing "\`_") and `interpreted text`_ ("`"). + +- Trailing underscores: Footnote references ("[" + label + "]_") and + simple `hyperlink references`_ (name + trailing "_") are mutually + independent. + +- Vertical bars: `Substitution references`_ ("|") are independently + recognized. + +- `Standalone hyperlinks`_ are the last to be recognized. + + +Emphasis +-------- + +DTD element: emphasis. + +Start-string = end-string = "*". + +Text enclosed by single asterisk characters is emphasized:: + + This is *emphasized text*. + +Emphasized text is typically displayed in italics. + + +Strong Emphasis +--------------- + +DTD element: strong. + +Start-string = end-string = "**". + +Text enclosed by double-asterisks is emphasized strongly:: + + This is **strong text**. + +Strongly emphasized text is typically displayed in boldface. + + +Interpreted Text +---------------- + +DTD element: interpreted. + +Start-string = end-string = "`". + +Text enclosed by single backquote characters is interpreted:: + + This is `interpreted text`. + +Interpreted text is text that is meant to be related, indexed, linked, +summarized, or otherwise processed, but the text itself is left +alone. The text is "tagged" directly, in-place. The semantics of +interpreted text are domain-dependent. It can be used as implicit or +explicit descriptive markup (such as for program identifiers, as in +the `Python Source Reader`_), for cross-reference interpretation (such +as index entries), or for other applications where context can be +inferred. + +The role of the interpreted text determines how the text is +interpreted. It is normally inferred implicitly. The role of the +interpreted text may also be indicated explicitly, using a role +marker, either as a prefix or as a suffix to the interpreted text, +depending on which reads better:: + + :role:`interpreted text` + + `interpreted text`:role: + +Roles are simply extensions of the available inline constructs; to +emphasis_, `strong emphasis`_, `inline literals`_, and `hyperlink +references`_, we can add "index entry", "acronym", "class", "red", +"blinking" or anything else we want. + +A role marker consists of a colon, the role name, and another colon. +A role name is a single word consisting of alphanumerics plus internal +hypens, underscores, and periods; no whitespace or other characters +are allowed. + + +Inline Literals +--------------- + +DTD element: literal. + +Start-string = end-string = "``". + +Text enclosed by double-backquotes is treated as inline literals:: + + This text is an example of ``inline literals``. + +Inline literals may contain any characters except two adjacent +backquotes in an end-string context (according to the recognition +rules above). No markup interpretation (including backslash-escape +interpretation) is done within inline literals. + +Line breaks are *not* preserved in inline literals. Although a +reStructuredText parser will preserve runs of spaces in its output, +the final representation of the processed document is dependent on the +output formatter, thus the preservation of whitespace cannot be +guaranteed. If the preservation of line breaks and/or other +whitespace is important, `literal blocks`_ should be used. + +Inline literals are useful for short code snippets. For example:: + + The regular expression ``[+-]?(\d+(\.\d*)?|\.\d+)`` matches + floating-point numbers (without exponents). + + +Hyperlink References +-------------------- + +DTD element: reference. + +- Named hyperlink references: + + - Start-string = "" (empty string), end-string = "_". + - Start-string = "`", end-string = "\`_". (Phrase references.) + +- Anonymous hyperlink references: + + - Start-string = "" (empty string), end-string = "__". + - Start-string = "`", end-string = "\`__". (Phrase references.) + +Hyperlink references are indicated by a trailing underscore, "_", +except for `standalone hyperlinks`_ which are recognized +independently. The underscore can be thought of as a right-pointing +arrow. The trailing underscores point away from hyperlink references, +and the leading underscores point toward `hyperlink targets`_. + +Hyperlinks consist of two parts. In the text body, there is a source +link, a reference name with a trailing underscore (or two underscores +for `anonymous hyperlinks`_):: + + See the Python_ home page for info. + +A target link with a matching reference name must exist somewhere else +in the document. See `Hyperlink Targets`_ for a full description). + +`Anonymous hyperlinks`_ (which see) do not use reference names to +match references to targets, but otherwise behave similarly to named +hyperlinks. + + +Inline Hyperlink Targets +------------------------ + +DTD element: target. + +Start-string = "_`", end-string = "`". + +Inline hyperlink targets are the equivalent of explicit `internal +hyperlink targets`_, but may appear within running text. The syntax +begins with an underscore and a backquote, is followed by a hyperlink +name or phrase, and ends with a backquote. Inline hyperlink targets +may not be anonymous. + +For example, the following paragraph contains a hyperlink target named +"Norwegian Blue":: + + Oh yes, the _`Norwegian Blue`. What's, um, what's wrong with it? + +See `Implicit Hyperlink Targets`_ for the resolution of duplicate +reference names. + + +Footnote References +------------------- + +DTD element: footnote_reference. + +Start-string = "[", end-string = "]_". + +Each footnote reference consists of a square-bracketed label followed +by a trailing underscore. Footnote labels are one of: + +- one or more digits (i.e., a number), + +- a single "#" (denoting `auto-numbered footnotes`_), + +- a "#" followed by a simple reference name (an `autonumber label`_), + or + +- a single "*" (denoting `auto-symbol footnotes`_). + +For example:: + + Please RTFM [1]_. + + .. [1] Read The Fine Manual + + +Citation References +------------------- + +DTD element: citation_reference. + +Start-string = "[", end-string = "]_". + +Each citation reference consists of a square-bracketed label followed +by a trailing underscore. Citation labels are simple `reference +names`_ (case-insensitive single words, consisting of alphanumerics +plus internal hyphens, underscores, and periods; no whitespace). + +For example:: + + Here is a citation reference: [CIT2002]_. + +See Citations_ for the citation itself. + + +Substitution References +----------------------- + +DTD element: substitution_reference, reference. + +Start-string = "|", end-string = "|" (optionally followed by "_" or +"__"). + +Vertical bars are used to bracket the substitution reference text. A +substitution reference may also be a hyperlink reference by appending +a "_" (named) or "__" (anonymous) suffix; the substitution text is +used for the reference text in the named case. + +The processing system replaces substitution references with the +processed contents of the corresponding `substitution definitions`_. +Substitution definitions produce inline-compatible elements. + +Examples:: + + This is a simple |substitution reference|. It will be replaced by + the processing system. + + This is a combination |substitution and hyperlink reference|_. In + addition to being replaced, the replacement text or element will + refer to the "substitution and hyperlink reference" target. + + +Standalone Hyperlinks +--------------------- + +DTD element: link. + +Start-string = end-string = "" (empty string). + +A URI (absolute URI [#URI]_ or standalone email address) within a text +block is treated as a general external hyperlink with the URI itself +as the link's text. For example:: + + See http://www.python.org for info. + +would be marked up in HTML as:: + + See <A HREF="http://www.python.org">http://www.python.org</A> for + info. + +Two forms of URI are recognized: + +1. Absolute URIs. These consist of a scheme, a colon (":"), and a + scheme-specific part whose interpretation depends on the scheme. + + The scheme is the name of the protocol, such as "http", "ftp", + "mailto", or "telnet". The scheme consists of an initial letter, + followed by letters, numbers, and/or "+", "-", ".". Recognition is + limited to known schemes, per the W3C's `Index of WWW Addressing + Schemes`_. + + The scheme-specific part of the resource identifier may be either + hierarchical or opaque: + + - Hierarchical identifiers begin with one or two slashes and may + use slashes to separate hierarchical components of the path. + Examples are web pages and FTP sites:: + + http://www.python.org + + ftp://ftp.python.org/pub/python + + - Opaque identifiers do not begin with slashes. Examples are + email addresses and newsgroups:: + + mailto:someone@somewhere.com + + news:comp.lang.python + + With queries, fragments, and %-escape sequences, URIs can become + quite complicated. A reStructuredText parser must be able to + recognize any absolute URI, as defined in RFC2396_ and RFC2732_. + +2. Standalone email addresses, which are treated as if they were + ablsolute URIs with a "mailto:" scheme. Example:: + + someone@somewhere.com + +Punctuation at the end of a URI is not considered part of the URI. + +.. [#URI] Uniform Resource Identifier. URIs are a general form of + URLs (Uniform Resource Locators). For the syntax of URIs see + RFC2396_ and RFC2732_. + + +---------------- + Error Handling +---------------- + +DTD element: system_message, problematic. + +Markup errors are handled according to the specification in `PEP +258`_. + + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _Docutils: http://docutils.sourceforge.net/ +.. _Docutils Document Tree Structure: + http://docutils.sourceforge.net/spec/doctree.txt +.. _Generic Plaintext Document Interface DTD: + http://docutils.sourceforge.net/spec/gpdi.dtd +.. _transforms: + http://docutils.sourceforge.net/docutils/transforms/ +.. _Grouch: http://www.mems-exchange.org/software/grouch/ +.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt +.. _DocTitle transform: +.. _DocInfo transform: + http://docutils.sourceforge.net/docutils/transforms/frontmatter.py +.. _doctest module: + http://www.python.org/doc/current/lib/module-doctest.html +.. _getopt.py: + http://www.python.org/doc/current/lib/module-getopt.html +.. _GNU libc getopt_long(): + http://www.gnu.org/manual/glibc-2.2.3/html_node/libc_516.html +.. _Index of WWW Addressing Schemes: + http://www.w3.org/Addressing/schemes.html +.. _World Wide Web Consortium: http://www.w3.org/ +.. _HTML Techniques for Web Content Accessibility Guidelines: + http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text +.. _reStructuredText Directives: directives.html +.. _Python Source Reader: + http://docutils.sourceforge.net/spec/pysource.txt +.. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt +.. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt +.. _Zope: http://www.zope.com/ +.. _PEP 258: http://docutils.sourceforge.net/spec/pep-0258.txt + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/docs/ref/soextblx.dtd b/docs/ref/soextblx.dtd new file mode 100644 index 000000000..56ba311ba --- /dev/null +++ b/docs/ref/soextblx.dtd @@ -0,0 +1,312 @@ +<!-- +=========================================================================== + OASIS XML Exchange Table Model Declaration Module +=========================================================================== +:Date: 1999-03-15 +--> + +<!-- This set of declarations defines the XML version of the Exchange + Table Model as of the date shown in the Formal Public Identifier + (FPI) for this entity. + + This set of declarations may be referred to using a public external + entity declaration and reference as shown in the following three + lines: + + <!ENTITY % calstblx + PUBLIC "-//OASIS//DTD XML Exchange Table Model 19990315//EN"> + %calstblx; + + If various parameter entities used within this set of declarations + are to be given non-default values, the appropriate declarations + should be given before calling in this package (i.e., before the + "%calstblx;" reference). +--> + +<!-- The motivation for this XML version of the Exchange Table Model + is simply to create an XML version of the SGML Exchange Table + Model. By design, no effort has been made to "improve" the model. + + This XML version incorporates the logical bare minimum changes + necessary to make the Exchange Table Model a valid XML DTD. +--> + +<!-- The XML version of the Exchange Table Model differs from + the SGML version in the following ways: + + The following parameter entities have been removed: + + - tbl.table.excep, tbl.hdft.excep, tbl.row.excep, tbl.entry.excep + There are no exceptions in XML. The following normative statement + is made in lieu of exceptions: the exchange table model explicitly + forbids a table from occurring within another table. If the + content model of an entry includes a table element, then this + cannot be enforced by the DTD, but it is a deviation from the + exchange table model to include a table within a table. + + - tbl.hdft.name, tbl.hdft.mdl, tbl.hdft.excep, tbl.hdft.att + The motivation for these elements was to change the table + header/footer elements. Since XML does not allow element declarations + to contain name groups, and the exchange table model does not + allow a table to contain footers, the continued presence of these + attributes seems unnecessary. + + The following parameter entity has been added: + + - tbl.thead.att + This entity parameterizes the attributes on thead. It replaces + the tbl.hdft.att parameter entity. + + Other miscellaneous changes: + + - Tag ommission indicators have been removed + - Comments have been removed from declarations + - NUMBER attributes have been changed to NMTOKEN + - NUTOKEN attributes have been to changed to NMTOKEN + - Removed the grouping characters around the content model + parameter entry for the 'entry' element. This is necessary + so that an entry can contain #PCDATA and be defined as an + optional, repeatable OR group beginning with #PCDATA. +--> + +<!-- This entity includes a set of element and attribute declarations + that partially defines the Exchange table model. However, the model + is not well-defined without the accompanying natural language + description of the semantics (meanings) of these various elements, + attributes, and attribute values. The semantic writeup, also available + from SGML Open, should be used in conjunction with this entity. +--> + +<!-- In order to use the Exchange table model, various parameter entity + declarations are required. A brief description is as follows: + + ENTITY NAME WHERE USED WHAT IT IS + + %yesorno In ATTLIST of: An attribute declared value + almost all elements for a "boolean" attribute + + %paracon In content model of: The "text" (logical content) + <entry> of the model group for <entry> + + %titles In content model of: The "title" part of the model + table element group for the table element + + %tbl.table.name In declaration of: The name of the "table" + table element element + + %tbl.table-titles.mdl In content model of: The model group for the title + table elements part of the content model for + table element + + %tbl.table.mdl In content model of: The model group for the content + table elements model for table element, + often (and by default) defined + in terms of %tbl.table-titles.mdl + and tgroup + + %tbl.table.att In ATTLIST of: Additional attributes on the + table element table element + + %bodyatt In ATTLIST of: Additional attributes on the + table element table element (for backward + compatibility with the SGML + model) + + %tbl.tgroup.mdl In content model of: The model group for the content + <tgroup> model for <tgroup> + + %tbl.tgroup.att In ATTLIST of: Additional attributes on the +4 <tgroup> <tgroup> element + + %tbl.thead.att In ATTLIST of: Additional attributes on the + <thead> <thead> element + + %tbl.tbody.att In ATTLIST of: Additional attributes on the + <tbody> <tbody> element + + %tbl.colspec.att In ATTLIST of: Additional attributes on the + <colspec> <colspec> element + + %tbl.row.mdl In content model of: The model group for the content + <row> model for <row> + + %tbl.row.att In ATTLIST of: Additional attributes on the + <row> <row> element + + %tbl.entry.mdl In content model of: The model group for the content + <entry> model for <entry> + + %tbl.entry.att In ATTLIST of: Additional attributes on the + <entry> <entry> element + + This set of declarations will use the default definitions shown below + for any of these parameter entities that are not declared before this + set of declarations is referenced. +--> + +<!-- These definitions are not directly related to the table model, but are + used in the default CALS table model and may be defined elsewhere (and + prior to the inclusion of this table module) in the referencing DTD. --> + +<!ENTITY % yesorno 'NMTOKEN'> <!-- no if zero(s), yes if any other value --> +<!ENTITY % titles 'title?'> +<!ENTITY % paracon '#PCDATA'> <!-- default for use in entry content --> + +<!-- +The parameter entities as defined below change and simplify the CALS table +model as published (as part of the Example DTD) in MIL-HDBK-28001. The +resulting simplified DTD has support from the SGML Open vendors and is +therefore more interoperable among different systems. + +These following declarations provide the Exchange default definitions +for these entities. However, these entities can be redefined (by giving +the appropriate parameter entity declaration(s) prior to the reference +to this Table Model declaration set entity) to fit the needs of the +current application. + +Note, however, that changes may have significant effect on the ability to +interchange table information. These changes may manifest themselves +in useability, presentation, and possible structure information degradation. +--> + +<!ENTITY % tbl.table.name "table"> +<!ENTITY % tbl.table-titles.mdl "%titles;,"> +<!ENTITY % tbl.table-main.mdl "tgroup+"> +<!ENTITY % tbl.table.mdl "%tbl.table-titles.mdl; %tbl.table-main.mdl;"> +<!ENTITY % tbl.table.att " + pgwide %yesorno; #IMPLIED "> +<!ENTITY % bodyatt ""> +<!ENTITY % tbl.tgroup.mdl "colspec*,thead?,tbody"> +<!ENTITY % tbl.tgroup.att ""> +<!ENTITY % tbl.thead.att ""> +<!ENTITY % tbl.tbody.att ""> +<!ENTITY % tbl.colspec.att ""> +<!ENTITY % tbl.row.mdl "entry+"> +<!ENTITY % tbl.row.att ""> +<!ENTITY % tbl.entry.mdl "(%paracon;)*"> +<!ENTITY % tbl.entry.att ""> + +<!-- ===== Element and attribute declarations follow. ===== --> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.table.name "table" + ENTITY % tbl.table-titles.mdl "%titles;," + ENTITY % tbl.table.mdl "%tbl.table-titles; tgroup+" + ENTITY % tbl.table.att " + pgwide %yesorno; #IMPLIED " +--> + +<!ELEMENT %tbl.table.name; (%tbl.table.mdl;)> + +<!ATTLIST %tbl.table.name; + frame (top|bottom|topbot|all|sides|none) #IMPLIED + colsep %yesorno; #IMPLIED + rowsep %yesorno; #IMPLIED + %tbl.table.att; + %bodyatt; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.tgroup.mdl "colspec*,thead?,tbody" + ENTITY % tbl.tgroup.att "" +--> + +<!ELEMENT tgroup (%tbl.tgroup.mdl;) > + +<!ATTLIST tgroup + cols NMTOKEN #REQUIRED + colsep %yesorno; #IMPLIED + rowsep %yesorno; #IMPLIED + align (left|right|center|justify|char) #IMPLIED + %tbl.tgroup.att; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.colspec.att "" +--> + +<!ELEMENT colspec EMPTY > + +<!ATTLIST colspec + colnum NMTOKEN #IMPLIED + colname NMTOKEN #IMPLIED + colwidth CDATA #IMPLIED + colsep %yesorno; #IMPLIED + rowsep %yesorno; #IMPLIED + align (left|right|center|justify|char) #IMPLIED + char CDATA #IMPLIED + charoff NMTOKEN #IMPLIED + %tbl.colspec.att; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.thead.att "" +--> + +<!ELEMENT thead (row+)> + +<!ATTLIST thead + valign (top|middle|bottom) #IMPLIED + %tbl.thead.att; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.tbody.att "" +--> + +<!ELEMENT tbody (row+)> + +<!ATTLIST tbody + valign (top|middle|bottom) #IMPLIED + %tbl.tbody.att; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.row.mdl "entry+" + ENTITY % tbl.row.att "" +--> + +<!ELEMENT row (%tbl.row.mdl;)> + +<!ATTLIST row + rowsep %yesorno; #IMPLIED + valign (top|middle|bottom) #IMPLIED + %tbl.row.att; +> + + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % paracon "#PCDATA" + ENTITY % tbl.entry.mdl "(%paracon;)*" + ENTITY % tbl.entry.att "" +--> + +<!ELEMENT entry %tbl.entry.mdl;> + +<!ATTLIST entry + colname NMTOKEN #IMPLIED + namest NMTOKEN #IMPLIED + nameend NMTOKEN #IMPLIED + morerows NMTOKEN #IMPLIED + colsep %yesorno; #IMPLIED + rowsep %yesorno; #IMPLIED + align (left|right|center|justify|char) #IMPLIED + char CDATA #IMPLIED + charoff NMTOKEN #IMPLIED + valign (top|middle|bottom) #IMPLIED + %tbl.entry.att; +> -- cgit v1.2.1 From 8233789d399195a3d502385780aa5f4e8ad29a25 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 25 Apr 2002 03:32:59 +0000 Subject: - Clarified field list usage. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@39 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 149ef3fd4..f352c9716 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -738,6 +738,14 @@ Field Lists DTD elements: field_list, field, field_name, field_argument, field_body. +Field lists are most often used as part of an extension syntax, such +as attributes for directives_, or database-like fields meant for +further processing. They are not intended to be an alternative to +definition lists. Applications of reStructuredText may recognize +field names and transform fields or field bodies in certain contexts. +See `Bibliographic Fields`_ below for one example, or the "image" +directive in `reStructuredText Directives`_ for another. + Field lists are mappings from field names to field bodies, modeled on RFC822_ headers. A field name is made up of one or more letters, numbers, and punctuation, except colons (":") and whitespace. Field @@ -772,12 +780,6 @@ The syntax for field arguments may be extended in the future. For example, quoted phrases may be treated as a single argument, and direct support for the "name=value" syntax may be added. -Applications of reStructuredText may recognize field names and -transform fields or field bodies in certain contexts; they are often -used as part of an extension syntax. See `Bibliographic Fields`_ -below for one example, or the "image" directive in `reStructuredText -Directives`_ for another. - Standard RFC822 headers cannot be used for this construct because they are ambiguous. A word followed by a colon at the beginning of a line is common in written text. However, in well-defined contexts such as -- cgit v1.2.1 From 29e9868d5635c52603e8101344cf26169bfa5328 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 30 Apr 2002 02:20:57 +0000 Subject: - Field lists' field_body may be empty. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@54 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index d47238b4d..9f3d1836a 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -302,7 +302,8 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT field_argument (#PCDATA)> <!ATTLIST field_argument %basic.atts;> -<!ELEMENT field_body (%body.elements;)+> +<!-- May be empty. --> +<!ELEMENT field_body (%body.elements;)*> <!ATTLIST field_body %basic.atts;> <!ELEMENT option_list (option_list_item+)> -- cgit v1.2.1 From b5f1e2618bd540436686dc1593d2c398b9558f00 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 30 Apr 2002 02:22:22 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@55 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 6 +++--- docs/ref/rst/restructuredtext.txt | 22 +++++++++++++--------- 2 files changed, 16 insertions(+), 12 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index cbb8b4609..8012ee9ed 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -157,9 +157,9 @@ legend. To specify a legend without a caption, use an empty comment ("..") in place of the caption. ---------------------- - Document Components ---------------------- +---------------- + Document Parts +---------------- Table of Contents ================= diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index f352c9716..37b53f784 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -648,23 +648,27 @@ The following formatting types are recognized: - surrounded by parentheses: "(1)", "(A)", "(a)", "(I)", "(i)". - suffixed with a right-parenthesis: "1)", "A)", "a)", "I)", "i)". -A system message will be generated for each of the following cases: +While parsing an enumerated list, a new list will be started whenever: -- The enumerators do not all have the same format and sequence type. +- An enumerator is encountered which does not have the same format and + sequence type as the current list (e.g. "1.", "(a)" produces two + separate lists). -- The enumerators are not in sequence (i.e., "1.", "3." generates a - level-1 [info] system message and produces two separate lists). +- The enumerators are not in sequence (e.g., "1.", "3." produces two + separate lists). It is recommended that the enumerator of the first list item be ordinal-1 ("1", "A", "a", "I", or "i"). Although other start-values -will be recognized, they may not be supported by the output format. +will be recognized, they may not be supported by the output format. A +level-1 [info] system message will be generated for any list beginning +with a non-ordinal-1 enumerator. Lists using Roman numerals must begin with "I"/"i" or a multi-character value, such as "II" or "XV". Any other -single-character Roman numeral ("V", "X", etc.) will be interpreted as -a letter of the alphabet, not as a Roman numeral. Likewise, lists -using letters of the alphabet may not begin with "I"/"i", since these -are recognized as Roman numeral 1. +single-character Roman numeral ("V", "X", "L", "C", "D", "M") will be +interpreted as a letter of the alphabet, not as a Roman numeral. +Likewise, lists using letters of the alphabet may not begin with +"I"/"i", since these are recognized as Roman numeral 1. Nested enumerated lists must be created with indentation. For example:: -- cgit v1.2.1 From 6b21c047594ea25b4fa75f903e9b315859735116 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 5 May 2002 17:06:02 +0000 Subject: fixed hyperlinks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@97 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/introduction.txt | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index 3d7cfc5f8..4ffb2d053 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -294,7 +294,6 @@ followed. .. _comp.lang.python: news:comp.lang.python .. _Python-dev: http://mail.python.org/pipermail/python-dev/ .. _Docstring Processing System: http://docstring.sourceforge.net/ -.. _Docutils: http://docutils.sourceforge.net/ .. _master PEP repository: http://www.python.org/peps/ -- cgit v1.2.1 From 77568921276db01c972cb1ee4dd8b42d7bf1b7a6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 May 2002 03:50:05 +0000 Subject: - Clarified purpose of directives. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@116 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 66 +++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 34 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 37b53f784..07c16ccd5 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1581,6 +1581,26 @@ Directives DTD elements: depend on the directive. +Directives are an extension mechanism for reStructuredText, a way of +adding support for new constructs without adding new syntax. +Directives which have been implemented and registered in the reference +reStructuredText parser are described in the `reStructuredText +Directives`_ document. For example, here's how an image may be +placed:: + + .. image:: mylogo.png + +A figure (a graphic with a caption) may placed like this:: + + .. figure:: larch.png + The larch. + +An admonition (note, caution, etc.) contains other body elements:: + + .. note:: This is a paragraph + + - Here is a bullet list. + Directives are indicated by an explicit markup start (".. ") followed by the directive type, two colons, and whitespace. Directive types are case-insensitive single words (alphanumerics plus internal @@ -1609,42 +1629,20 @@ interpreted as a directive block. Simple directives may not require any text beyond the directive data (if that), and will not process any following indented text. -Directives which have been implemented and registered in the reference -reStructuredText parser are described in the `reStructuredText -Directives`_ document. Below are examples of implemented directives. - Directives are meant for the arbitrary processing of their contents (the directive data & text block), which can be transformed into -something possibly unrelated to the original text. Directives are -used as an extension mechanism for reStructuredText, a way of adding -support for new constructs without adding new syntax. For example, -here's how an image may be placed:: - - .. image:: mylogo.png - -A figure (a graphic with a caption) may placed like this:: - - .. figure:: larch.png - The larch. - -An admonition (note, caution, etc.) contains other body elements:: - - .. note:: This is a paragraph - - - Here is a bullet list. - -It may also be possible for directives to be used as pragmas, to -modify the behavior of the parser, such as to experiment with -alternate syntax. There is no parser support for this functionality -at present; if a reasonable need for pragma directives is found, they -may be supported. - -Directives normally do not survive as "directive" elements past the -parsing stage; they are a *parser construct* only, and have no -intrinsic meaning outside of reStructuredText. Instead, the parser -will transform recognized directives into (possibly specialized) -document elements. Unknown directives will trigger level-3 (error) -system messages. +something possibly unrelated to the original text. It may also be +possible for directives to be used as pragmas, to modify the behavior +of the parser, such as to experiment with alternate syntax. There is +no parser support for this functionality at present; if a reasonable +need for pragma directives is found, they may be supported. + +Directives do not survive as "directive" elements past the parsing +stage; they are a *parser construct* only, and have no intrinsic +meaning outside of reStructuredText. Instead, the parser will +transform recognized directives into (possibly specialized) document +elements. Unknown directives will trigger level-3 (error) system +messages. Syntax diagram:: -- cgit v1.2.1 From 8f2153983e79ea721ea895853f12746eb824b58f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 11 May 2002 16:45:40 +0000 Subject: more directive clarification git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@121 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 07c16ccd5..32d03f7ea 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1582,11 +1582,14 @@ Directives DTD elements: depend on the directive. Directives are an extension mechanism for reStructuredText, a way of -adding support for new constructs without adding new syntax. -Directives which have been implemented and registered in the reference -reStructuredText parser are described in the `reStructuredText -Directives`_ document. For example, here's how an image may be -placed:: +adding support for new constructs without adding new syntax. All +standard directives (those implemented and registered in the reference +reStructuredText parser) are described in the `reStructuredText +Directives`_ document, and are always available. Any other directives +are domain-specific, and may require special action to make them +available when processing the document. + +For example, here's how an image may be placed:: .. image:: mylogo.png -- cgit v1.2.1 From c9957ebcea78d02fcc2c316e4c902fdf83031c09 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 11 May 2002 18:38:10 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@123 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 32d03f7ea..31c22a184 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1596,6 +1596,7 @@ For example, here's how an image may be placed:: A figure (a graphic with a caption) may placed like this:: .. figure:: larch.png + The larch. An admonition (note, caution, etc.) contains other body elements:: -- cgit v1.2.1 From c95927c8ddb04d0b89e84311ff5f0eb9f953f9f7 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 30 May 2002 02:07:32 +0000 Subject: - Added ``-/:`` characters to inline markup's start string prefix, ``/`` to end string suffix. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@147 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 31c22a184..3d90489d4 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1948,8 +1948,9 @@ follows. If any of the conditions are not met, the start-string or end-string will not be recognized or processed. 1. Inline markup start-strings must start a text block or be - immediately preceded by whitespace, single or double quotes, "(", - "[", "{", or "<". + immediately preceded by whitespace or one of:: + + ' " ( [ { < - / : 2. Inline markup start-strings must be immediately followed by non-whitespace. @@ -1960,7 +1961,7 @@ end-string will not be recognized or processed. 4. Inline markup end-strings must end a text block or be immediately followed by whitespace or one of:: - ' " . , : ; ! ? - ) ] } > + ' " ) ] } > - / : . , ; ! ? 5. If an inline markup start-string is immediately preceded by a single or double quote, "(", "[", "{", or "<", it must not be -- cgit v1.2.1 From 7608caed8e3ec8e027810d7509121697a5e981b0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 1 Jun 2002 01:35:59 +0000 Subject: - Added ``decoration``, ``header``, and ``footer`` elements. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@167 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 9f3d1836a..856f3c13e 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -174,7 +174,7 @@ http://www.oasis-open.org/html/tm9901.htm). <!-- Optional elements may be generated by internal processing. --> <!ELEMENT document - ((title, subtitle?)?, docinfo?, %structure.model;)> + ((title, subtitle?)?, docinfo?, decoration?, %structure.model;)> <!ATTLIST document %basic.atts;> @@ -231,6 +231,22 @@ http://www.oasis-open.org/html/tm9901.htm). <!ATTLIST copyright %basic.atts;> +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Decoration Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!ELEMENT decoration (header?, footer?)> +<!ATTLIST decoration %basic.atts;> + +<!ELEMENT header (%body.elements;)+> +<!ATTLIST header %basic.atts;> + +<!ELEMENT footer (%body.elements;)+> +<!ATTLIST footer %basic.atts;> + + <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Structural Elements -- cgit v1.2.1 From 8c4fa064a323de3e1d4aba4e853fd004e3e08914 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 27 Jun 2002 01:23:17 +0000 Subject: - Brought ``interpreted`` element in line with the parser: changed attribute "type" to "role", added "position". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@211 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 856f3c13e..80e54b084 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -112,7 +112,7 @@ resolve to either an internal or external reference. <!ENTITY % additional.body.elements ""> <!ENTITY % body.elements - " paragraph | literal_block | block_quote | doctest_block| table + " paragraph | literal_block | block_quote | doctest_block | table | figure | image | footnote | citation | bullet_list | enumerated_list | definition_list | field_list | option_list @@ -489,7 +489,8 @@ following caveats: <!ELEMENT interpreted (%text.model;)> <!ATTLIST interpreted %basic.atts; - type CDATA #IMPLIED> + role CDATA #IMPLIED + position (prefix | suffix) #IMPLIED> <!ELEMENT literal (#PCDATA)> <!ATTLIST literal %basic.atts;> -- cgit v1.2.1 From 7169009358ab112b33e8c0fb9d37ff902eb0892c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 27 Jun 2002 01:26:55 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@214 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 90aea7054..89b222f6f 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -21,7 +21,7 @@ one-to-many relationships; sections may contain (sub)sections, tables contain further body elements, etc. :: +--------------------------------------------------------------------+ - | document [may begin with a title, subtitle, docinfo] | + | document [may begin with a title, subtitle, docinfo, decoration] | | +--------------------------------------+ | | sections [each begins with a title] | +-----------------------------+-------------------------+------------+ @@ -41,11 +41,12 @@ contain further body elements, etc. :: Element Hierarchy ------------------- -A class hierarchy has been implemented in nodes.py where the position -of the element (the level at which it can occur) is significant. -E.G., Root, Structural, Body, Inline classes etc. Certain -transformations will be easier because we can use isinstance() on -them. +A class hierarchy has been implemented in nodes.py. The position of +each node (the level at which it can occur) is significant and is +represented by abstract base classes (Root, Structural, Body, Inline, +etc.). Certain transformations will be easier because we can use +``isinstance(node, base_class)`` to determine the position of the node +in the hierarchy. The elements making up Docutils document trees can be categorized into the following groups: -- cgit v1.2.1 From 6adf8d5e25be90964f922d5c9e5ca48aa9e7ac52 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 29 Jun 2002 00:44:58 +0000 Subject: changed the title git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@228 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 89b222f6f..e58a4f306 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1,6 +1,6 @@ -================================== - Docutils Document Tree Structure -================================== +============================ + The Docutils Document Tree +============================ :Author: David Goodger :Contact: goodger@users.sourceforge.net :Revision: $Revision$ -- cgit v1.2.1 From d0307b9ca6000b9b67a36d628b5d0fc9b83c5762 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 1 Jul 2002 13:58:31 +0000 Subject: not just PNG! git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@237 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- docs/ref/rst/restructuredtext.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 8012ee9ed..d39f488c3 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -96,7 +96,7 @@ 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 + .. image:: picture.jpeg :height: 100 :width: 200 :scale: 50 diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 3d90489d4..e26ce2a21 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1591,7 +1591,7 @@ available when processing the document. For example, here's how an image may be placed:: - .. image:: mylogo.png + .. image:: mylogo.jpeg A figure (a graphic with a caption) may placed like this:: -- cgit v1.2.1 From 7f5c468171236cb0dd3a7f5301ec1c931c0e88f4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 6 Jul 2002 03:04:57 +0000 Subject: Added "Hyperlink Bookkeeping" section. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@257 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index e58a4f306..476c57868 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -234,6 +234,45 @@ The ``%text.model;`` parameter entity Appendix: Miscellaneous Topics -------------------------------- +Hyperlink Bookkeeping +===================== + +``document.nameids`` maps names to IDs, while ``document.nametypes`` +maps names to booleans representing hyperlink type (True==explicit, +False==implicit). The ``document.set_name_id_map()`` method updates +the mappings. + +The following state transition table shows how ``nameids`` ("ids") and +``nametypes`` ("types") change with new input (a call to +``document.set_name_id_map()``), and what actions are performed:: + + ==== ===== ======== ======== ======= ==== ===== ===== + Old State Input Action New State Notes + ----------- -------- ----------------- ----------- + ids types new type sys.msg. dupname ids types + ==== ===== ======== ======== ======= ==== ===== ===== + -- -- explicit -- -- new True + -- -- implicit -- -- new False + None False explicit -- -- new True + old False explicit implicit old new True + None True explicit explicit new None True + old True explicit explicit new,old None True [1] + None False implicit implicit new None False + old False implicit implicit new,old None False + None True implicit implicit new None True + old True implicit implicit new old True + ==== ===== ======== ======== ======= ==== ===== ===== + +Note 1: Do not clear the name->id map or invalidate the old target if +both old and new targets are external and refer to identical URIs. +The new target is invalidated regardless. + +(The above is an example of `table syntax alternative 3`__; not +implemented yet, but I'm thinking about it.) + +__ rst/problems.html#tables + + Representation of Horizontal Rules ================================== -- cgit v1.2.1 From cd0f776806d83251e5cb34e29ec6252cd795464b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 8 Jul 2002 12:46:43 +0000 Subject: fixed typos git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@260 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/introduction.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index 4ffb2d053..3ca6de778 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -7,7 +7,7 @@ :Date: $Date$ reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get -plaintext markup syntax and parser system. It is useful for in-line +plaintext markup syntax and parser system. It is useful for inline program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText_ is a proposed revision and reinterpretation of the @@ -63,9 +63,9 @@ beginning with the most important: 2. Unobtrusive. The markup that is used should be as simple and unobtrusive as possible. The simplicity of markup constructs - should be roughly proporional to their frequency of use. The most + should be roughly proportional to their frequency of use. The most common constructs, with natural and obvious markup, should be the - simplest and most unobtrusive. Less common contstructs, for which + simplest and most unobtrusive. Less common constructs, for which there is no natural or obvious markup, should be distinctive. 3. Unambiguous. The rules for markup must not be open for -- cgit v1.2.1 From 173329c4c4950fbb3289eb20cbd4604ad9cf3f77 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 11 Jul 2002 01:47:45 +0000 Subject: Updated "Authors" bibliographic field behavior. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@261 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index e26ce2a21..1e84feff5 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -825,20 +825,29 @@ The registered bibliographic field names and their corresponding DTD elements are as follows: - Field name "Author": author element. -- "Authors": authors. May contain either: a single paragraph - consisting of a list of authors, separated by ";" or ","; or a - bullet list whose elements each contain a single paragraph per - author. +- "Authors": authors. - "Organization": organization. - "Contact": contact. - "Version": version. - "Status": status. - "Date": date. - "Copyright": copyright. -- "Abstract": topic. May contain arbitrary body elements. Only one - abstract is allowed. The abstract becomes a topic element with - title "Abstract" (or language equivalent) immediately following the - docinfo element. +- "Abstract": topic. + +The "Authors" field may contain either: a single paragraph consisting +of a list of authors, separated by ";" or ","; or a bullet list whose +elements each contain a single paragraph per author. ";" is checked +first, so "Doe, Jane; Doe, John" will work. In some languages +(e.g. Swedish), there is no singular/plural distinction between +"Author" and "Authors", so only an "Authors" field is provided, and a +single name is interpreted as an "Author". If a single name contains +a comma, end it with a semicolon to disambiguate: ":Authors: Doe, +Jane;". + +The "Abstract" field may contain arbitrary body elements. Only one +abstract is allowed. The abstract becomes a topic element with title +"Abstract" (or language equivalent) immediately following the docinfo +element. This field-name-to-element mapping can be extended, or replaced for other languages. See the `DocInfo transform`_ implementation -- cgit v1.2.1 From 94e191e2a5157768c7b2327fda83943ca1f0950b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 13 Jul 2002 02:53:20 +0000 Subject: Changed "inline hyperlink targets" to "inline internal targets". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@268 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 1e84feff5..d996adf7a 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -57,7 +57,7 @@ Here are examples of `body elements`_: external hyperlinks (Python_), internal cross-references (example_), footnote references ([1]_), citation references ([CIT2002]_), substitution references (|example|), and _`inline - hyperlink targets`. + internal targets`. Paragraphs are separated by blank lines and are left-aligned. @@ -1460,7 +1460,7 @@ indirect. .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/ An inline form of internal hyperlink target is available; see - `Inline Hyperlink Targets`_. + `Inline Internal Targets`_. 2. _`External hyperlink targets` have an absolute or relative URI in their link blocks. For example, take the following input:: @@ -1944,7 +1944,7 @@ identical start-strings and end-strings to indicate the markup: Three constructs use different start-strings and end-strings: -- `inline hyperlink targets`_: "_`" and "`" +- `inline internal targets`_: "_`" and "`" - `footnote references`_: "[" and "]_" - `hyperlink references`_: "`" and "\`_" (phrases), or just a trailing "_" (single words) @@ -2005,7 +2005,7 @@ each character. The inline markup recognition order is as follows: - Asterisks: `Strong emphasis`_ ("**") is recognized before emphasis_ ("*"). -- Backquotes: `Inline literals`_ ("``"), `inline hyperlink targets`_ +- Backquotes: `Inline literals`_ ("``"), `inline internal targets`_ (leading "_`", trailing "`"), are mutually independent, and are recognized before phrase `hyperlink references`_ (leading "`", trailing "\`_") and `interpreted text`_ ("`"). @@ -2153,17 +2153,17 @@ match references to targets, but otherwise behave similarly to named hyperlinks. -Inline Hyperlink Targets +Inline Internal Targets ------------------------ DTD element: target. Start-string = "_`", end-string = "`". -Inline hyperlink targets are the equivalent of explicit `internal +Inline internal targets are the equivalent of explicit `internal hyperlink targets`_, but may appear within running text. The syntax begins with an underscore and a backquote, is followed by a hyperlink -name or phrase, and ends with a backquote. Inline hyperlink targets +name or phrase, and ends with a backquote. Inline internal targets may not be anonymous. For example, the following paragraph contains a hyperlink target named -- cgit v1.2.1 From d2293256dba0cdc32d801cbc60d8796fe4be165d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 18 Jul 2002 01:33:32 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@305 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 49 ++++++++++++++++++++++--------------------------- 1 file changed, 22 insertions(+), 27 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 476c57868..d138a8b2c 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -244,33 +244,28 @@ the mappings. The following state transition table shows how ``nameids`` ("ids") and ``nametypes`` ("types") change with new input (a call to -``document.set_name_id_map()``), and what actions are performed:: - - ==== ===== ======== ======== ======= ==== ===== ===== - Old State Input Action New State Notes - ----------- -------- ----------------- ----------- - ids types new type sys.msg. dupname ids types - ==== ===== ======== ======== ======= ==== ===== ===== - -- -- explicit -- -- new True - -- -- implicit -- -- new False - None False explicit -- -- new True - old False explicit implicit old new True - None True explicit explicit new None True - old True explicit explicit new,old None True [1] - None False implicit implicit new None False - old False implicit implicit new,old None False - None True implicit implicit new None True - old True implicit implicit new old True - ==== ===== ======== ======== ======= ==== ===== ===== - -Note 1: Do not clear the name->id map or invalidate the old target if -both old and new targets are external and refer to identical URIs. -The new target is invalidated regardless. - -(The above is an example of `table syntax alternative 3`__; not -implemented yet, but I'm thinking about it.) - -__ rst/problems.html#tables +``document.set_name_id_map()``), and what actions are performed: + +==== ===== ======== ======== ======= ==== ===== ===== + Old State Input Action New State Notes +----------- -------- ----------------- ----------- ----- +ids types new type sys.msg. dupname ids types +==== ===== ======== ======== ======= ==== ===== ===== +-- -- explicit -- -- new True +-- -- implicit -- -- new False +None False explicit -- -- new True +old False explicit implicit old new True +None True explicit explicit new None True +old True explicit explicit new,old None True [#]_ +None False implicit implicit new None False +old False implicit implicit new,old None False +None True implicit implicit new None True +old True implicit implicit new old True +==== ===== ======== ======== ======= ==== ===== ===== + +.. [#] Do not clear the name->id map or invalidate the old target if + both old and new targets are external and refer to identical URIs. + The new target is invalidated regardless. Representation of Horizontal Rules -- cgit v1.2.1 From 6927e19091214c51280889c64eb4ba1eb3489767 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 18 Jul 2002 01:36:52 +0000 Subject: Added "simple table" syntax to supplement the existing but newly-renamed "grid tables". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@307 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 171 ++++++++++++++++++++++++++++++++------ 1 file changed, 146 insertions(+), 25 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index d996adf7a..659e952d9 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -136,15 +136,26 @@ Here are examples of `body elements`_: >>> print '(cut and pasted from interactive Python sessions)' (cut and pasted from interactive Python sessions) -- Tables_:: +- Two syntaxes for tables_: - +------------------------+------------+----------+ - | Header row, column 1 | Header 2 | Header 3 | - +========================+============+==========+ - | body row 1, column 1 | column 2 | column 3 | - +------------------------+------------+----------+ - | body row 2 | Cells may span | - +------------------------+-----------------------+ + 1. `Grid tables`_; complete, but complex and verbose:: + + +------------------------+------------+----------+ + | Header row, column 1 | Header 2 | Header 3 | + +========================+============+==========+ + | body row 1, column 1 | column 2 | column 3 | + +------------------------+------------+----------+ + | body row 2 | Cells may span | + +------------------------+-----------------------+ + + 2. `Simple tables`_; easy and compact, but limited:: + + ==================== ========== ========== + Header row, column 1 Header 2 Header 3 + ==================== ========== ========== + body row 1, column 1 column 2 column 3 + body row 2 Cells may span columns + ==================== ====================== - `Explicit markup blocks`_ all begin with an explicit block marker, two periods and a space: @@ -1109,17 +1120,38 @@ Tables DTD elements: table, tgroup, colspec, thead, tbody, row, entry. -Tables are described with a visual outline made up of the characters +ReStructuredText provides two syntaxes for delineating table cells: +`Grid Tables`_ and `Simple Tables`_. + +As with other body elements, blank lines are required before and after +tables. Tables' left edges should align with the left edge of +preceding text blocks; if indented, the table is considered to be part +of a block quote. + +Once isolated, each table cell is treated as a miniature document; the +top and bottom cell boundaries act as delimiting blank lines. Each +cell contains zero or more body elements. Cell contents may include +left and/or right margins, which are removed before processing. + + +Grid Tables +``````````` + +Grid tables provide a complete table representation via grid-like +"ASCII art". Grid tables allow arbitrary cell contents (body +elements), and both row and column spans. However, grid tables can be +cumbersome to produce, especially for simple data sets. The `Emacs +table mode`_ is a tool that allows easy editing of grid tables, in +Emacs. See `Simple Tables`_ for a simpler (but limited) +representation. + +Grid tables are described with a visual grid made up of the characters "-", "=", "|", and "+". The hyphen ("-") is used for horizontal lines (row separators). The equals sign ("=") may be used to separate -optional header rows from the table body. The vertical bar ("|") is -used for vertical lines (column separators). The plus sign ("+") is -used for intersections of horizontal and vertical lines. - -Each table cell is treated as a miniature document; the top and bottom -cell boundaries act as delimiting blank lines. Each cell contains -zero or more body elements. Cell contents may include left and/or -right margins, which are removed before processing. Example:: +optional header rows from the table body (not supported by the `Emacs +table mode`_). The vertical bar ("|") is used for vertical lines +(column separators). The plus sign ("+") is used for intersections of +horizontal and vertical lines. Example:: +------------------------+------------+----------+----------+ | Header row, column 1 | Header 2 | Header 3 | Header 4 | @@ -1134,14 +1166,9 @@ right margins, which are removed before processing. Example:: | body row 4 | | - body elements. | +------------------------+------------+---------------------+ -As with other body elements, blank lines are required before and after -tables. Tables' left edges should align with the left edge of -preceding text blocks; otherwise, the table is considered to be part -of a block quote. - -Some care must be taken with tables to avoid undesired interactions -with cell text in rare cases. For example, the following table -contains a cell in row 2 spanning from column 2 to column 4:: +Some care must be taken with grid tables to avoid undesired +interactions with cell text in rare cases. For example, the following +table contains a cell in row 2 spanning from column 2 to column 4:: +--------------+----------+-----------+-----------+ | row 1, col 1 | column 2 | column 3 | column 4 | @@ -1186,6 +1213,100 @@ Another possibility is to add an extra line to row 2:: +--------------+----------+-----------+-----------+ +Simple Tables +````````````` + +Simple tables provide a compact and easy to type but limited +row-oriented table representation for simple data sets. Cell contents +are typically single paragraphs, although arbitrary body elements may +be represented in most cells. Simple tables allow multi-line rows and +column spans, but not row spans. See `Grid Tables`_ above for a +complete table representation. + +Simple tables are described with horizontal borders made up of "=" and +"-" characters. The equals sign ("=") is used for top and bottom +table borders, and to separate optional header rows from the table +body. The hyphen ("-") is used to indicate column spans in a single +row by underlining the joined columns. + +A simple table begins with a top border of equals signs with one or +more spaces at each column boundary (two or more spaces recommended). +Regardless of spans, the top border *must* fully describe all table +columns. There must be at least two columns in the table (to +differentiate it from section headers). The last of the optional +header rows is underlined with '=', again with spaces at column +boundaries. There may not be a blank line below the header row +separator; it would be interpreted as the bottom border of the table. +The bottom boundary of the table consists of '=' underlines, also with +spaces at column boundaries. For example, here is a truth table, a +three-column table with one header row and four body rows:: + + ===== ===== ======= + A B A and B + ===== ===== ======= + False False False + True False False + False True False + True True True + ===== ===== ======= + +Underlines of '-' may be used to indicate column spans by "filling in" +column margins to join adjacent columns. Column span underlines must +be complete (they must cover all columns) and align with established +column boundaries. Text lines containing column span underlines may +not contain any other text. A column span underline applies only to +one row immediately above it. For example, here is a table with a +column span in the header:: + + ===== ===== ====== + Inputs Output + ------------ ------ + A B A or B + ===== ===== ====== + False False False + True False True + False True True + True True True + ===== ===== ====== + +Each line of text must contain spaces at column boundaries, except +where cells have been joined by column spans. Each line of text +starts a new row, except when there is a blank cell in the first +column. In that case, that line of text is parsed as a continuation +line. For this reason, cells in the first column of new rows (*not* +continuation lines) *must* contain some text; blank cells would lead +to a misinterpretation. An empty comment ("..") is sufficient and +will be omitted from the processed output. Also, cells in the first +column are limited to one line of text. + +Blank lines are permitted within simple tables. Their interpretation +depends on the context. Blank lines *between* rows are ignored. +Blank lines *within* multi-line rows may separate paragraphs or other +body elements within cells. + +The rightmost column is unbounded; text may continue past the edge of +the table (as indicated by the table borders). However, it is +recommended that borders be made long enough to contain the entire +text. + +The following example illustrates continuation lines (row 2 consists +of two lines of text, and four lines for row 3), a blank line +separating paragraphs (row 3, column 2), and text extending past the +right edge of the table:: + + ===== ===== + col 1 col 2 + ===== ===== + 1 Second column of row 1. + 2 Second column of row 2. + Second line of paragraph. + 3 - Second column of row 3. + + - Second item in bullet + list (row 3, column 2). + ===== ===== + + Explicit Markup Blocks ---------------------- -- cgit v1.2.1 From 8a2a8c7bb67756e1c7f4429094bcf2e02139ac5b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 18 Jul 2002 02:00:37 +0000 Subject: fixed link git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@314 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 659e952d9..abf85b19c 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2454,12 +2454,13 @@ Markup errors are handled according to the specification in `PEP .. _DocTitle transform: .. _DocInfo transform: http://docutils.sourceforge.net/docutils/transforms/frontmatter.py -.. _doctest module: - http://www.python.org/doc/current/lib/module-doctest.html .. _getopt.py: http://www.python.org/doc/current/lib/module-getopt.html .. _GNU libc getopt_long(): http://www.gnu.org/manual/glibc-2.2.3/html_node/libc_516.html +.. _doctest module: + http://www.python.org/doc/current/lib/module-doctest.html +.. _Emacs table mode: http://table.sourceforge.net/ .. _Index of WWW Addressing Schemes: http://www.w3.org/Addressing/schemes.html .. _World Wide Web Consortium: http://www.w3.org/ -- cgit v1.2.1 From a29e32f3d2999d91eba1444f59c809de7489fed9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 24 Jul 2002 01:44:44 +0000 Subject: Added cautions for anonymous hyperlink use. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@361 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index abf85b19c..74e8cf3c8 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1676,12 +1676,14 @@ Anonymous Hyperlinks The `World Wide Web Consortium`_ recommends in its `HTML Techniques for Web Content Accessibility Guidelines`_ that authors should -"clearly identify the target of each link." Hyperlink references +"clearly identify the target of each link." Hyperlink references should be as verbose as possible, but duplicating a verbose hyperlink name in the target is onerous and error-prone. Anonymous hyperlinks are designed to allow convenient verbose hyperlink references, and are analogous to `Auto-Numbered Footnotes`_. They are particularly useful -in short or one-off documents. +in short or one-off documents. However, this feature is easily abused +and can result in unreadable plaintext and/or unmaintainable +documents. Caution is advised. Anonymous `hyperlink references`_ are specified with two underscores instead of one:: @@ -1703,7 +1705,10 @@ to its target. Instead, the order of anonymous hyperlink references and targets within the document is significant: the first anonymous reference will link to the first anonymous target. The number of anonymous hyperlink references in a document must match the number of -anonymous targets. +anonymous targets. For readability, it is recommended that targets be +kept close to references. Take care when editing text containing +anonymous references; adding, removing, and rearranging references +require attention to the order of corresponding targets. Directives -- cgit v1.2.1 From 9aff0d96c5f7e0fff2b9df8cc522d922534753dd Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 24 Jul 2002 01:45:41 +0000 Subject: Added "backlinks" attribute to "contents" directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@362 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index d39f488c3..039e7fd0c 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -212,6 +212,9 @@ The following attributes are recognized: 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. +``backlinks`` : "entry" or "top" or "none" + Generate links from section headers back to the table of contents + entries, the table of contents itself, or generate no backlinks. Footnotes -- cgit v1.2.1 From c1cdf743e8823711597a7a0ed47822af56c030e2 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 25 Jul 2002 01:55:51 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@371 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 74e8cf3c8..4c56bd25d 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -795,11 +795,12 @@ The syntax for field arguments may be extended in the future. For example, quoted phrases may be treated as a single argument, and direct support for the "name=value" syntax may be added. -Standard RFC822 headers cannot be used for this construct because they -are ambiguous. A word followed by a colon at the beginning of a line -is common in written text. However, in well-defined contexts such as -when a field list invariably occurs at the beginning of a document -(PEPs and email messages), standard RFC822 headers could be used. +Standard RFC822_ headers cannot be used for this construct because +they are ambiguous. A word followed by a colon at the beginning of a +line is common in written text. However, in well-defined contexts +such as when a field list invariably occurs at the beginning of a +document (PEPs and email messages), standard RFC822 headers could be +used. Syntax diagram (simplified):: -- cgit v1.2.1 From 6b056f9e44a429f6f1f6641e37dc383a02a97d42 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 27 Jul 2002 03:48:12 +0000 Subject: Added support for generic bibliographic fields. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@378 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 80e54b084..5d6ec6ad6 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -103,6 +103,7 @@ resolve to either an internal or external reference. <!ENTITY % bibliographic.elements " author | authors | organization | contact | version | revision | status | date | copyright + | field %additional.bibliographic.elements; "> <!ENTITY % additional.structural.elements ""> -- cgit v1.2.1 From 08050d45bb78052da7109b32b46e29f8ef9f5021 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 27 Jul 2002 03:50:20 +0000 Subject: Added "Dedication" and generic bibliographic fields. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@379 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 49 +++++++++++++++++++++++---------------- 1 file changed, 29 insertions(+), 20 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 4c56bd25d..0e0941226 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -754,7 +754,7 @@ DTD elements: field_list, field, field_name, field_argument, field_body. Field lists are most often used as part of an extension syntax, such -as attributes for directives_, or database-like fields meant for +as attributes for directives_, or database-like records meant for further processing. They are not intended to be an alternative to definition lists. Applications of reStructuredText may recognize field names and transform fields or field bodies in certain contexts. @@ -815,7 +815,7 @@ Bibliographic Fields ```````````````````` DTD elements: docinfo, author, authors, organization, contact, -version, status, date, copyright, topic. +version, status, date, copyright, field, topic. When a field list is the first non-comment element in a document (after the document title, if there is one), it may have certain @@ -823,15 +823,15 @@ specific fields transformed to document bibliographic data. This bibliographic data corresponds to the front matter of a book, such as the title page and copyright page. -Certain field names (listed below) are recognized and transformed to -the corresponding DTD elements, most becoming child elements of the -"docinfo" element. No ordering is required of these fields, although -they may be rearranged to fit the document structure, as noted. -Unless otherwise indicated in the list below, each of the -bibliographic elements' field bodies may contain a single paragraph -only. Field bodies may be checked for `RCS keywords`_ and cleaned up. -Any unrecognized fields will remain in a generic field list in the -document body. +Certain registered field names (listed below) are recognized and +transformed to the corresponding DTD elements, most becoming child +elements of the "docinfo" element. No ordering is required of these +fields, although they may be rearranged to fit the document structure, +as noted. Unless otherwise indicated below, each of the bibliographic +elements' field bodies may contain a single paragraph only. Field +bodies may be checked for `RCS keywords`_ and cleaned up. Any +unrecognized fields will remain as generic fields in the docinfo +element. The registered bibliographic field names and their corresponding DTD elements are as follows: @@ -844,6 +844,7 @@ elements are as follows: - "Status": status. - "Date": date. - "Copyright": copyright. +- "Dedication": topic. - "Abstract": topic. The "Authors" field may contain either: a single paragraph consisting @@ -856,14 +857,17 @@ single name is interpreted as an "Author". If a single name contains a comma, end it with a semicolon to disambiguate: ":Authors: Doe, Jane;". -The "Abstract" field may contain arbitrary body elements. Only one -abstract is allowed. The abstract becomes a topic element with title -"Abstract" (or language equivalent) immediately following the docinfo -element. +The "Dedication" and "Abstract" fields may contain arbitrary body +elements. Only one of each is allowed. They become topic elements +with "Dedication" or "Abstract" titles (or language equivalents) +immediately following the docinfo element. -This field-name-to-element mapping can be extended, or replaced for -other languages. See the `DocInfo transform`_ implementation -documentation for details. +This field-name-to-element mapping can be replaced for other +languages. See the `DocInfo transform`_ implementation documentation +for details. + +Unregistered/generic fields may contain one or more paragraphs or +arbitrary body elements. RCS Keywords @@ -1277,8 +1281,13 @@ column. In that case, that line of text is parsed as a continuation line. For this reason, cells in the first column of new rows (*not* continuation lines) *must* contain some text; blank cells would lead to a misinterpretation. An empty comment ("..") is sufficient and -will be omitted from the processed output. Also, cells in the first -column are limited to one line of text. +will be omitted from the processed output. Also, this mechanism +limits cells in the first column to only one line of text. Use `grid +tables`_ if this limitation is unacceptable. + +Underlines of '-' may also be used to visually separate rows, even if +there are no column spans. This is especially useful in long tables, +where rows are many lines long. Blank lines are permitted within simple tables. Their interpretation depends on the context. Blank lines *between* rows are ignored. -- cgit v1.2.1 From 1822e231995b5aacc2511922f1fe4b7c46ff2de5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 1 Aug 2002 00:15:21 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@433 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 039e7fd0c..8011eb3c5 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -220,6 +220,8 @@ The following attributes are recognized: Footnotes ========= +**NOT IMPLEMENTED YET** + DTD elements: pending, topic. @@@ @@ -228,6 +230,8 @@ DTD elements: pending, topic. Citations ========= +**NOT IMPLEMENTED YET** + DTD elements: pending, topic. @@@ @@ -236,6 +240,8 @@ DTD elements: pending, topic. Topic ===== +**NOT IMPLEMENTED YET** + DTD element: topic. @@@ @@ -303,6 +309,8 @@ HTML equivalent:: Imagemap ======== +**NOT IMPLEMENTED YET** + Non-standard element: imagemap. @@ -313,6 +321,8 @@ Non-standard element: imagemap. Raw Data Pass-Through ===================== +**NOT IMPLEMENTED YET** + DTD element: pending. Directive block: the directive data is interpreted as an output format -- cgit v1.2.1 From 550b619ded6ea003676ceacebaed30b27fb81061 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 7 Aug 2002 01:11:40 +0000 Subject: Added "topic" directive docs. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@468 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 8011eb3c5..205d3843a 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -157,6 +157,34 @@ legend. To specify a legend without a caption, use an empty comment ("..") in place of the caption. +--------------- + Body Elements +--------------- + +Topic +===== + +DTD element: topic. + +Directive block: directive data and all following indented lines are +collected. The first line is interpreted as the topic title; the +second line must be blank. All subsequent lines are the topic body, +interpreted as body elements. + +A topic is like a block quote with a title, or a self-contained +section with no subsections. Use the "topic" directive to indicate a +self-contained idea that is separate from the flow of the document. +Topics may occur anywhere a section or transition may occur. Body +elements (including topics) may not contain nested topics. For +example:: + + topic:: Topic Title + + Subsequent indented lines comprise + the body of the topic, and are + interpreted as body elements. + + ---------------- Document Parts ---------------- -- cgit v1.2.1 From 43396c99e65920bfc0219d8d4e731c6542cd1cce Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 7 Aug 2002 01:12:51 +0000 Subject: Disambiguated comments. Updated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@469 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 0e0941226..c94e03ffb 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -6,7 +6,7 @@ :Revision: $Revision$ :Date: $Date$ -reStructuredText_ is plain text that uses simple and intuitive +reStructuredText_ is plaintext that uses simple and intuitive constructs to indicate the structure of a document. These constructs are equally easy to read in raw and processed forms. This document is itself an example of reStructuredText (raw, if you are reading the @@ -28,8 +28,7 @@ reStructuredText markup by example. A complete specification is given in the `Syntax Details`_ section. `Literal blocks`_ (in which no markup processing is done) are used for -examples throughout this document, to illustrate the plain text -markup. +examples throughout this document, to illustrate the plaintext markup. .. contents:: @@ -324,7 +323,7 @@ the field names):: Escaping Mechanism ================== -The character set universally available to plain text documents, 7-bit +The character set universally available to plaintext documents, 7-bit ASCII, is limited. No matter what characters are used for markup, they will already have multiple meanings in written text. Therefore markup characters *will* sometimes appear in text **without being @@ -1335,7 +1334,7 @@ required between explicit markup blocks and other elements, but are optional between explicit markup blocks where unambiguous. The explicit markup syntax is used for footnotes, citations, hyperlink -targets, directives, and comments. +targets, directives, substitution definitions, and comments. Footnotes @@ -1927,8 +1926,8 @@ Styles [#]_ The style name may be meaningful in the context of some particular output format (CSS class name for HTML output, LaTeX style name - for LaTeX, etc), or may be ignored for other output formats (often - for plain text). + for LaTeX, etc), or may be ignored for other output formats (such + as plaintext). .. @@@ This needs to be rethought & rewritten or removed: @@ -2006,8 +2005,20 @@ be processed as a comment element. No further processing is done on the comment block text; a comment contains a single "text blob". Depending on the output formatter, comments may be removed from the processed output. The only restriction on comments is that they not -use the same syntax as directives, footnotes, citations, or hyperlink -targets. +use the same syntax as any of the other explicit markup constructs: +substitution definitions, directives, footnotes, citations, or +hyperlink targets. To ensure that none of the other explicit markup +constructs is recognized, leave the ".." on a line by itself:: + + .. This is a comment + .. + _so: is this! + .. + [and] this! + .. + this:: too! + .. + |even| this:: ! A explicit markup start followed by a blank line and nothing else (apart from whitespace) is an "empty comment". It serves to terminate -- cgit v1.2.1 From 5bce8db5f80f9e1a03724ee137fb0adf578bc488 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 10 Aug 2002 04:29:04 +0000 Subject: Changed the focus. It's about DTD elements: structural relationships, semantics, and external (public) attributes. Not about the element class library; moved some implementation-specific stuff into ``docutils.nodes`` docstrings. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@494 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 237 +++++++++++++++++++++++---------------------------- 1 file changed, 108 insertions(+), 129 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index d138a8b2c..ce4f951db 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -6,14 +6,35 @@ :Revision: $Revision$ :Date: $Date$ -This document describes the internal data structure representing -document trees in Docutils. The data structure is defined by the -hierarchy of classes in the ``docutils.nodes`` module. It is also -formally described by the `Docutils Generic DTD`_ XML document type -definition, docutils.dtd_, which is the definitive source for element -hierarchy details. - -Below is a simplified diagram of the hierarchy of element types in the +This document describes the XML data structure of Docutils documents, +the relationships and semantics of elements. The Docutils document +structure is formally defined by the `Docutils Generic DTD`_ XML +document type definition, docutils.dtd_, which is the definitive +source for details of element structural relationships. + +The data structure is implemented by the class library in the +``docutils.nodes`` module. This document does not discuss +implementation details; they can be found in documentation for the +``docutils.nodes`` module (docstrings). + +The reader is assumed to have some familiarity with XML or SGML, and +an understanding the data structure meaning of "tree". For a list of +introductory articles, see `Introducing the Extensible Markup Language +(XML)`_. + +.. _Docutils Generic DTD: +.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd +.. _Introducing the Extensible Markup Language (XML): + http://xml.coverpages.org/xmlIntro.html + +.. contents:: + + +------------------- + Element Hierarchy +------------------- + +Below is a simplified diagram of the hierarchy of elements in the Docutils document tree structure. An element may contain any other elements immediately below it in the diagram. Text in square brackets are notes. Element types in parentheses indicate recursive or @@ -36,94 +57,97 @@ contain further body elements, etc. :: | markup) | +---------+ +The Docutils document model uses a simple, recursive model for section +structure. A document_ node may contain body elements and section_ +elements. Sections in turn may contain body elements and sections. +The level (depth) of a section element is determined from its physical +nesting level; unlike other document models (``<h1>`` in HTML_, +``<sect1>`` in DocBook_, ``<div1>`` in XMLSpec_) the level is not +incorporated into the element name. -------------------- - Element Hierarchy -------------------- +The Docutils document model uses strict element content models. Every +element has a unique structure and semantics, but elements may be +classified into general categories: -A class hierarchy has been implemented in nodes.py. The position of -each node (the level at which it can occur) is significant and is -represented by abstract base classes (Root, Structural, Body, Inline, -etc.). Certain transformations will be easier because we can use -``isinstance(node, base_class)`` to determine the position of the node -in the hierarchy. +* _`Structural elements` (document_, section_, and topic_) may only + contain child elements; they do not directly contain text data. + Child elements of structural elements may be body elements or other + structural elements. Structural elements can only be child elements + of other structural elements. -The elements making up Docutils document trees can be categorized into -the following groups: +* _`Body elements` are contained within structural elements and + compound body elements. There are two subcategories of body + elements: -- _`Root element`: document_ + - _`Compound body elements` (like table_ and bullet_list_) contain + local substructure and further body elements. They do not + directly contain text data. -- _`Title elements`: title_, subtitle_ + - _`Simple body elements` (like paragraph_ and literal_block) + directly contain text data, and may also contain inline elements. + Some simple body elements have a "mixed content model". -- _`Bibliographic elements`: docinfo_, author_, authors_, - organization_, contact_, version_, revision_, status_, date_, - copyright_ +* _`Inline elements` (like emphasis_ and reference_) directly contain + text data, and may also contain inline elements. Inline elements + are contained within simple body elements. Inline elements have a + "mixed content model". -- _`Structural elements`: document_, section_, topic_, transition_ +Only elements which are meant to directly contain text data have a +mixed content model, where text data and elements may be intermixed. +This is unlike the HTML_ document model, where paragraphs and text +data may occur at the same level. -- _`Body elements`: +.. _HTML: http://www.w3.org/MarkUp/ +.. _DocBook: http://docbook.org/tdg/en/html/docbook.html +.. _XMLSpec: http://www.w3.org/XML/1998/06/xmlspec-report.htm - - _`General body elements`: paragraph_, literal_block_, - block_quote_, doctest_block_, table_, figure_, image_, footnote_ - - _`Lists`: bullet_list_, enumerated_list_, definition_list_, - field_list_, option_list_ - - - _`Admonitions`: note_, tip_, warning_, error_, caution_, danger_, - important_ +------------------- + Element Reference +------------------- - - _`Special body elements`: target_, substitution_definition_, - comment_, system_warning_ +Each element in the document tree model is described in its own +section below. Each section contains the following subsections: -- _`Inline elements`: emphasis_, strong_, interpreted_, literal_, - reference_, target_, footnote_reference_, substitution_reference_, - image_, problematic_ +* Description: The semantics of the element. + - Parents: A list of elements which may contain the element. -``Node`` -======== + - Children: A list of elements which may occur within the element. + - Analogies: Describes analogous elements in well-known document + models such as HTML_ or DocBook_. Lists similarities and + differences. -``Text`` -======== + - Processing Expectations: Lists formatting or rendering + expectations for the element. +* Content Model: the content model of the element from the `Docutils + DTD`_. -``Element`` -=========== + - Attributes: Describes the possible values and semantics of each + attribute. Common attributes are described via references. + - Parameter Entities: Lists the parameter entities in which the + element described appears. -``TextElement`` -=============== +* Example: Where possible, a reStructuredText example is shown along + with a fragment of the document tree resulting from parsing. -------------------- - Element Reference -------------------- - ``document`` ============ -description -contents +The ``document`` element is the root (topmost) element of the Docutils +document tree. ``document`` is the direct or indirect ancestor of +every other element in the tree. -External attributes -------------------- -`Common external attributes`_. +contents +Attributes +---------- -Internal attributes -------------------- -- `Common internal attributes`_. -- ``explicittargets`` -- ``implicittargets`` -- ``externaltargets`` -- ``indirecttargets`` -- ``refnames`` -- ``anonymoustargets`` -- ``anonymousrefs`` -- ``autofootnotes`` -- ``autofootnoterefs`` -- ``reporter`` +`Common external attributes`_. --------------------- @@ -188,13 +212,6 @@ The ``source`` attribute The ``xml:space`` attribute -Internal Attributes -=================== - -All element objects share the following _`common internal attributes`: -rawsource_, children_, attributes_, tagname_. - - ------------------------ DTD Parameter Entities ------------------------ @@ -234,40 +251,6 @@ The ``%text.model;`` parameter entity Appendix: Miscellaneous Topics -------------------------------- -Hyperlink Bookkeeping -===================== - -``document.nameids`` maps names to IDs, while ``document.nametypes`` -maps names to booleans representing hyperlink type (True==explicit, -False==implicit). The ``document.set_name_id_map()`` method updates -the mappings. - -The following state transition table shows how ``nameids`` ("ids") and -``nametypes`` ("types") change with new input (a call to -``document.set_name_id_map()``), and what actions are performed: - -==== ===== ======== ======== ======= ==== ===== ===== - Old State Input Action New State Notes ------------ -------- ----------------- ----------- ----- -ids types new type sys.msg. dupname ids types -==== ===== ======== ======== ======= ==== ===== ===== --- -- explicit -- -- new True --- -- implicit -- -- new False -None False explicit -- -- new True -old False explicit implicit old new True -None True explicit explicit new None True -old True explicit explicit new,old None True [#]_ -None False implicit implicit new None False -old False implicit implicit new,old None False -None True implicit implicit new None True -old True implicit implicit new old True -==== ===== ======== ======== ======= ==== ===== ===== - -.. [#] Do not clear the name->id map or invalidate the old target if - both old and new targets are external and refer to identical URIs. - The new target is invalidated regardless. - - Representation of Horizontal Rules ================================== @@ -278,11 +261,11 @@ the implementation of the document tree. Given this source:: Document ======== - Paragraph + Paragraph 1 -------- - Paragraph + Paragraph 2 The horizontal rule indicates a "transition" (in prose terms) or the start of a new "division". Before implementation, the parsed document @@ -293,13 +276,12 @@ tree would be:: <title> Document <paragraph> - Paragraph + Paragraph 1 -------- <--- error here <paragraph> - Paragraph + Paragraph 2 -There are several possibilities for the implementation. Solution 3 -was chosen. +There are several possibilities for the implementation: 1. Implement horizontal rules as "divisions" or segments. A "division" is a title-less, non-hierarchical section. The first @@ -310,10 +292,10 @@ was chosen. <title> Document <paragraph> - Paragraph + Paragraph 1 <division> <paragraph> - Paragraph + Paragraph 2 But the two paragraphs are really at the same level; they shouldn't appear to be at different levels. There's really an invisible @@ -329,18 +311,18 @@ was chosen. Document <division> <paragraph> - Paragraph + Paragraph 1 <division> <paragraph> - Paragraph + Paragraph 2 With this change, documents and sections will directly contain divisions and sections, but not body elements. Only divisions will directly contain body elements. Even without a horizontal rule anywhere, the body elements of a document or section would be contained within a division element. This makes the document tree - deeper. This is similar to the way HTML treats document contents: - grouped within a <BODY> element. + deeper. This is similar to the way HTML_ treats document contents: + grouped within a ``<body>`` element. 3. Implement them as "transitions", empty elements:: @@ -349,23 +331,20 @@ was chosen. <title> Document <paragraph> - Paragraph + Paragraph 1 <transition> <paragraph> - Paragraph + Paragraph 2 A transition would be a "point element", not containing anything, only identifying a point within the document structure. This keeps the document tree flatter, but the idea of a "point element" like "transition" smells bad. A transition isn't a thing itself, it's - the space between two divisions. - - This solution has been chosen for incorporation into the document - tree. + the space between two divisions. However, transitions are a + practical solution. +Solution 3 was chosen for incorporation into the document tree model. -.. _Docutils Generic DTD: -.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd .. _reStructuredText: http://docutils.sourceforge.net/spec/rst/reStructuredText.html -- cgit v1.2.1 From ec966350bdbbc7b83741dbe91f6c9bf93443ff7d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 13 Aug 2002 00:59:29 +0000 Subject: - Added "generated" inline element. - Added "auto" attribute to "title". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@509 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 5d6ec6ad6..312c74895 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -87,7 +87,7 @@ resolve to either an internal or external reference. <!ENTITY % anonymous.att " anonymous %yesorno; #IMPLIED "> -<!-- Auto-numbered footnote. --> +<!-- Auto-numbered footnote or title. --> <!ENTITY % auto.att " auto %yesorno; #IMPLIED "> @@ -127,7 +127,8 @@ resolve to either an internal or external reference. <!ENTITY % inline.elements " emphasis | strong | interpreted | literal | reference | footnote_reference | citation_reference - | substitution_reference | target | image | problematic | raw + | substitution_reference | problematic | generated + | target | image | raw %additional.inline.elements; "> <!-- Element Content Models @@ -188,7 +189,8 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT title %text.model;> <!ATTLIST title %basic.atts; - %refid.att;> + %refid.att; + %auto.att;> <!ELEMENT subtitle %text.model;> <!ATTLIST subtitle %basic.atts;> @@ -523,6 +525,9 @@ following caveats: %basic.atts; %refid.att;> +<!ELEMENT generated (%text.model;)> +<!ATTLIST generated %basic.atts;> + <!-- Local Variables: -- cgit v1.2.1 From bf0e6532758252fbf6b22c80a1f83d702463f712 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 13 Aug 2002 01:00:28 +0000 Subject: Added the "sectnum" directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@510 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 47 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 10 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 205d3843a..5e1f07314 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -9,6 +9,14 @@ This document describes the directives implemented in the reference reStructuredText parser. +Directives have the following syntax:: + + +-------+--------------------------+ + | ".. " | directive type "::" data | + +-------+ directive block | + | | + +--------------------------+ + .. contents:: @@ -235,7 +243,7 @@ The following attributes are recognized: ``depth`` : integer The number of section levels that are collected in the table of - contents. + contents. The default is unlimited depth. ``local`` : empty Generate a local table of contents. Entries will only include subsections of the section in which the directive is given. If no @@ -245,17 +253,36 @@ The following attributes are recognized: entries, the table of contents itself, or generate no backlinks. -Footnotes -========= +Automatic Section Numbering +=========================== -**NOT IMPLEMENTED YET** +DTD elements: pending, generated. -DTD elements: pending, topic. +Directive block: directive data and following indented lines (up to +the first blank line) are interpreted as optional attributes. + +The "sectnum" (or "section-autonumbering") directive automatically +numbers sections and subsections in a document. Section numbers of +the "multiple enumeration" form, where each level has a number, +separated by periods. For example, the title of section 1, subsection +2, subsubsection 3 would have "1.2.3" prefixed. + +The "sectnum" directive does its work in two passes: initial parse and +transform. During the initial parse, a "pending" element is generated +which acts as a placeholder, storing any attributes internally. At a +later stage in the processing, the "pending" element triggers a +transform, which adds section numbers to titles. Section numbers are +enclosed in a "generated" element, and titles have their "auto" +attribute set to "1". -@@@ +The following attributes are recognized: +``depth`` : integer + The number of section levels that are numbered by this directive. + The default is unlimited depth. -Citations + +Footnotes ========= **NOT IMPLEMENTED YET** @@ -265,12 +292,12 @@ DTD elements: pending, topic. @@@ -Topic -===== +Citations +========= **NOT IMPLEMENTED YET** -DTD element: topic. +DTD elements: pending, topic. @@@ -- cgit v1.2.1 From 096e020774b4f3681762f86fb2baeff90957feb5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 14 Aug 2002 02:45:02 +0000 Subject: Added the "target-notes" directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@523 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 5e1f07314..f5fa956ce 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -282,6 +282,24 @@ The following attributes are recognized: The default is unlimited depth. +------------ + References +------------ + +Target Footnotes +================ + +DTD elements: pending, footnote, footnote_reference. + +Directive block: unused; directive data must be empty. + +The "target-notes" directive creates a footnote for each external +target in the text, and corresponding footnote references after each +reference. For every explicit target (of the form, ``.. _target name: +URL``) in the text, a footnote will be generated containing the +visible URL as content. + + Footnotes ========= -- cgit v1.2.1 From 0e0945034dac85d840bcf15384b533a41ece4d49 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Aug 2002 00:32:36 +0000 Subject: Added the "line-block" and "parsed-literal" directives. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@537 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 47 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index f5fa956ce..dbbec83fa 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -193,6 +193,53 @@ example:: interpreted as body elements. +Line Block +========== + +DTD element: line_block. + +Directive block: directive data and all following indented text become +the body of the line block. + +The "line-block" directive constructs a paragraph-like element where +leading whitespace and linebreaks are significant and inline markup is +supported. This is useful for address blocks and verse (poetry, song +lyrics). For example:: + + "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by + Ewan McTeagle (for Lassie O'Shea): + + .. line-block:: + + Lend us a couple of bob till Thursday. + I'm absolutely skint. + But I'm expecting a postal order and I can pay you back + as soon as it comes. + Love, Ewan. + + +Parsed Literal Block +==================== + +DTD element: literal_block. + +Directive block: directive data and all following indented text become +the body of the literal block. + +Unlike an ordinary literal block, the "parsed-literal" directive +constructs a literal block where the text is parsed for inline markup. +This is useful for adding hyperlinks to code examples. For example, +all the element names in this content model are links:: + + .. parsed-literal:: + + ((title_, + subtitle_?)?, + docinfo_?, + decoration_?, + `%structure.model;`_) + + ---------------- Document Parts ---------------- -- cgit v1.2.1 From 6801360e316b2004d56599da78056b0e991b6fc6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Aug 2002 00:36:34 +0000 Subject: minor progress git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@540 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 98 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 76 insertions(+), 22 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index ce4f951db..16c4d6442 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -6,6 +6,8 @@ :Revision: $Revision$ :Date: $Date$ +.. contents:: :depth: 1 + This document describes the XML data structure of Docutils documents, the relationships and semantics of elements. The Docutils document structure is formally defined by the `Docutils Generic DTD`_ XML @@ -27,9 +29,6 @@ introductory articles, see `Introducing the Extensible Markup Language .. _Introducing the Extensible Markup Language (XML): http://xml.coverpages.org/xmlIntro.html -.. contents:: - - ------------------- Element Hierarchy ------------------- @@ -106,6 +105,10 @@ data may occur at the same level. Element Reference ------------------- +.. contents:: + :local: + :depth: 1 + Each element in the document tree model is described in its own section below. Each section contains the following subsections: @@ -138,77 +141,112 @@ section below. Each section contains the following subsections: ``document`` ============ +Description +----------- + The ``document`` element is the root (topmost) element of the Docutils document tree. ``document`` is the direct or indirect ancestor of every other element in the tree. -contents + +Content Model +------------- + +.. parsed-literal:: + + ((title_, + subtitle_?)?, + docinfo_?, + decoration_?, + `%structure.model;`_) + Attributes ----------- +`````````` `Common external attributes`_. +Example +------- + + --------------------- Attribute Reference --------------------- -External Attributes -=================== +.. contents:: + :local: + :depth: 1 Through the `%basic.atts;`_ parameter entity, all elements share the following _`common external attributes`: id_, name_, dupname_, -source_. +source_, class_. ``anonymous`` -------------- +============= + The ``anonymous`` attribute ``auto`` --------- +======== + The ``auto`` attribute +``class`` +========= + +The ``class`` attribute + + ``dupname`` ------------ +=========== + The ``dupname`` attribute ``id`` ------- +====== + The ``id`` attribute ``name`` --------- +======== + The ``name`` attribute ``refid`` ---------- +========= + The ``refid`` attribute ``refname`` ------------ +=========== + The ``refname`` attribute ``refuri`` ----------- +========== + The ``refuri`` attribute ``source`` ----------- +========== + The ``source`` attribute ``xml:space`` -------------- +============= + The ``xml:space`` attribute @@ -216,40 +254,56 @@ The ``xml:space`` attribute DTD Parameter Entities ------------------------ +.. contents:: + :local: + :depth: 1 + + ``%basic.atts;`` ================ + The ``%basic.atts;`` parameter entity lists attributes common to all elements. See `Common Attributes`_. ``%body.elements;`` =================== + The ``%body.elements;`` parameter entity ``%inline.elements;`` -==================== +===================== + The ``%inline.elements;`` parameter entity ``%reference.atts;`` ==================== + The ``%reference.atts;`` parameter entity ``%structure.model;`` ===================== + The ``%structure.model;`` parameter entity ``%text.model;`` ================ + The ``%text.model;`` parameter entity --------------------------------- - Appendix: Miscellaneous Topics --------------------------------- +---------------------- + Miscellaneous Topics +---------------------- + +.. contents:: + :local: + :depth: 1 + Representation of Horizontal Rules ================================== -- cgit v1.2.1 From d5fa6b83feda02eef106ac0d7d3425cb1041932d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Aug 2002 00:38:41 +0000 Subject: Added "line_block" body element. Changed content models of "literal_block" and "doctest_block" to ``%text.model``. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@541 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 312c74895..5b7e8aac4 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -113,8 +113,8 @@ resolve to either an internal or external reference. <!ENTITY % additional.body.elements ""> <!ENTITY % body.elements - " paragraph | literal_block | block_quote | doctest_block | table - | figure | image | footnote | citation + " paragraph | literal_block | doctest_block | line_block | block_quote + | table | figure | image | footnote | citation | bullet_list | enumerated_list | definition_list | field_list | option_list | attention | caution | danger | error | hint | important | note @@ -354,15 +354,20 @@ either the string separating it from the `option` (typically either <!ELEMENT description (%body.elements;)+> <!ATTLIST description %basic.atts;> -<!ELEMENT literal_block (#PCDATA)> +<!ELEMENT literal_block %text.model;> <!ATTLIST literal_block %basic.atts; %fixedspace.att;> +<!ELEMENT line_block %text.model;> +<!ATTLIST line_block + %basic.atts; + %fixedspace.att;> + <!ELEMENT block_quote (%body.elements;)+> <!ATTLIST block_quote %basic.atts;> -<!ELEMENT doctest_block (#PCDATA)> +<!ELEMENT doctest_block %text.model;> <!ATTLIST doctest_block %basic.atts; %fixedspace.att;> -- cgit v1.2.1 From 91ae000132d385eda896d67cea537efe983f1962 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Aug 2002 00:39:36 +0000 Subject: Updated enumerated list description; added a discussion of the second-line validity checking. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@542 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index c94e03ffb..040393276 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -680,6 +680,26 @@ interpreted as a letter of the alphabet, not as a Roman numeral. Likewise, lists using letters of the alphabet may not begin with "I"/"i", since these are recognized as Roman numeral 1. +The second line of each enumerated list item is checked for validity. +This is to prevent ordinary paragraphs from being mistakenly +interpreted as list items, when they happen to begin with text +identical to enumerators. For example, this text is parsed as an +ordinary paragraph:: + + A. Einstein was a really + smart dude. + +However, ambiguity cannot be avoided if the paragraph consists of only +one line. This text is parsed as an enumerated list item:: + + A. Einstein was a really smart dude. + +If a single-line paragraph begins with text identical to an enumerator +("A.", "1.", "(b)", "I)", etc.), the first character will have to be +escaped in order to have the line parsed as an ordinary paragraph:: + + \A. Einstein was a really smart dude. + Nested enumerated lists must be created with indentation. For example:: -- cgit v1.2.1 From 3428a179892ef8343a8ec642c43cca59b43cb20a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 01:25:36 +0000 Subject: Lots of progress. Wrote descriptions of all common attributes and parameter entities. Filled in introductory material. Started on element descriptions (3 down, 80 to go). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@550 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 1330 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 1209 insertions(+), 121 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 16c4d6442..bcf983971 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1,6 +1,10 @@ ============================ The Docutils Document Tree ============================ + +A Guide to the Docutils DTD +*************************** + :Author: David Goodger :Contact: goodger@users.sourceforge.net :Revision: $Revision$ @@ -8,35 +12,51 @@ .. contents:: :depth: 1 -This document describes the XML data structure of Docutils documents, +This document describes the XML data structure of Docutils_ documents, the relationships and semantics of elements. The Docutils document structure is formally defined by the `Docutils Generic DTD`_ XML document type definition, docutils.dtd_, which is the definitive source for details of element structural relationships. -The data structure is implemented by the class library in the -``docutils.nodes`` module. This document does not discuss -implementation details; they can be found in documentation for the -``docutils.nodes`` module (docstrings). +This document does not discuss implementation details. Those can be +found in internal documentation (docstrings) for the +``docutils.nodes`` module, where the document tree data structure is +implemented in a class library. The reader is assumed to have some familiarity with XML or SGML, and an understanding the data structure meaning of "tree". For a list of introductory articles, see `Introducing the Extensible Markup Language (XML)`_. +The reStructuredText_ markup is used for illustrative examples +throughout this document. For a gentle introduction, see `A +ReStructuredText Primer`_. For complete technical details, see the +`reStructuredText Markup Specification`_. + + +.. _Docutils: http://docutils.sourceforge.net/ .. _Docutils Generic DTD: +.. _Docutils DTD: .. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd .. _Introducing the Extensible Markup Language (XML): http://xml.coverpages.org/xmlIntro.html +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _A ReStructuredText Primer: + http://docutils.sourceforge.net/docs/rst/quickstart.html +.. _reStructuredText Markup Specification: + http://docutils.sourceforge.net/spec/rst/reStructuredText.html + ------------------- Element Hierarchy ------------------- +.. contents:: :local: + Below is a simplified diagram of the hierarchy of elements in the Docutils document tree structure. An element may contain any other -elements immediately below it in the diagram. Text in square brackets -are notes. Element types in parentheses indicate recursive or +elements immediately below it in the diagram. Notes are written in +square brackets. Element types in parentheses indicate recursive or one-to-many relationships; sections may contain (sub)sections, tables contain further body elements, etc. :: @@ -66,35 +86,120 @@ incorporated into the element name. The Docutils document model uses strict element content models. Every element has a unique structure and semantics, but elements may be -classified into general categories: +classified into general categories (below). Only elements which are +meant to directly contain text data have a mixed content model, where +text data and inline elements may be intermixed. This is unlike the +much looser HTML_ document model, where paragraphs and text data may +occur at the same level. + + +Structural Elements +=================== + +Structural elements may only contain child elements; they do not +directly contain text data. Structural elements may contain body +elements or further structural elements. Structural elements can only +be child elements of other structural elements. + +Category members: document_, section_, topic_ + + +Structural Subelements +---------------------- + +Structural subelements are child elements of structural elements, but +contain no further structure of their own (except for text and inline +elements). + +Category members: title_, subtitle_, transition_ + + +Bibliographic Elements +---------------------- + +The docinfo_ element is an optional child of document_. It groups +bibliographic elements together. + +Category members: docinfo_, author_, authors_, contact_, copyright_, +date_, organization_, revision_, status_, version_ + + +Decorative Elements +------------------- + +The decoration_ element is also an optional child of document_. It +groups together elements used to generate page headers and footers. + +Category members: decoration_, footer_, header_ + + +Body Elements +============= + +Body elements are contained within structural elements and compound +body elements. There are two subcategories of body elements: simple +and compound. + +Category members: attention_, block_quote_, bullet_list_, caution_, +citation_, comment_, danger_, definition_list_, doctest_block_, +enumerated_list_, error_, field_list_, figure_, footnote_, hint_, +image_, important_, line_block_, literal_block_, note_, option_list_, +paragraph_, pending_, raw_, substitution_definition_, +system_message_, table_, target_, tip_, warning_ + -* _`Structural elements` (document_, section_, and topic_) may only - contain child elements; they do not directly contain text data. - Child elements of structural elements may be body elements or other - structural elements. Structural elements can only be child elements - of other structural elements. +Simple Body Elements +-------------------- -* _`Body elements` are contained within structural elements and - compound body elements. There are two subcategories of body - elements: +Simple body elements directly are empty or contain text data. Those +that contain text data may also contain inline elements. Such +elements therefore have a "mixed content model". - - _`Compound body elements` (like table_ and bullet_list_) contain - local substructure and further body elements. They do not - directly contain text data. +Category members: comment_, doctest_block_, image_, line_block_, +literal_block_, paragraph_, pending_, raw_, substitution_definition_, +target_ - - _`Simple body elements` (like paragraph_ and literal_block) - directly contain text data, and may also contain inline elements. - Some simple body elements have a "mixed content model". -* _`Inline elements` (like emphasis_ and reference_) directly contain - text data, and may also contain inline elements. Inline elements - are contained within simple body elements. Inline elements have a - "mixed content model". +Compound Body Elements +---------------------- + +Compound body elements contain local substructure (component parts) +and further body elements. They do not directly contain text data. + +Category members: attention_, block_quote_, bullet_list_, caution_, +citation_, danger_, definition_list_, enumerated_list_, error_, +field_list_, figure_, footnote_, hint_, important_, note_, +option_list_, system_message_, table_, tip_, warning_ + + +Compound Body Subelements +````````````````````````` + +Compound body elements contain specific compound body subelements +(e.g. bullet_list_ contains list_item_). Subelements may themselves +be compound elements (containing further child elements, like field_) +or simple data elements (containing text data, like field_name_). +These subelements always occur within specific parent elements, never +at the body element level (just below sections, etc.). + +Category members: caption_, classifier_, colspec_, definition_, +definition_list_item_, description_, entry_, field_, field_argument_, +field_body_, field_name_, label_, legend_, list_item_, option_, +option_argument_, option_group_, option_list_item_, option_string_, +row_, tbody_, term_, tgroup_, thead + + +Inline Elements +=============== + +Inline elements directly contain text data, and may also contain +further inline elements. Inline elements are contained within simple +body elements. Most inline elements have a "mixed content model". + +Category members: citation_reference_, emphasis_, footnote_reference_, +generated_, image_, interpreted_, literal_, problematic_, reference_, +strong_, substitution_reference_, target_, raw_. -Only elements which are meant to directly contain text data have a -mixed content model, where text data and elements may be intermixed. -This is unlike the HTML_ document model, where paragraphs and text -data may occur at the same level. .. _HTML: http://www.w3.org/MarkUp/ .. _DocBook: http://docbook.org/tdg/en/html/docbook.html @@ -105,12 +210,12 @@ data may occur at the same level. Element Reference ------------------- -.. contents:: - :local: - :depth: 1 +.. contents:: :local: + :depth: 1 -Each element in the document tree model is described in its own -section below. Each section contains the following subsections: +Each element in the DTD (document type definition) is described in its +own section below. Each section contains the following subsections +and items: * Description: The semantics of the element. @@ -122,20 +227,184 @@ section below. Each section contains the following subsections: models such as HTML_ or DocBook_. Lists similarities and differences. - - Processing Expectations: Lists formatting or rendering - expectations for the element. + - Processing: Lists formatting or rendering recommendations for the + element. -* Content Model: the content model of the element from the `Docutils - DTD`_. +* Content Model: from the `Docutils DTD`_. - - Attributes: Describes the possible values and semantics of each - attribute. Common attributes are described via references. + - Attributes: Describes (or refers to descriptions of) the possible + values and semantics of each attribute. - - Parameter Entities: Lists the parameter entities in which the - element described appears. + - Parameter Entities: Lists the parameter entities which include the + element described. * Example: Where possible, a reStructuredText example is shown along - with a fragment of the document tree resulting from parsing. + with a fragment of the document tree resulting from parsing. + _`Pseudo-XML` is used for the results of parsing and processing. + Pseudo-XML is a representation of XML where nesting is indicated by + indentation and end-tags are not shown. Some of the precision of + real XML is traded for easier readability. For example, the + following are equivalent. XML:: + + <document> + <section id="a-title" name="a title"> + <title>A Title + A paragraph. +
+ + + Pseudo-XML:: + + +
+ + A Title + <paragraph> + A paragraph. + +-------------------- + +Many of the element reference sections below are marked "_`to be +completed`". Please help complete this document by contributing to +its writing. + + +``attention`` +============= + +`To be completed`_. + + +``author`` +========== + +`To be completed`_. + + +``authors`` +=========== + +`To be completed`_. + + +``block_quote`` +=============== + +`To be completed`_. + + +``bullet_list`` +=============== + +`To be completed`_. + + +``caption`` +=========== + +`To be completed`_. + + +``caution`` +=========== + +`To be completed`_. + + +``citation`` +============ + +`To be completed`_. + + +``citation_reference`` +====================== + +`To be completed`_. + + +``classifier`` +============== + +`To be completed`_. + + +``colspec`` +=========== + +`To be completed`_. + + +``comment`` +=========== + +`To be completed`_. + + +``contact`` +=========== + +`To be completed`_. + + +``copyright`` +============= + +`To be completed`_. + + +``danger`` +========== + +`To be completed`_. + + +``date`` +======== + +`To be completed`_. + + +``decoration`` +============== + +`To be completed`_. + + +``definition`` +============== + +`To be completed`_. + + +``definition_list`` +=================== + +`To be completed`_. + + +``definition_list_item`` +======================== + +`To be completed`_. + + +``description`` +=============== + +`To be completed`_. + + +``docinfo`` +=========== + +`To be completed`_. + + +``doctest_block`` +================= + +`To be completed`_. ``document`` @@ -144,9 +413,24 @@ section below. Each section contains the following subsections: Description ----------- +Element category: `structural elements`_. + The ``document`` element is the root (topmost) element of the Docutils document tree. ``document`` is the direct or indirect ancestor of -every other element in the tree. +every other element in the tree. It encloses the entire document +tree. It is the starting point for a document. + +Parents + The ``document`` element has no parents. + +Children + ``document`` elements may contain the following elements: title_, + subtitle_, docinfo_, decoration_, topic_, transition_, section_, + and `body elements`_. + +Analogies + ``document`` is analogous to the HTML "html" element and several + DocBook elements such as "book". Content Model @@ -155,162 +439,968 @@ Content Model .. parsed-literal:: ((title_, - subtitle_?)?, - docinfo_?, - decoration_?, + subtitle_?)?, + docinfo_?, + decoration_?, `%structure.model;`_) +Depending on the source of the data and the stage of processing, the +"document" may not initially contain a "title". A document title is +not directly representable in reStructuredText_. Instead, a lone +top-level section may have its title promoted to become the document +title_, and similarly for a lone second-level (sub)section's title to +become the document subtitle_. The "docinfo_" may be transformed from +an initial field_list_, and "decoration_" is usually constructed +programmatically. Attributes -`````````` - -`Common external attributes`_. + The ``document`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. Example ------- +reStructuredText source:: ---------------------- - Attribute Reference ---------------------- + A Title + ======= -.. contents:: - :local: - :depth: 1 + A paragraph. -Through the `%basic.atts;`_ parameter entity, all elements share the -following _`common external attributes`: id_, name_, dupname_, -source_, class_. +Complete pseudo-XML_ result from simple parsing:: + <document> + <section id="a-title" name="a title"> + <title> + A Title + <paragraph> + A paragraph. -``anonymous`` -============= +After applying transforms, the section title is promoted to become the +document title:: -The ``anonymous`` attribute + <document id="a-title" name="a title"> + <title> + A Title + <paragraph> + A paragraph. -``auto`` -======== +``emphasis`` +============ -The ``auto`` attribute +`To be completed`_. -``class`` +``entry`` ========= -The ``class`` attribute +`To be completed`_. -``dupname`` -=========== +``enumerated_list`` +=================== -The ``dupname`` attribute +`To be completed`_. -``id`` -====== +``error`` +========= -The ``id`` attribute +`To be completed`_. -``name`` +``field`` +========= + +`To be completed`_. + + +``field_argument`` +================== + +`To be completed`_. + + +``field_body`` +============== + +`To be completed`_. + + +``field_list`` +============== + +`To be completed`_. + + +``field_name`` +============== + +`To be completed`_. + + +``figure`` +========== + +`To be completed`_. + + +``footer`` +========== + +`To be completed`_. + + +``footnote`` +============ + +`To be completed`_. + + +``footnote_reference`` +====================== + +`To be completed`_. + + +``generated`` +============= + +`To be completed`_. + + +``header`` +========== + +`To be completed`_. + + +``hint`` ======== -The ``name`` attribute +`To be completed`_. -``refid`` +``image`` ========= -The ``refid`` attribute +`To be completed`_. -``refname`` -=========== +``important`` +============= -The ``refname`` attribute +`To be completed`_. -``refuri`` -========== +``interpreted`` +=============== -The ``refuri`` attribute +`To be completed`_. -``source`` +``label`` +========= + +`To be completed`_. + + +``legend`` ========== -The ``source`` attribute +`To be completed`_. -``xml:space`` +``line_block`` +============== + +`To be completed`_. + + +``list_item`` ============= -The ``xml:space`` attribute +`To be completed`_. ------------------------- - DTD Parameter Entities ------------------------- +``literal`` +=========== -.. contents:: - :local: - :depth: 1 +`To be completed`_. -``%basic.atts;`` -================ +``literal_block`` +================= -The ``%basic.atts;`` parameter entity lists attributes common to all -elements. See `Common Attributes`_. +`To be completed`_. -``%body.elements;`` +``note`` +======== + +`To be completed`_. + + +``option`` +========== + +`To be completed`_. + + +``option_argument`` =================== -The ``%body.elements;`` parameter entity +`To be completed`_. -``%inline.elements;`` -===================== +``option_group`` +================ -The ``%inline.elements;`` parameter entity +`To be completed`_. -``%reference.atts;`` +``option_list`` +=============== + +`To be completed`_. + + +``option_list_item`` ==================== -The ``%reference.atts;`` parameter entity +`To be completed`_. -``%structure.model;`` -===================== +``option_string`` +================= -The ``%structure.model;`` parameter entity +`To be completed`_. -``%text.model;`` +``organization`` ================ -The ``%text.model;`` parameter entity +`To be completed`_. ----------------------- - Miscellaneous Topics ----------------------- +``paragraph`` +============= + +`To be completed`_. + + +``pending`` +=========== + +`To be completed`_. + + +``problematic`` +=============== + +`To be completed`_. + + +``raw`` +======= + +`To be completed`_. + + +``reference`` +============= + +`To be completed`_. + + +``revision`` +============ + +`To be completed`_. -.. contents:: - :local: - :depth: 1 +``row`` +======= + +`To be completed`_. + + +``section`` +=========== + +`To be completed`_. + + +``status`` +========== + +`To be completed`_. + + +``strong`` +========== + +`To be completed`_. + + +``substitution_definition`` +=========================== + +`To be completed`_. + + +``substitution_reference`` +========================== + +`To be completed`_. + + +``subtitle`` +============ + +Description +----------- + +Element category: `structural subelements`_. + +The ``subtitle`` element stores the subtitle of a document_. + +Parents + The following elements may contain ``subtitle``: document_. + +Children + ``subtitle`` elements may contain text data plus `inline + elements`_. + +Analogies + ``subtitle`` is analogous to HTML header elements ("h2" etc.) and + the DocBook "subtitle" element. + +Processing + A document's subtitle is usually rendered smaller than its title_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``subtitle`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Example +------- + +reStructuredText source:: + + ======= + Title + ======= + ---------- + Subtitle + ---------- + + A paragraph. + +Complete pseudo-XML_ result after parsing and transforms applied:: + + <document id="title" name="title"> + <title> + Title + <subtitle id="subtitle" name="subtitle"> + Subtitle + <paragraph> + A paragraph. + +Note how two section levels have collapsed, promoting their titles to +become the document's title and subtitle. Since there is only one +structural element (document), the subsection's ``id`` and ``name`` +attributes are stored in the ``subtitle`` element. + + +``system_message`` +================== + +`To be completed`_. + + +``table`` +========= + +`To be completed`_. + + +``target`` +========== + +`To be completed`_. + + +``tbody`` +========= + +`To be completed`_. + + +``term`` +======== + +`To be completed`_. + + +``tgroup`` +========== + +`To be completed`_. + + +``thead`` +========= + +`To be completed`_. + + +``tip`` +======= + +`To be completed`_. + + +``title`` +========= + +Description +----------- + +Element category: `structural subelements`_. + +The ``title`` element stores the title of a document_, section_, or +topic_. + +Parents + The following elements may contain ``title``: document_, section_, + topic_. + +Children + ``title`` elements may contain text data plus `inline elements`_. + +Analogies + ``title`` is analogous to HTML "title" and header ("h1" etc.) + elements, and DocBook "title" elements. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``title`` element contains the `common attributes`_ (id_, + name_, dupname_, source_, and class_), refid_, and auto_. + + ``refid`` is used as a backlink to a table of contents entry. + + ``auto`` is used to indicate (with value "1") that the ``title`` + has been numbered automatically. + + +Example +------- + +reStructuredText source:: + + A Title + ======= + + A paragraph. + +Pseudo-XML_ fragment from simple parsing:: + + <section id="a-title" name="a title"> + <title> + A Title + <paragraph> + A paragraph. + + +``topic`` +========= + +`To be completed`_. + + +``transition`` +============== + +`To be completed`_. + + +``version`` +=========== + +`To be completed`_. + + +``warning`` +=========== + +`To be completed`_. + + +--------------------- + Attribute Reference +--------------------- + +.. contents:: :local: + :depth: 1 + +_`Common Attributes`: Through the `%basic.atts;`_ parameter entity, +all elements contain the following attributes: id_, name_, dupname_, +source_, and class_. + +.. _attribute type: + +Attribute types: + +``CDATA`` + Character data. ``CDATA`` attributes may contain arbitrary text. + +``ID`` + Like a ``NMTOKEN``, but it must begin with a letter (a "name + production"). Identical ``ID`` values must not appear more than + once in a document; i.e., ID values must uniquely identify their + elements. + +``IDREF`` + A reference to an ``ID`` value (a name production) of another + element. + +``IDREFS`` + One or more space-separated ``ID`` references (name productions). + +``NMTOKEN`` + A "name token". One or more of letters, digits, ".", "-", and + "_". + +``NMTOKENS`` + One or more space-separated ``NMTOKEN`` names. + +``%yesorno;`` + No if zero ("0"), yes if any other value. This is a parameter + entity which resolves to a ``NMTOKEN`` attribute type. + +``%number;`` + This emphasizes that the attribute value must be a number. This + is a parameter entity which resolves to a ``NMTOKEN`` attribute + type. + + +``anonymous`` +============= + +`Attribute type`_: ``%yesorno;``. Default value: none (implies no). + +The ``anonymous`` attribute is used for unnamed hyperlinks in the +target_ and reference_ elements. + + +``auto`` +======== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``auto`` attribute is used to indicate an automatically-numbered +footnote_, footnote_reference_ or title_. + + +``backrefs`` +============ + +`Attribute type`_: ``IDREFS``. Default value: none. + +The ``backrefs`` attribute contains a space-separated list of id_ +references, used for backlinks from footnote_, citation_, and +system_message_ elements. + + +``class`` +========= + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``class`` attribute contains one or more names used to classify or +subclassify an element. It can be used to carry context forward +between a Docutils Reader and Writer, when a custom structure is +reduced to a standardized document tree. ``class`` is one of the `common +attributes`_, shared by all Docutils elements. + + +``dupname`` +=========== + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``dupname`` attribute contains the name of an element when there +has been a naming conflict. The contents of the ``dupname`` attribute +would have been transferred from the `name`_ attribute. An element +may have at most one of the ``name`` or ``dupname`` attributes, but +not both. ``dupname`` is one of the `common attributes`_, shared by +all Docutils elements. + + +``id`` +====== + +`Attribute type`_: ``ID``. Default value: none. + +The ``id`` attribute contains a unique identifier key. ``id`` is one +of the `common attributes`_, shared by all Docutils elements. + + +``name`` +======== + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``name`` attribute contains the name of an element, typically +originating from the element's title or content. ``name`` must be +unique; if there are name conflicts (two or more elements want to the +same name), the contents will be transferred to the `dupname`_ +attribute on the duplicate elements. An element may have at most one +of the ``name`` or ``dupname`` attributes, but not both. ``name`` is +one of the `common attributes`_, shared by all Docutils elements. + + +``refid`` +========= + +`Attribute type`_: ``IDREF``. Default value: none. + +The ``refid`` attribute contains references to `id`_ attributes in +other elements. It is used by the target_, reference_, +footnote_reference_, citation_reference_, title_ and problematic_ +elements. + + +``refname`` +=========== + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``refname`` attribute contains an internal reference to the +`name`_ attribute of another element. On a `target`_ element, +``refname`` indicates an indirect target which may resolve to either +an internal or external reference. ``refname`` is used by the +target_, reference_, footnote_reference_, citation_reference_, and +substitution_reference_ elements. + + +``refuri`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``refuri`` attribute contains an external reference to a URI/URL. +It is used by the target_, reference_, footnote_reference_, and +citation_reference_ elements. + + +``source`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``source`` attribute is used to store the path or URL to the +source text that was used to produce the document tree. It is one of +the `common attributes`_, shared by all Docutils elements. + + +``xml:space`` +============= + +`Attribute type`_: one of "default" or "preserve". Default value: +"preserve" (fixed). + +The ``xml:space`` attribute is a standard XML attribute for +whitespace-preserving elements. It is used by the literal_block_, +line_block_, doctest_block_, comment_, and raw_ elements. It is a +fixed attribute, meant to communicate to an XML parser that the +element contains significant whitespace. The attribute value should +not be set in a document instance. + + +-------------------- + Parameter Entities +-------------------- + +.. contents:: :local: + :depth: 1 + +Parameter entities are used to simplify the DTD (to share definitions +and reduce duplication) and to allow the DTD to be customized by +wrapper DTDs (external client DTDs that use or import the Docutils +DTD). Parameter entities may be overridden by wrapper DTDs, replacing +the definitions below with custom definitions. Parameter entities +whose names begin with "additional" are meant to allow easy extension +by wrapper DTDs. + + +``%anonymous.att;`` +=================== + +The ``%anonymous.att;`` parameter entity contains the anonymous_ +attribute, used for unnamed hyperlinks. + +Entity definition: + +.. parsed-literal:: + + anonymous %yesorno; #IMPLIED + + +``%auto.att;`` +============== + +The ``%auto.att;`` parameter entity contains the auto_ attribute, used +to indicate an automatically-numbered footnote or title. + +Entity definition: + +.. parsed-literal:: + + auto_ CDATA #IMPLIED + + +``%backrefs.att;`` +================== + +The ``%backrefs.att;`` parameter entity contains the backrefs_ +attribute, a space-separated list of id references, for backlinks. + +Entity definition: + +.. parsed-literal:: + + backrefs_ IDREFS #IMPLIED + + +``%basic.atts;`` +================ + +The ``%basic.atts;`` parameter entity lists attributes common to all +elements. See `Common Attributes`_. + +Entity definition: + +.. parsed-literal:: + + id_ ID #IMPLIED + name_ NMTOKENS #IMPLIED + dupname_ NMTOKENS #IMPLIED + source_ CDATA #IMPLIED + class_ NMTOKENS #IMPLIED + %additional.basic.atts; + +The ``%additional.basic.atts;`` parameter entity can be used by +wrapper DTDs to extend ``%basic.atts;``. + + +``%body.elements;`` +=================== + +The ``%body.elements;`` parameter entity contains an OR-list of all +`body elements`_. + +Entity definition: + +.. parsed-literal:: + + paragraph_ | literal_block_ | doctest_block_ | line_block_ + | block_quote_ | table_ | figure_ | image_ | footnote_ | citation_ + | bullet_list_ | enumerated_list_ | definition_list_ | field_list_ + | option_list_ + | attention_ | caution_ | danger_ | error_ | hint_ | important_ + | note_ | tip_ | warning_ + | target_ | substitution_definition_ | comment_ | pending_ + | system_message_ | raw_ + %additional.body.elements; + +The ``%additional.body.elements;`` parameter entity can be used by +wrapper DTDs to extend ``%body.elements;``. + + +``%fixedspace.att;`` +==================== + +The ``%fixedspace.att;`` parameter entity contains the `xml:space`_ +attribute, a standard XML attribute for whitespace-preserving +elements. + +Entity definition: + +.. parsed-literal:: + + xml:space (default | preserve) #FIXED 'preserve' + + +``%inline.elements;`` +===================== + +The ``%inline.elements;`` parameter entity contains an OR-list of all +`inline elements`_. + +Entity definition: + +.. parsed-literal:: + + emphasis_ | strong_ | interpreted_ | literal_ + | reference_ | footnote_reference_ | citation_reference_ + | substitution_reference_ | problematic_ | generated_ + | target_ | image_ | raw_ + %additional.inline.elements; + +The ``%additional.inline.elements;`` parameter entity can be used by +wrapper DTDs to extend ``%inline.elements;``. + + +``%reference.atts;`` +==================== + +The ``%reference.atts;`` parameter entity groups together the refuri_, +refid_, and refname_ attributes. + +Entity definition: + +.. parsed-literal:: + + `%refuri.att;`_ + `%refid.att;`_ + `%refname.att;`_ + %additional.reference.atts; + +The ``%additional.reference.atts;`` parameter entity can be used by +wrapper DTDs to extend ``%additional.reference.atts;``. + + +``%refid.att;`` +================ + +The ``%refid.att;`` parameter entity contains the refid_ attribute, an +internal reference to the `id`_ attribute of another element. + +Entity definition: + +.. parsed-literal:: + + refid_ CDATA #IMPLIED + + +``%refname.att;`` +================= + +The ``%refname.att;`` parameter entity contains the refname_ +attribute, an internal reference to the `name`_ attribute of another +element. On a `target`_ element, ``refname`` indicates an indirect +target which may resolve to either an internal or external +reference. + +Entity definition: + +.. parsed-literal:: + + refname_ NMTOKENS #IMPLIED + + +``%refuri.att;`` +================ + +The ``%refuri.att;`` parameter entity contains the refuri_ attribute, +an external reference to a URI/URL. + +Entity definition: + +.. parsed-literal:: + + refuri_ CDATA #IMPLIED + + +``%section.elements;`` +====================== + +The ``%section.elements;`` parameter entity contains an OR-list of +all section_-equivalent elements. + +Entity definition: + +.. parsed-literal:: + + section_ + %additional.section.elements; + +The ``%additional.section.elements;`` parameter entity can be used +by wrapper DTDs to extend ``%section.elements;``. + + +``%structure.model;`` +===================== + +The ``%structure.model;`` parameter entity is used by document_ and +section_ elements. It encapsulates the section structure of a +document and of parts of that document. See the discussion of the +`element hierarchy`_ above. + +Entity definition: + +.. parsed-literal:: + + ( ( (`%body.elements;`_ | topic_)+, + (transition_, (`%body.elements;`_ | topic_)+ )*, + (`%section.elements;`_)* ) + | (`%section.elements;`_)+ ) + +Each document_ or section_ contains either: + +- multiple body elements and/or topics, optionally interspersed with + transitions (but transitions cannot occur at the beginning or end, + nor may there be two transitions in a row), followed by zero or more + sections; or + +- one or more sections (whose contents are recursively the same as this + model). + + +``%text.model;`` +================ + +The ``%text.model;`` parameter entity is used by many elements to +represent text data mixed with `inline elements`_. + +Entity definition: + +.. parsed-literal:: + + (#PCDATA | `%inline.elements;`_)* + + +---------------------- + Miscellaneous Topics +---------------------- Representation of Horizontal Rules ================================== -Having added the "horizontal rule" construct to the reStructuredText_ -spec, a decision had to be made as to how to reflect the construct in -the implementation of the document tree. Given this source:: +Having added the "horizontal rule" construct to the `reStructuredText +Markup Specification`_, a decision had to be made as to how to reflect +the construct in the implementation of the document tree. Given this +source:: Document ======== @@ -399,8 +1489,6 @@ There are several possibilities for the implementation: Solution 3 was chosen for incorporation into the document tree model. -.. _reStructuredText: - http://docutils.sourceforge.net/spec/rst/reStructuredText.html .. -- cgit v1.2.1 From 07f935fcc9b913de724ddf60ac5e1eecb062b0e5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 01:26:56 +0000 Subject: editorial improvements git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@551 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index dbbec83fa..3e9d2da41 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -17,6 +17,12 @@ Directives have the following syntax:: | | +--------------------------+ +Directives begin with an explicit markup start (two periods and a +space), followed by the directive type, two colons, optional directive +data (on the same line as the directive type) and an optional +directive block (on subsequent lines). The directive block is +indented, aligned with the left edge of the directive type. + .. contents:: @@ -201,10 +207,13 @@ DTD element: line_block. Directive block: directive data and all following indented text become the body of the line block. -The "line-block" directive constructs a paragraph-like element where -leading whitespace and linebreaks are significant and inline markup is -supported. This is useful for address blocks and verse (poetry, song -lyrics). For example:: +The "line-block" directive constructs an element where whitespace +(including linebreaks) is significant and inline markup is supported. +It is equivalent to a `parsed literal block`_ with different +rendering: typically in an ordinary serif typeface instead of a +typewriter/monospaced face. Line blocks are useful for address blocks +and verse (poetry, song lyrics), where the structure of lines is +significant. For example, here's a classic:: "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by Ewan McTeagle (for Lassie O'Shea): @@ -228,8 +237,13 @@ the body of the literal block. Unlike an ordinary literal block, the "parsed-literal" directive constructs a literal block where the text is parsed for inline markup. -This is useful for adding hyperlinks to code examples. For example, -all the element names in this content model are links:: +It is equivalent to a `line block`_ with different rendering: +typically in a typewriter/monospaced typeface, like an ordinary +literal block. Parsed literal blocks are useful for adding hyperlinks +to code examples. However, care must be taken with the text, because +inline markup is recognized; there is no protection from parsing. + +For example, all the element names in this content model are links:: .. parsed-literal:: -- cgit v1.2.1 From 47f1e25c94da9b7ca9e974804cc21d4c8e4d0496 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 01:29:09 +0000 Subject: - Added ``%number;`` attribute type parameter entity. - Changed ``%structural.elements;`` to ``%section.elements``. - Updated attribute types; made more specific. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@552 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 56 ++++++++++++++++++++++++--------------------------- 1 file changed, 26 insertions(+), 30 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 5b7e8aac4..0e328bb34 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -19,15 +19,14 @@ The proposed formal public identifier for this DTD is:: +//IDN python.org//DTD Docutils Generic//EN//XML --> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Parameter Entities ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Parameter entities are used to simplify the DTD (reduce duplication) -and to allow the DTD to be customized by wrapper DTDs. Parameter -entities beginning with 'additional' are meant to allow easy extension +and to allow the DTD to be customized by wrapper DTDs. Parameter +entities beginning with "additional" are meant to allow easy extension by wrapper DTDs. --> @@ -37,6 +36,9 @@ by wrapper DTDs. <!-- Boolean: no if zero(s), yes if any other value. --> <!ENTITY % yesorno "NMTOKEN"> +<!-- Emphasize that the attribute value must be a number. --> +<!ENTITY % number "NMTOKEN"> + <!ENTITY % additional.basic.atts ""> <!-- Attributes shared by all elements in this DTD: @@ -49,10 +51,10 @@ Attributes shared by all elements in this DTD: --> <!ENTITY % basic.atts " id ID #IMPLIED - name CDATA #IMPLIED - dupname CDATA #IMPLIED + name NMTOKENS #IMPLIED + dupname NMTOKENS #IMPLIED source CDATA #IMPLIED - class CDATA #IMPLIED + class NMTOKENS #IMPLIED %additional.basic.atts; "> <!-- External reference to a URI/URL. --> @@ -73,7 +75,7 @@ Internal reference to the `name` attribute of an element. On a resolve to either an internal or external reference. --> <!ENTITY % refname.att - " refname CDATA #IMPLIED "> + " refname NMTOKENS #IMPLIED "> <!ENTITY % additional.reference.atts ""> <!-- Collected hyperlink reference attributes. --> @@ -89,7 +91,7 @@ resolve to either an internal or external reference. <!-- Auto-numbered footnote or title. --> <!ENTITY % auto.att - " auto %yesorno; #IMPLIED "> + " auto CDATA #IMPLIED "> <!-- XML standard attribute for whitespace-preserving elements. --> <!ENTITY % fixedspace.att @@ -106,10 +108,10 @@ resolve to either an internal or external reference. | field %additional.bibliographic.elements; "> -<!ENTITY % additional.structural.elements ""> -<!ENTITY % structural.elements +<!ENTITY % additional.section.elements ""> +<!ENTITY % section.elements " section - %additional.structural.elements; "> + %additional.section.elements; "> <!ENTITY % additional.body.elements ""> <!ENTITY % body.elements @@ -131,18 +133,20 @@ resolve to either an internal or external reference. | target | image | raw %additional.inline.elements; "> + <!-- Element Content Models ================================================================== --> <!ENTITY % structure.model " ( ( (%body.elements; | topic)+, (transition, (%body.elements; | topic)+ )*, - (%structural.elements;)* ) - | (%structural.elements;)+ ) "> + (%section.elements;)* ) + | (%section.elements;)+ ) "> <!ENTITY % text.model " (#PCDATA | %inline.elements;)* "> + <!-- Table Model ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -165,8 +169,7 @@ http://www.oasis-open.org/html/tm9901.htm). <!ENTITY % tbl.entry.mdl " (%body.elements;)* "> <!ENTITY % tbl.entry.att " %basic.atts; - morecols NMTOKEN #IMPLIED "> - + morecols %number; #IMPLIED "> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -179,7 +182,6 @@ http://www.oasis-open.org/html/tm9901.htm). ((title, subtitle?)?, docinfo?, decoration?, %structure.model;)> <!ATTLIST document %basic.atts;> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Title Elements @@ -195,7 +197,6 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT subtitle %text.model;> <!ATTLIST subtitle %basic.atts;> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Bibliographic Elements @@ -233,7 +234,6 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT copyright %text.model;> <!ATTLIST copyright %basic.atts;> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Decoration Elements @@ -249,7 +249,6 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT footer (%body.elements;)+> <!ATTLIST footer %basic.atts;> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Structural Elements @@ -265,7 +264,6 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT transition EMPTY> <!ATTLIST transition %basic.atts;> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Body Elements @@ -288,7 +286,7 @@ http://www.oasis-open.org/html/tm9901.htm). #IMPLIED prefix CDATA #IMPLIED suffix CDATA #IMPLIED - start NUMBER #IMPLIED> + start %number; #IMPLIED> <!ELEMENT list_item (%body.elements;)+> <!ATTLIST list_item %basic.atts;> @@ -440,9 +438,9 @@ either the string separating it from the `option` (typically either %basic.atts; uri CDATA #REQUIRED alt CDATA #IMPLIED - height NMTOKEN #IMPLIED - width NMTOKEN #IMPLIED - scale NMTOKEN #IMPLIED> + height &number; #IMPLIED + width &number; #IMPLIED + scale &number; #IMPLIED> <!ELEMENT caption %text.model;> <!ATTLIST caption %basic.atts;> @@ -460,16 +458,15 @@ Table elements: table, tgroup, colspec, thead, tbody, row, entry. <!ATTLIST system_message %basic.atts; %backrefs.att; - level NMTOKEN #IMPLIED - type CDATA #IMPLIED> + level &number; #IMPLIED + type NMTOKEN #IMPLIED> <!-- Used to pass raw data through the system. Also inline. --> <!ELEMENT raw %text.model;> <!ATTLIST raw %basic.atts; %fixedspace.att; - format CDATA #IMPLIED> - + format NMTOKEN #IMPLIED> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -497,7 +494,7 @@ following caveats: <!ELEMENT interpreted (%text.model;)> <!ATTLIST interpreted %basic.atts; - role CDATA #IMPLIED + role NMTOKEN #IMPLIED position (prefix | suffix) #IMPLIED> <!ELEMENT literal (#PCDATA)> @@ -533,7 +530,6 @@ following caveats: <!ELEMENT generated (%text.model;)> <!ATTLIST generated %basic.atts;> - <!-- Local Variables: mode: sgml -- cgit v1.2.1 From aebb476aeb2df374d2f34c9ee9166ea3967317b0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 01:38:39 +0000 Subject: Made the element subsection entitled "Description" implicit, because it interfered with the "description" element. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@554 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index bcf983971..50564348e 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -217,7 +217,8 @@ Each element in the DTD (document type definition) is described in its own section below. Each section contains the following subsections and items: -* Description: The semantics of the element. +* The initial text contains a description of the semantics of the + element, plus: - Parents: A list of elements which may contain the element. @@ -410,9 +411,6 @@ its writing. ``document`` ============ -Description ------------ - Element category: `structural elements`_. The ``document`` element is the root (topmost) element of the Docutils @@ -760,9 +758,6 @@ document title:: ``subtitle`` ============ -Description ------------ - Element category: `structural subelements`_. The ``subtitle`` element stores the subtitle of a document_. @@ -875,9 +870,6 @@ attributes are stored in the ``subtitle`` element. ``title`` ========= -Description ------------ - Element category: `structural subelements`_. The ``title`` element stores the title of a document_, section_, or -- cgit v1.2.1 From e7ec9616617696f83df6abe5c96e5ab85357fa6a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 01:46:49 +0000 Subject: tweaks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@555 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 50564348e..6e9bc3b80 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -896,7 +896,7 @@ Content Model Attributes The ``title`` element contains the `common attributes`_ (id_, - name_, dupname_, source_, and class_), refid_, and auto_. + name_, dupname_, source_, and class_), plus refid_ and auto_. ``refid`` is used as a backlink to a table of contents entry. @@ -1155,7 +1155,7 @@ Entity definition: .. parsed-literal:: - anonymous %yesorno; #IMPLIED + anonymous_ %yesorno; #IMPLIED ``%auto.att;`` @@ -1181,7 +1181,7 @@ Entity definition: .. parsed-literal:: - backrefs_ IDREFS #IMPLIED + backrefs_ IDREFS #IMPLIED ``%basic.atts;`` @@ -1240,7 +1240,7 @@ Entity definition: .. parsed-literal:: - xml:space (default | preserve) #FIXED 'preserve' + `xml:space`_ (default | preserve) #FIXED 'preserve' ``%inline.elements;`` -- cgit v1.2.1 From 7a665930bde84725f54d7a0236679682249d5e03 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 02:06:44 +0000 Subject: more tweaks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@556 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 6e9bc3b80..ca5bb0aaa 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -24,9 +24,9 @@ found in internal documentation (docstrings) for the implemented in a class library. The reader is assumed to have some familiarity with XML or SGML, and -an understanding the data structure meaning of "tree". For a list of -introductory articles, see `Introducing the Extensible Markup Language -(XML)`_. +an understanding of the data structure meaning of "tree". For a list +of introductory articles, see `Introducing the Extensible Markup +Language (XML)`_. The reStructuredText_ markup is used for illustrative examples throughout this document. For a gentle introduction, see `A @@ -186,7 +186,7 @@ Category members: caption_, classifier_, colspec_, definition_, definition_list_item_, description_, entry_, field_, field_argument_, field_body_, field_name_, label_, legend_, list_item_, option_, option_argument_, option_group_, option_list_item_, option_string_, -row_, tbody_, term_, tgroup_, thead +row_, tbody_, term_, tgroup_, thead_ Inline Elements @@ -1028,10 +1028,10 @@ system_message_ elements. `Attribute type`_: ``NMTOKENS``. Default value: none. -The ``class`` attribute contains one or more names used to classify or -subclassify an element. It can be used to carry context forward -between a Docutils Reader and Writer, when a custom structure is -reduced to a standardized document tree. ``class`` is one of the `common +The ``class`` attribute contains one or more names used to classify an +element. It can be used to carry context forward between a Docutils +Reader and Writer, when a custom structure is reduced to a +standardized document tree. ``class`` is one of the `common attributes`_, shared by all Docutils elements. -- cgit v1.2.1 From 9631ca774f2b84f2cd7ae2fb83090308a609ac5e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 16:12:59 +0000 Subject: Added missing ``%bibliographic.elements;`` parameter entity. More tweaks. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@557 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index ca5bb0aaa..0253908b5 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -10,13 +10,15 @@ A Guide to the Docutils DTD :Revision: $Revision$ :Date: $Date$ + .. contents:: :depth: 1 -This document describes the XML data structure of Docutils_ documents, -the relationships and semantics of elements. The Docutils document -structure is formally defined by the `Docutils Generic DTD`_ XML -document type definition, docutils.dtd_, which is the definitive -source for details of element structural relationships. + +This document describes the XML data structure of Docutils_ documents: +the relationships and semantics of elements and attributes. The +Docutils document structure is formally defined by the `Docutils +Generic DTD`_ XML document type definition, docutils.dtd_, which is +the definitive source for details of element structural relationships. This document does not discuss implementation details. Those can be found in internal documentation (docstrings) for the @@ -803,7 +805,7 @@ reStructuredText source:: A paragraph. -Complete pseudo-XML_ result after parsing and transforms applied:: +Complete pseudo-XML_ result after parsing and applying transforms:: <document id="title" name="title"> <title> @@ -1205,6 +1207,25 @@ The ``%additional.basic.atts;`` parameter entity can be used by wrapper DTDs to extend ``%basic.atts;``. +``%bibliographic.elements;`` +============================ + +The ``%bibliographic.elements;`` parameter entity contains an OR-list of all +`bibliographic elements`_. + +Entity definition: + +.. parsed-literal:: + + author_ | authors_ | organization_ | contact_ + | version_ | revision_ | status_ | date_ | copyright_ + | field_ + %additional.bibliographic.elements; + +The ``%additional.bibliographic.elements;`` parameter entity can be used by +wrapper DTDs to extend ``%bibliographic.elements;``. + + ``%body.elements;`` =================== -- cgit v1.2.1 From 408dc71030378fa9541310582a98df85b43ed8e9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 17:13:15 +0000 Subject: updated/fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@561 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/introduction.txt | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index 3ca6de778..ea5c6ca90 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -19,9 +19,9 @@ application domains. Its parser is a component of Docutils_. This document defines the goals_ of reStructuredText and provides a history_ of the project. It is written using the reStructuredText markup, and therefore serves as an example of its use. Please also -see an analysis of the `problems with StructuredText`_ and the -`reStructuredText markup specification`_ itself at project's web page, -http://docutils.sourceforge.net/rst.html. +see an analysis of the `Problems With StructuredText`_ and the +`reStructuredText Markup Specification`_ itself at the subproject's +web page, http://docutils.sourceforge.net/rst.html. .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _StructuredText: @@ -145,8 +145,8 @@ History reStructuredText_, the specification, is based on StructuredText_ and Setext_. StructuredText was developed by Jim Fulton of `Zope Corporation`_ (formerly Digital Creations) and first released in 1996. -It is now released as a part of the open-source 'Z Object Publishing -Environment' (ZOPE_). Ian Feldman's and Tony Sanders' earlier Setext_ +It is now released as a part of the open-source "Z Object Publishing +Environment" (ZOPE_). Ian Feldman's and Tony Sanders' earlier Setext_ specification was either an influence on StructuredText or, by their similarities, at least evidence of the correctness of this approach. @@ -157,13 +157,13 @@ I was not able to get pythondoc to work for me, I found StructuredText to be almost ideal for my needs. I joined the Python Doc-SIG_ (Documentation Special Interest Group) mailing list and found an ongoing discussion of the shortcomings of the StructuredText -'standard'. This discussion has been going on since the inception of +"standard". This discussion has been going on since the inception of the mailing list in 1996, and possibly predates it. I decided to modify the original module with my own extensions and some suggested by the Doc-SIG members. I soon realized that the module was not written with extension in mind, so I embarked upon a -general reworking, including adapting it to the 're' regular +general reworking, including adapting it to the "re" regular expression module (the original inspiration for the name of this project). Soon after I completed the modifications, I discovered that StructuredText.py was up to version 1.23 in the ZOPE distribution. @@ -178,7 +178,7 @@ StructuredText. I decided that a complete rewrite was in order, and even started a `reStructuredText SourceForge project`_ (now inactive). My -motivations (the 'itches' I aim to 'scratch') are as follows: +motivations (the "itches" I aim to "scratch") are as follows: - I need a standard format for inline documentation of the programs I write. This inline documentation has to be convertible to other @@ -229,7 +229,7 @@ June 2001, including posting the second draft of the spec [#spec-2]_ and the first draft of PEPs 256, 257, and 258 [#peps-1]_ to the Doc-SIG. These documents and the project implementation proceeded to evolve at a rapid pace. Implementation history details can be found -in the project file, HISTORY.txt_. +in the `project history file`_. In November 2001, the reStructuredText parser was nearing completion. Development of the parser continued with the addition of small @@ -253,7 +253,8 @@ followed. .. __: `reStructuredText SourceForge project`_ -.. [#spec-2] +.. [#spec-2] The second draft of the spec: + - `An Introduction to reStructuredText`__ - `Problems With StructuredText`__ - `reStructuredText Markup Specification`__ @@ -265,7 +266,8 @@ followed. __ http://mail.python.org/pipermail/doc-sig/2001-June/001860.html __ http://mail.python.org/pipermail/doc-sig/2001-June/001861.html -.. [#peps-1] +.. [#peps-1] First drafts of the PEPs: + - `PEP 256: Docstring Processing System Framework`__ - `PEP 258: DPS Generic Implementation Details`__ - `PEP 257: Docstring Conventions`__ @@ -286,11 +288,10 @@ followed. .. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ .. _StructuredTextNG: http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG -.. _HISTORY.txt: - http://docutils.sourceforge.net/HISTORY.txt -.. _PEP 287: http://docutils.sourceforge.net/spec/pep-0287.txt +.. _project history file: http://docutils.sourceforge.net/HISTORY.html +.. _PEP 287: http://docutils.sourceforge.net/spec/pep-0287.html .. _Docstring Processing System framework: - http://docutils.sourceforge.net/spec/pep-0256.txt + http://docutils.sourceforge.net/spec/pep-0256.html .. _comp.lang.python: news:comp.lang.python .. _Python-dev: http://mail.python.org/pipermail/python-dev/ .. _Docstring Processing System: http://docstring.sourceforge.net/ -- cgit v1.2.1 From abac0fa413311365e8db58fde6dc403759778fe6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 17:34:43 +0000 Subject: more tweaks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@562 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 0253908b5..6ee5d1e97 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -113,26 +113,27 @@ Structural subelements are child elements of structural elements, but contain no further structure of their own (except for text and inline elements). -Category members: title_, subtitle_, transition_ +Category members: title_, subtitle_, docinfo_, decoration_, +transition_ Bibliographic Elements ----------------------- +`````````````````````` The docinfo_ element is an optional child of document_. It groups bibliographic elements together. -Category members: docinfo_, author_, authors_, contact_, copyright_, -date_, organization_, revision_, status_, version_ +Category members: author_, authors_, contact_, copyright_, date_, +organization_, revision_, status_, version_ Decorative Elements -------------------- +``````````````````` The decoration_ element is also an optional child of document_. It groups together elements used to generate page headers and footers. -Category members: decoration_, footer_, header_ +Category members: footer_, header_ Body Elements -- cgit v1.2.1 From 8bc9ccd896a49fbc07aef3fcd4d3178e0f2e58c7 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 18 Aug 2002 15:38:06 +0000 Subject: tweaked the subsections some more git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@563 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 134 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 79 insertions(+), 55 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 6ee5d1e97..622243ec5 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -124,7 +124,7 @@ The docinfo_ element is an optional child of document_. It groups bibliographic elements together. Category members: author_, authors_, contact_, copyright_, date_, -organization_, revision_, status_, version_ +field_, organization_, revision_, status_, version_ Decorative Elements @@ -166,7 +166,7 @@ target_ Compound Body Elements ---------------------- -Compound body elements contain local substructure (component parts) +Compound body elements contain local substructure (body subelements) and further body elements. They do not directly contain text data. Category members: attention_, block_quote_, bullet_list_, caution_, @@ -175,21 +175,24 @@ field_list_, figure_, footnote_, hint_, important_, note_, option_list_, system_message_, table_, tip_, warning_ -Compound Body Subelements -````````````````````````` +Body Subelements +```````````````` -Compound body elements contain specific compound body subelements -(e.g. bullet_list_ contains list_item_). Subelements may themselves -be compound elements (containing further child elements, like field_) -or simple data elements (containing text data, like field_name_). -These subelements always occur within specific parent elements, never -at the body element level (just below sections, etc.). +Compound body elements contain specific subelements (e.g. bullet_list_ +contains list_item_). Subelements may themselves be compound elements +(containing further child elements, like field_) or simple data +elements (containing text data, like field_name_). These subelements +always occur within specific parent elements, never at the body +element level (beside paragraphs, etc.). -Category members: caption_, classifier_, colspec_, definition_, -definition_list_item_, description_, entry_, field_, field_argument_, -field_body_, field_name_, label_, legend_, list_item_, option_, -option_argument_, option_group_, option_list_item_, option_string_, -row_, tbody_, term_, tgroup_, thead_ +Category members (simple): caption_, classifier_, colspec_, +field_argument_, field_name_, label_, option_argument_, +option_string_, term_ + +Category members (compound): definition_, definition_list_item_, +description_, entry_, field_, field_body_, legend_, list_item_, +option_, option_group_, option_list_item_, row_, tbody_, tgroup_, +thead_ Inline Elements @@ -201,7 +204,7 @@ body elements. Most inline elements have a "mixed content model". Category members: citation_reference_, emphasis_, footnote_reference_, generated_, image_, interpreted_, literal_, problematic_, reference_, -strong_, substitution_reference_, target_, raw_. +strong_, substitution_reference_, target_, raw_ .. _HTML: http://www.w3.org/MarkUp/ @@ -217,11 +220,14 @@ strong_, substitution_reference_, target_, raw_. :depth: 1 Each element in the DTD (document type definition) is described in its -own section below. Each section contains the following subsections -and items: +own section below. Each section contains an introduction plus the +following subsections: + +* Details (of element relationships and semantics): -* The initial text contains a description of the semantics of the - element, plus: + - Category: One or more references to the element categories in + `Element Hierarchy`_ above. Some elements belong to more than one + category. - Parents: A list of elements which may contain the element. @@ -234,7 +240,9 @@ and items: - Processing: Lists formatting or rendering recommendations for the element. -* Content Model: from the `Docutils DTD`_. +* Content Model: + + The formal XML content model from the `Docutils DTD`_, followed by: - Attributes: Describes (or refers to descriptions of) the possible values and semantics of each attribute. @@ -242,29 +250,31 @@ and items: - Parameter Entities: Lists the parameter entities which include the element described. -* Example: Where possible, a reStructuredText example is shown along - with a fragment of the document tree resulting from parsing. +* Examples: reStructuredText examples are shown along with + fragments of the document trees resulting from parsing. _`Pseudo-XML` is used for the results of parsing and processing. Pseudo-XML is a representation of XML where nesting is indicated by indentation and end-tags are not shown. Some of the precision of - real XML is traded for easier readability. For example, the - following are equivalent. XML:: + real XML is given up in exchange for easier readability. For + example, the following are equivalent: - <document> - <section id="a-title" name="a title"> - <title>A Title - A paragraph. -
- + - Real XML:: - Pseudo-XML:: + +
+ A Title + A paragraph. +
+ + + - Pseudo-XML:: - -
- - A Title - <paragraph> - A paragraph. + <document> + <section id="a-title" name="a title"> + <title> + A Title + <paragraph> + A paragraph. -------------------- @@ -414,20 +424,24 @@ its writing. ``document`` ============ -Element category: `structural elements`_. - The ``document`` element is the root (topmost) element of the Docutils document tree. ``document`` is the direct or indirect ancestor of every other element in the tree. It encloses the entire document tree. It is the starting point for a document. + +Details +------- + +Category + `Structural Elements`_ + Parents The ``document`` element has no parents. Children - ``document`` elements may contain the following elements: title_, - subtitle_, docinfo_, decoration_, topic_, transition_, section_, - and `body elements`_. + ``document`` elements may contain `structural subelements`_, + `structural elements`_, and `body elements`_. Analogies ``document`` is analogous to the HTML "html" element and several @@ -459,8 +473,8 @@ Attributes id_, name_, dupname_, source_, and class_. -Example -------- +Examples +-------- reStructuredText source:: @@ -761,12 +775,17 @@ document title:: ``subtitle`` ============ -Element category: `structural subelements`_. - The ``subtitle`` element stores the subtitle of a document_. + +Details +------- + +Category + `Structural Subelements`_ + Parents - The following elements may contain ``subtitle``: document_. + The following elements may contain ``subtitle``: document_ Children ``subtitle`` elements may contain text data plus `inline @@ -792,8 +811,8 @@ Attributes id_, name_, dupname_, source_, and class_. -Example -------- +Examples +-------- reStructuredText source:: @@ -873,14 +892,19 @@ attributes are stored in the ``subtitle`` element. ``title`` ========= -Element category: `structural subelements`_. - The ``title`` element stores the title of a document_, section_, or topic_. + +Details +------- + +Category + `Structural Subelements`_ + Parents The following elements may contain ``title``: document_, section_, - topic_. + topic_ Children ``title`` elements may contain text data plus `inline elements`_. @@ -907,8 +931,8 @@ Attributes has been numbered automatically. -Example -------- +Examples +-------- reStructuredText source:: -- cgit v1.2.1 From 9a6d962501d8b2aeb79e847555061b849d5ea34c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 21 Aug 2002 02:48:06 +0000 Subject: tweaks & good progress git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@570 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 1051 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 1011 insertions(+), 40 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 622243ec5..26a65c9cb 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -9,6 +9,7 @@ A Guide to the Docutils DTD :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. .. contents:: :depth: 1 @@ -39,14 +40,12 @@ ReStructuredText Primer`_. For complete technical details, see the .. _Docutils: http://docutils.sourceforge.net/ .. _Docutils Generic DTD: .. _Docutils DTD: -.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd +.. _docutils.dtd: docutils.dtd .. _Introducing the Extensible Markup Language (XML): http://xml.coverpages.org/xmlIntro.html .. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _A ReStructuredText Primer: - http://docutils.sourceforge.net/docs/rst/quickstart.html -.. _reStructuredText Markup Specification: - http://docutils.sourceforge.net/spec/rst/reStructuredText.html +.. _A ReStructuredText Primer: ../docs/rst/quickstart.html +.. _reStructuredText Markup Specification: rst/reStructuredText.html ------------------- @@ -123,8 +122,8 @@ Bibliographic Elements The docinfo_ element is an optional child of document_. It groups bibliographic elements together. -Category members: author_, authors_, contact_, copyright_, date_, -field_, organization_, revision_, status_, version_ +Category members: address_, author_, authors_, contact_, copyright_, +date_, field_, organization_, revision_, status_, version_ Decorative Elements @@ -247,8 +246,8 @@ following subsections: - Attributes: Describes (or refers to descriptions of) the possible values and semantics of each attribute. - - Parameter Entities: Lists the parameter entities which include the - element described. + - Parameter Entities: Lists the parameter entities which directly or + indirectly include the element. * Examples: reStructuredText examples are shown along with fragments of the document trees resulting from parsing. @@ -283,6 +282,80 @@ completed`". Please help complete this document by contributing to its writing. +``address`` +=========== + +The ``address`` element holds the surface mailing address information +for the author (individual or group) of the document, or a third-party +contact address. Its structure is identical to that of the +line_block_ element: whitespace is significant, especially newlines. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + The following elements may contain ``address``: docinfo_, authors_ + +Children + ``address`` elements contain text data plus `inline elements`_. + +Analogies + ``address`` is analogous to the DocBook "address" element. + +Processing + As with the line_block_ element, newlines and other whitespace is + significant and must be preserved. However, a monospaced typeface + need not be used. + + See also docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``address`` element contains the `common attributes`_ (id_, + name_, dupname_, source_, and class_), plus `xml:space`_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``address``. + + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Address: 123 Example Ave. + Example, EX + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <address> + 123 Example Ave. + Example, EX + +See docinfo_ for a more complete example, including processing +context. + + ``attention`` ============= @@ -292,13 +365,139 @@ its writing. ``author`` ========== -`To be completed`_. +The ``author`` element holds the name of the author of the document. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + The following elements may contain ``author``: docinfo_, authors_ + +Children + ``author`` elements may contain text data plus `inline elements`_. + +Analogies + ``author`` is analogous to the DocBook "author" element. + +Processing + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``author`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``author``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Author: J. Random Hacker + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <author> + J. Random Hacker + +See docinfo_ for a more complete example, including processing +context. ``authors`` =========== -`To be completed`_. +The ``authors`` element is a container for author information for +documents with multiple authors. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``authors``. + +Children + ``authors`` elements may contain the following elements: author_, + organization_, address_, contact_ + +Analogies + ``authors`` is analogous to the DocBook "authors" element. + +Processing + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + ((author_, organization_?, address_?, contact_?)+) + +Attributes + The ``authors`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``authors``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Authors: J. Random Hacker; Jane Doe + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <authors> + <author> + J. Random Hacker + <author> + Jane Doe + +In reStructuredText, multiple author's names are separated with +semicolons (";") or commas (","); semicolons take precedence. There +is currently no way to represent the author's organization, address, +or contact in a reStructuredText "Authors" field. + +See docinfo_ for a more complete example, including processing +context. ``block_quote`` @@ -358,13 +557,135 @@ its writing. ``contact`` =========== -`To be completed`_. +The ``contact`` element holds contact information for the author +(individual or group) of the document, or a third-party contact. It +is typically used for an email or web address. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + The following elements may contain ``contact``: docinfo_, authors_ + +Children + ``contact`` elements may contain text data plus `inline + elements`_. + +Analogies + ``contact`` is analogous to the DocBook "email" element. The HTML + "address" element serves a similar purpose. + +Processing + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``contact`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``contact``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Contact: jrh@example.com + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <contact> + <reference refuri="mailto:jrh@example.com"> + jrh@example.com + +See docinfo_ for a more complete example, including processing +context. ``copyright`` ============= -`To be completed`_. +The ``copyright`` element contains the document's copyright statement. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``copyright``. + +Children + ``copyright`` elements may contain text data plus `inline + elements`_. + +Analogies + ``copyright`` is analogous to the DocBook "copyright" element. + +Processing + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``copyright`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``copyright``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Copyright: This document has been placed in the public domain. + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <copyright> + This document has been placed in the public domain. + +See docinfo_ for a more complete example, including processing +context. ``danger`` @@ -376,13 +697,131 @@ its writing. ``date`` ======== -`To be completed`_. +The ``date`` element contains the date of publication, release, or +last modification of the document. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``date``. + +Children + ``date`` elements may contain text data plus `inline elements`_. + +Analogies + ``date`` is analogous to the DocBook "date" element. + +Processing + Often used with the RCS/CVS keyword "Date". See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``date`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``date``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Date: 2002-08-20 + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <date> + 2002-08-20 + +See docinfo_ for a more complete example, including processing +context. ``decoration`` ============== -`To be completed`_. +The ``decoration`` element is a container for header_ and footer_ +elements and potential future extensions. These elements are used for +page navigation, notes, time/datestamp, etc. Currently only the +footer_ element is implemented, populated with processing information +(datestamp, a link to Docutils_, etc.). + + +Details +------- + +Category + `Structural Subelements`_ + +Parents + Only the document_ element contains ``decoration``. + +Children + ``decoration`` elements may contain `decorative elements`_. + +Analogies + There are no direct analogies to ``decoration`` in HTML or DocBook. + Equivalents are typically constructed from primitives and/or + generated by the processing system. + +Processing + See the individual `decorative elements`_. + +Content Model +------------- + +.. parsed-literal:: + + (header_?, footer_?) + +Although the content model doesn't specifically require contents, no +empty ``decoration`` elements are ever created. + +Attributes + The ``decoration`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +reStructuredText source:: + + A paragraph. + +Complete pseudo-XML_ result after parsing and applying transforms, +assuming that the datestamp command-line option or configuration +setting has been supplied:: + + <document> + <decoration> + <footer> + <paragraph> + Generated on: 2002-08-20. + <paragraph> + A paragraph. ``definition`` @@ -412,7 +851,106 @@ its writing. ``docinfo`` =========== -`To be completed`_. +The ``docinfo`` element is a container for document bibliographic +data, or meta-data (data about the document). It corresponds to the +front matter of a book, such as the title page and copyright page. + + +Details +------- + +Category + `Structural Subelements`_ + +Parents + Only the document_ element contains ``docinfo``. + +Children + ``docinfo`` elements contain `bibliographic elements`_. + +Analogies + ``docinfo`` is analogous to DocBook "info" elements ("bookinfo" + etc.). There are no directly analogous HTML elements; the "meta" + element carries some of the same information, albeit invisibly. + +Processing + The ``docinfo`` element may be rendered as a two-column table or + in other styles. It may even be invisible or omitted from the + processed output. Meta-data may be extracted from ``docinfo`` + children; for example, HTML ``<meta>`` tags may be constructed. + + When Docutils_ transforms a reStructuredText_ field_list_ into a + ``docinfo`` element (see the examples below), RCS/CVS keywords are + normally stripped from simple (one paragraph) field bodies. For + complete details, please see `RCS Keywords`_ in the + `reStructuredText Markup Specification`_. + + .. _RCS Keywords: rst/reStructuredText.html#rcs-keywords + + +Content Model +------------- + +.. parsed-literal:: + + (`%bibliographic.elements;`_)+ + +Attributes + The ``docinfo`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +Docinfo is represented in reStructuredText by a field_list_ in a +bibliographic context: the first non-comment element of a document_, +after any document title_/subtitle_. The field list is transformed +into a ``docinfo`` element and its children by a transform. Source:: + + Docinfo Example + =============== + + :Author: J. Random Hacker + :Contact: jrh@example.com + :Date: 2002-08-18 + :Status: Work In Progress + :Version: 1 + :Filename: $RCSfile$ + :Copyright: This document has been placed in the public domain. + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="docinfo-example" name="docinfo example"> + <title> + Docinfo Example + <docinfo> + <author> + J. Random Hacker + <contact> + <reference refuri="mailto:jrh@example.com"> + jrh@example.com + <date> + 2002-08-18 + <status> + Work In Progress + <version> + 1 + <field> + <field_name> + Filename + <field_body> + <paragraph> + doctree.txt + <copyright> + This document has been placed in the public domain. + +Note that "Filename" is a non-standard ``docinfo`` field, so becomes a +generic ``field`` element. Also note that the "RCSfile" keyword +syntax has been stripped from the "Filename" data. + +See field_list_ for an example in a non-bibliographic context. Also +see the individual examples for the various `bibliographic elements`_. ``doctest_block`` @@ -444,8 +982,8 @@ Children `structural elements`_, and `body elements`_. Analogies - ``document`` is analogous to the HTML "html" element and several - DocBook elements such as "book". + ``document`` is analogous to the HTML "html" element and to + several DocBook elements such as "book". Content Model @@ -468,6 +1006,9 @@ become the document subtitle_. The "docinfo_" may be transformed from an initial field_list_, and "decoration_" is usually constructed programmatically. +See the `%structure.model;`_ parameter entity for details of the body +of a ``document``. + Attributes The ``document`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -553,19 +1094,72 @@ document title:: ``field_name`` ============== -`To be completed`_. +`To be completed`_. + + +``figure`` +========== + +`To be completed`_. + + +``footer`` +========== + +The ``footer`` element is a container element whose contents are meant +to appear at the bottom of a web page, or repeated at the bottom of +every printed page. Currently the ``footer`` element may contain +processing information (datestamp, a link to Docutils_, etc.). + + +Details +------- + +Category + `Decorative Elements`_ + +Parents + Only the decoration_ element contains ``footer``. + +Children + ``footer`` elements may contain `body elements`_. + +Analogies + There are no direct analogies to ``footer`` in HTML or DocBook. + Equivalents are typically constructed from primitives and/or + generated by the processing system. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +Attributes + The ``footer`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. -``figure`` -========== +Examples +-------- -`To be completed`_. +reStructuredText source:: + A paragraph. -``footer`` -========== +Complete pseudo-XML_ result after parsing and applying transforms, +assuming that the datestamp command-line option or configuration +setting has been supplied:: -`To be completed`_. + <document> + <decoration> + <footer> + <paragraph> + Generated on: 2002-08-20. + <paragraph> + A paragraph. ``footnote`` @@ -589,7 +1183,45 @@ document title:: ``header`` ========== -`To be completed`_. +The ``header`` element is a container element whose contents are meant +to appear at the top of a web page, or at the top of every printed +page. Docutils does not yet make use of the ``header`` element. + + +Details +------- + +Category + `Decorative Elements`_ + +Parents + Only the decoration_ element contains ``header``. + +Children + ``header`` elements may contain `body elements`_. + +Analogies + There are no direct analogies to ``header`` in HTML or DocBook. + Equivalents are typically constructed from primitives and/or + generated by the processing system. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +Attributes + The ``header`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +None. ``hint`` @@ -697,7 +1329,68 @@ document title:: ``organization`` ================ -`To be completed`_. +The ``organization`` element contains the name of document author's +organization, or the organization responsible for the document. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``organization``. + +Children + ``organization`` elements may contain text data plus `inline + elements`_. + +Analogies + ``organization`` is analogous to the DocBook "orgname", + "corpname", or "publishername" elements. + +Processing + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``organization`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``organization``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Organization: Humankind + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <organization> + Humankind + +See docinfo_ for a more complete example, including processing +context. ``paragraph`` @@ -733,7 +1426,72 @@ document title:: ``revision`` ============ -`To be completed`_. +The ``revision`` element contains the revision number of the document. +It can be used alone or in conjunction with version_. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``revision``. + +Children + ``revision`` elements may contain text data plus `inline + elements`_. + +Analogies + ``revision`` is analogous to but simpler than the DocBook + "revision" element. It closely matches the DocBook "revnumber" + element, but in a simpler context. + +Processing + Often used with the RCS/CVS keyword "Revision". See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``revision`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``revision``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Version: 1 + :Revision: b + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <version> + 1 + <revision> + b + +See docinfo_ for a more complete example, including processing +context. ``row`` @@ -745,13 +1503,162 @@ document title:: ``section`` =========== -`To be completed`_. +The ``section`` element is the main unit of hierarchy for Docutils +documents. Docutils ``section`` elements are a recursive structure; a +``section`` may contain other ``section`` elements, without limit. +Paragraphs and other body elements may occur before a ``section``, but +not after it. + + +Details +------- + +Category + `Structural Elements`_ + +Parents + The following elements may contain ``section``: document_, + section_ + +Children + ``section`` elements begin with a title_, and may contain `body + elements`_, and transition_ and topic_ elements. + +Analogies + ``section`` is analogous to HTML "div" elements and to DocBook + recursive "section" elements. + + +Content Model +------------- + +.. parsed-literal:: + + (title_, + `%structure.model;`_) + +See the `%structure.model;`_ parameter entity for details of the body +of a ``section``. + +Attributes + The ``section`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%section.elements;`_ parameter entity directly includes + ``section``. The `%structure.model;`_ parameter entity indirectly + includes ``section``. + + +Examples +-------- + +reStructuredText source:: + + Title 1 + ======= + Paragraph 1. + + Title 2 + ------- + Paragraph 2. + + Title 3 + ======= + Paragraph 3. + + Title 4 + ------- + Paragraph 4. + +Complete pseudo-XML_ result after parsing:: + + <document> + <section id="title-1" name="title 1"> + <title> + Title 1 + <paragraph> + Paragraph 1. + <section id="title-2" name="title 2"> + <title> + Title 2 + <paragraph> + Paragraph 2. + <section id="title-3" name="title 3"> + <title> + Title 3 + <paragraph> + Paragraph 3. + <section id="title-4" name="title 4"> + <title> + Title 4 + <paragraph> + Paragraph 4. ``status`` ========== -`To be completed`_. +The ``status`` element contains a status statement for the document, +such as "Draft", "Final", "Work In Progress", etc. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``status``. + +Children + ``status`` elements may contain text data plus `inline elements`_. + +Analogies + ``status`` is analogous to the DocBook "status" element. + +Processing + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``status`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``status``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Status: Work In Progress + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <status> + Work In Progress + +See docinfo_ for a more complete example, including processing +context. ``strong`` @@ -785,7 +1692,7 @@ Category `Structural Subelements`_ Parents - The following elements may contain ``subtitle``: document_ + Only the document_ element contains ``subtitle``. Children ``subtitle`` elements may contain text data plus `inline @@ -793,7 +1700,7 @@ Children Analogies ``subtitle`` is analogous to HTML header elements ("h2" etc.) and - the DocBook "subtitle" element. + to the DocBook "subtitle" element. Processing A document's subtitle is usually rendered smaller than its title_. @@ -911,7 +1818,7 @@ Children Analogies ``title`` is analogous to HTML "title" and header ("h1" etc.) - elements, and DocBook "title" elements. + elements, and to the DocBook "title" element. Content Model @@ -965,7 +1872,69 @@ Pseudo-XML_ fragment from simple parsing:: ``version`` =========== -`To be completed`_. +The ``version`` element contains the version number of the document. +It can be used alone or in conjunction with revision_. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``version``. + +Children + ``version`` elements may contain text data plus `inline + elements`_. + +Analogies + ``version`` may be considered analogous to the DocBook "revision", + "revnumber", or "biblioid" elements. + +Processing + Sometimes used with the RCS/CVS keyword "Revision". See docinfo_ + and revision_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``version`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``version``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Version: 1.1 + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <version> + 1.1 + +See docinfo_ for a more complete example, including processing +context. ``warning`` @@ -1242,7 +2211,7 @@ Entity definition: .. parsed-literal:: - author_ | authors_ | organization_ | contact_ + author_ | authors_ | organization_ | contact_ | address_ | version_ | revision_ | status_ | date_ | copyright_ | field_ %additional.bibliographic.elements; @@ -1255,7 +2224,8 @@ wrapper DTDs to extend ``%bibliographic.elements;``. =================== The ``%body.elements;`` parameter entity contains an OR-list of all -`body elements`_. +`body elements`_. ``%body.elements;`` is itself contained within the +`%structure.model;`_ parameter entity. Entity definition: @@ -1373,8 +2343,9 @@ Entity definition: ``%section.elements;`` ====================== -The ``%section.elements;`` parameter entity contains an OR-list of -all section_-equivalent elements. +The ``%section.elements;`` parameter entity contains an OR-list of all +section_-equivalent elements. ``%section.elements;`` is itself +contained within the `%structure.model;`_ parameter entity. Entity definition: @@ -1391,8 +2362,8 @@ by wrapper DTDs to extend ``%section.elements;``. ===================== The ``%structure.model;`` parameter entity is used by document_ and -section_ elements. It encapsulates the section structure of a -document and of parts of that document. See the discussion of the +section_ elements. It encapsulates the hierarchical structure of a +document and of its constituent parts. See the discussion of the `element hierarchy`_ above. Entity definition: -- cgit v1.2.1 From 084f211ed73cd637e15f6af04e9de105edda5170 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 21 Aug 2002 02:49:16 +0000 Subject: Added "address" element. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@571 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 0e328bb34..8947d9367 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -103,7 +103,7 @@ resolve to either an internal or external reference. <!ENTITY % additional.bibliographic.elements ""> <!ENTITY % bibliographic.elements - " author | authors | organization | contact + " author | authors | organization | address | contact | version | revision | status | date | copyright | field %additional.bibliographic.elements; "> @@ -210,12 +210,17 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT author %text.model;> <!ATTLIST author %basic.atts;> -<!ELEMENT authors ((author, organization?, contact?)+)> +<!ELEMENT authors ((author, organization?, address?, contact?)+)> <!ATTLIST authors %basic.atts;> <!ELEMENT organization %text.model;> <!ATTLIST organization %basic.atts;> +<!ELEMENT address %text.model;> +<!ATTLIST address + %basic.atts; + %fixedspace.att;> + <!ELEMENT contact %text.model;> <!ATTLIST contact %basic.atts;> -- cgit v1.2.1 From 13ed20d392cc6c5e727344dad0c3aca8cea125f1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 21 Aug 2002 03:00:07 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@572 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 040393276..f96e86fe6 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -837,10 +837,10 @@ DTD elements: docinfo, author, authors, organization, contact, version, status, date, copyright, field, topic. When a field list is the first non-comment element in a document -(after the document title, if there is one), it may have certain -specific fields transformed to document bibliographic data. This -bibliographic data corresponds to the front matter of a book, such as -the title page and copyright page. +(after the document title, if there is one), it may have its fields +transformed to document bibliographic data. This bibliographic data +corresponds to the front matter of a book, such as the title page and +copyright page. Certain registered field names (listed below) are recognized and transformed to the corresponding DTD elements, most becoming child @@ -859,6 +859,7 @@ elements are as follows: - "Authors": authors. - "Organization": organization. - "Contact": contact. +- "Address": address. - "Version": version. - "Status": status. - "Date": date. @@ -876,6 +877,10 @@ single name is interpreted as an "Author". If a single name contains a comma, end it with a semicolon to disambiguate: ":Authors: Doe, Jane;". +The "Address" field is for a multi-line surface mailing address. A +specialized form of line block`_ (see `reStructuredText Directives`_), +newlines and whitespace will be preserved. + The "Dedication" and "Abstract" fields may contain arbitrary body elements. Only one of each is allowed. They become topic elements with "Dedication" or "Abstract" titles (or language equivalents) -- cgit v1.2.1 From 25f06d048879c8730dfddb4af70d665cf6b3b339 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Aug 2002 01:54:33 +0000 Subject: Added cross-references to/from parameter entities. Added "topic", "transition", & "paragraph". 21 down, 63 to go. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@577 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 304 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 282 insertions(+), 22 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 26a65c9cb..d9c54275b 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1396,7 +1396,58 @@ context. ``paragraph`` ============= -`To be completed`_. +The ``paragraph`` element contains the text and inline elements of a +single paragraph, a fundamental building block of documents. + + +Details +------- + +Category + `Body Elements`_ + +Parents + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``paragraph``. + +Children + ``paragraph`` elements may contain text data plus `inline + elements`_. + +Analogies + ``paragraph`` is analogous to the HTML "p" element and the DocBook + "para" elements. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``paragraph`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%body.elements;`_ parameter entity directly includes + ``paragraph``. The `%structure.model;`_ parameter entity + indirectly includes ``paragraph``. + + +Examples +-------- + +reStructuredText source:: + + A paragraph. + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + A paragraph. ``pending`` @@ -1522,11 +1573,11 @@ Parents Children ``section`` elements begin with a title_, and may contain `body - elements`_, and transition_ and topic_ elements. + elements`_ and transition_ and topic_ elements. Analogies - ``section`` is analogous to HTML "div" elements and to DocBook - recursive "section" elements. + ``section`` is analogous to DocBook recursive "section" elements, + and to HTML "div" elements combined with "h1" etc. title elements. Content Model @@ -1860,13 +1911,146 @@ Pseudo-XML_ fragment from simple parsing:: ``topic`` ========= -`To be completed`_. +The ``topic`` element is a nonrecursive section_-like construct which +may occur at the top level of a section_ wherever a body element +(list, table, etc.) is allowed. In other words, ``topic`` elements +cannot nest inside body elements, so you can't have a ``topic`` inside +a ``table`` or a ``list``, or inside another ``topic``. + + +Details +------- + +Category + `Structural Elements`_ + +Parents + The following elements may contain ``topic``: document_, section_ + +Children + ``topic`` elements begin with a title_ and may contain `body + elements`_. + +Analogies + ``topic`` is analogous to the DocBook "simplesect" element. + +Processing + A ``topic`` element should be set off from the rest of the + document somehow, such as with indentation or a border. + + +Content Model +------------- + +.. parsed-literal:: + + (title_?, + (`%body.elements;`_)+) + +Attributes + The ``topic`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%structure.model;`_ parameter entity directly includes + ``topic``. + + +Examples +-------- + +The `"topic" directive`_ is used to create a ``topic`` element. +reStructuredText source:: + + .. topic:: Title + + Body. + +Pseudo-XML_ fragment from simple parsing:: + + <topic> + <title> + Title + <paragraph> + Body. + +.. _"topic" directive: rst/directives.html#topic ``transition`` ============== -`To be completed`_. +The ``transition`` element is commonly seen in novels and short +fiction, as a gap spanning one or more lines, with or without a type +ornament such as a row of asterisks. Transitions separate other body +elements, dividing a section into untitled divisions. A transition +may not begin or end a section or document, nor may two transitions be +immediately adjacent. + +See `Representation of Horizontal Rules`_ below. + + +Details +------- + +Category + `Structural Subelements`_ + +Parents + The following elements may contain ``transition``: document_, + section_ + +Children + ``transition`` is an empty element and has no children. + +Analogies + ``transition`` is analogous to the HTML "hr" element. + +Processing + The ``transition`` element is typically rendered as vertical + whitespace (more than that separating paragraphs), with or without + a horizontal line or row of asterisks. In novels, transitions are + often represented as a row of three well-spaced asterisks with + vertical space above and below. + + +Content Model +------------- + +:: + + EMPTY + +The ``transition`` element has no content; it is a "point element". + +Attributes + The ``transition`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%structure.model;`_ parameter entity directly includes + ``transition``. + + +Examples +-------- + +reStructuredText source:: + + Paragraph 1. + + -------- + + Paragraph 2. + +Complete pseudo-XML_ result after parsing:: + + <document> + <paragraph> + Paragraph 1. + <transition> + <paragraph> + Paragraph 2. ``version`` @@ -1997,7 +2181,8 @@ Attribute types: `Attribute type`_: ``%yesorno;``. Default value: none (implies no). The ``anonymous`` attribute is used for unnamed hyperlinks in the -target_ and reference_ elements. +target_ and reference_ elements (via the `%anonymous.att;`_ parameter +entity). ``auto`` @@ -2005,8 +2190,9 @@ target_ and reference_ elements. `Attribute type`_: ``CDATA``. Default value: none. -The ``auto`` attribute is used to indicate an automatically-numbered -footnote_, footnote_reference_ or title_. +The ``auto`` attribute is used to indicate automatically-numbered +footnote_, footnote_reference_ and title_ elements (via the +`%auto.att;`_ parameter entity). ``backrefs`` @@ -2016,7 +2202,7 @@ footnote_, footnote_reference_ or title_. The ``backrefs`` attribute contains a space-separated list of id_ references, used for backlinks from footnote_, citation_, and -system_message_ elements. +system_message_ elements (via the `%backrefs.att;`_ parameter entity). ``class`` @@ -2075,7 +2261,8 @@ one of the `common attributes`_, shared by all Docutils elements. The ``refid`` attribute contains references to `id`_ attributes in other elements. It is used by the target_, reference_, footnote_reference_, citation_reference_, title_ and problematic_ -elements. +elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter +entities). ``refname`` @@ -2088,7 +2275,8 @@ The ``refname`` attribute contains an internal reference to the ``refname`` indicates an indirect target which may resolve to either an internal or external reference. ``refname`` is used by the target_, reference_, footnote_reference_, citation_reference_, and -substitution_reference_ elements. +substitution_reference_ elements (via the `%refname.att;`_ and +`%reference.atts;`_ parameter entities). ``refuri`` @@ -2098,7 +2286,8 @@ substitution_reference_ elements. The ``refuri`` attribute contains an external reference to a URI/URL. It is used by the target_, reference_, footnote_reference_, and -citation_reference_ elements. +citation_reference_ elements (via the `%reference.atts;`_ parameter +entity). ``source`` @@ -2119,10 +2308,11 @@ the `common attributes`_, shared by all Docutils elements. The ``xml:space`` attribute is a standard XML attribute for whitespace-preserving elements. It is used by the literal_block_, -line_block_, doctest_block_, comment_, and raw_ elements. It is a -fixed attribute, meant to communicate to an XML parser that the -element contains significant whitespace. The attribute value should -not be set in a document instance. +line_block_, doctest_block_, comment_, and raw_ elements (via the +`%fixedspace.att;`_ parameter entity). It is a fixed attribute, meant +to communicate to an XML parser that the element contains significant +whitespace. The attribute value should not be set in a document +instance. -------------------- @@ -2153,6 +2343,9 @@ Entity definition: anonymous_ %yesorno; #IMPLIED +The reference_ and target_ elements directly employ the +``%anonymous.att;`` parameter entity in their attribute lists. + ``%auto.att;`` ============== @@ -2166,6 +2359,9 @@ Entity definition: auto_ CDATA #IMPLIED +The footnote_, footnote_reference_, and title_ elements directly +employ the ``%auto.att;`` parameter entity in their attribute lists. + ``%backrefs.att;`` ================== @@ -2179,12 +2375,15 @@ Entity definition: backrefs_ IDREFS #IMPLIED +The citation_, footnote_, and system_message_ elements directly employ +the ``%backrefs.att;`` parameter entity in their attribute lists. + ``%basic.atts;`` ================ The ``%basic.atts;`` parameter entity lists attributes common to all -elements. See `Common Attributes`_. +Docutils elements. See `Common Attributes`_. Entity definition: @@ -2219,6 +2418,9 @@ Entity definition: The ``%additional.bibliographic.elements;`` parameter entity can be used by wrapper DTDs to extend ``%bibliographic.elements;``. +Only the docinfo_ element directly employs the +``%bibliographic.elements;`` parameter entity in its content model. + ``%body.elements;`` =================== @@ -2244,6 +2446,16 @@ Entity definition: The ``%additional.body.elements;`` parameter entity can be used by wrapper DTDs to extend ``%body.elements;``. +The ``%body.elements;`` parameter entity is directly employed in the +content models of the following elements: attention_, block_quote_, +caution_, citation_, danger_, definition_, description_, entry_, +error_, field_body_, footer_, footnote_, header_, hint_, important_, +legend_, list_item_, note_, system_message_, tip_, topic_, warning_ + +Via `%structure.model;`_, the ``%body.elements;`` parameter entity is +indirectly employed in the content models of the document_ and +section_ elements. + ``%fixedspace.att;`` ==================== @@ -2258,6 +2470,10 @@ Entity definition: `xml:space`_ (default | preserve) #FIXED 'preserve' +The ``%fixedspace.att;`` parameter entity is directly employed in the +attribute lists of the following elements: address_, comment_, +doctest_block_, line_block_, literal_block_, raw_ + ``%inline.elements;`` ===================== @@ -2278,6 +2494,14 @@ Entity definition: The ``%additional.inline.elements;`` parameter entity can be used by wrapper DTDs to extend ``%inline.elements;``. +Via `%text.model;`_, the ``%inline.elements;`` parameter entity is +indirectly employed in the content models of the following elements: +address_, author_, caption_, classifier_, contact_, copyright_, date_, +doctest_block_, emphasis_, generated_, interpreted_, line_block_, +literal_block_, organization_, paragraph_, problematic_, raw_, +reference_, revision_, status_, strong_, substitution_definition_, +substitution_reference_, subtitle_, target_, term_, title_, version_ + ``%reference.atts;`` ==================== @@ -2297,6 +2521,10 @@ Entity definition: The ``%additional.reference.atts;`` parameter entity can be used by wrapper DTDs to extend ``%additional.reference.atts;``. +The citation_reference_, footnote_reference_, reference_, and target_ +elements directly employ the ``%reference.att;`` parameter entity in +their attribute lists. + ``%refid.att;`` ================ @@ -2310,6 +2538,13 @@ Entity definition: refid_ CDATA #IMPLIED +The title_ and problematic_ elements directly employ the +``%refid.att;`` parameter entity in their attribute lists. + +Via `%reference.atts;`_, the ``%refid.att;`` parameter entity is +indirectly employed in the attribute lists of the citation_reference_, +footnote_reference_, reference_, and target_ elements. + ``%refname.att;`` ================= @@ -2326,6 +2561,13 @@ Entity definition: refname_ NMTOKENS #IMPLIED +The substitution_reference_ element directly employs the +``%refname.att;`` parameter entity in its attribute list. + +Via `%reference.atts;`_, the ``%refname.att;`` parameter entity is +indirectly employed in the attribute lists of the citation_reference_, +footnote_reference_, reference_, and target_ elements. + ``%refuri.att;`` ================ @@ -2339,6 +2581,10 @@ Entity definition: refuri_ CDATA #IMPLIED +Via `%reference.atts;`_, the ``%refuri.att;`` parameter entity is +indirectly employed in the attribute lists of the citation_reference_, +footnote_reference_, reference_, and target_ elements. + ``%section.elements;`` ====================== @@ -2357,14 +2603,17 @@ Entity definition: The ``%additional.section.elements;`` parameter entity can be used by wrapper DTDs to extend ``%section.elements;``. +Via `%structure.model;`_, the ``%section.elements;`` parameter entity +is indirectly employed in the content models of the document_ and +section_ elements. + ``%structure.model;`` ===================== -The ``%structure.model;`` parameter entity is used by document_ and -section_ elements. It encapsulates the hierarchical structure of a -document and of its constituent parts. See the discussion of the -`element hierarchy`_ above. +The ``%structure.model;`` parameter entity encapsulates the +hierarchical structure of a document and of its constituent parts. +See the discussion of the `element hierarchy`_ above. Entity definition: @@ -2385,6 +2634,9 @@ Each document_ or section_ contains either: - one or more sections (whose contents are recursively the same as this model). +The `%structure.model;`_ parameter entity is directly employed in the +content models of the document_ and section_ elements. + ``%text.model;`` ================ @@ -2398,6 +2650,14 @@ Entity definition: (#PCDATA | `%inline.elements;`_)* +The ``%text.model;`` parameter entity is directly employed in the +content models of the following elements: address_, author_, caption_, +classifier_, contact_, copyright_, date_, doctest_block_, emphasis_, +generated_, interpreted_, line_block_, literal_block_, organization_, +paragraph_, problematic_, raw_, reference_, revision_, status_, +strong_, substitution_definition_, substitution_reference_, subtitle_, +target_, term_, title_, version_ + ---------------------- Miscellaneous Topics -- cgit v1.2.1 From 91678c6fc588e7f3e7e4e59aa44197678202c135 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Aug 2002 01:55:40 +0000 Subject: cleanup git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@578 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 8947d9367..244d4c9d0 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -417,13 +417,13 @@ either the string separating it from the `option` (typically either <!ATTLIST label %basic.atts;> <!-- Empty except when used as an inline element. --> -<!ELEMENT target (%text.model;)> +<!ELEMENT target %text.model;> <!ATTLIST target %basic.atts; %reference.atts; %anonymous.att;> -<!ELEMENT substitution_definition (%text.model;)> +<!ELEMENT substitution_definition %text.model;> <!ATTLIST substitution_definition %basic.atts;> <!ELEMENT comment (#PCDATA)> @@ -490,13 +490,13 @@ following caveats: <literal>, and <image> do not support nesting. --> -<!ELEMENT emphasis (%text.model;)> +<!ELEMENT emphasis %text.model;> <!ATTLIST emphasis %basic.atts;> -<!ELEMENT strong (%text.model;)> +<!ELEMENT strong %text.model;> <!ATTLIST strong %basic.atts;> -<!ELEMENT interpreted (%text.model;)> +<!ELEMENT interpreted %text.model;> <!ATTLIST interpreted %basic.atts; role NMTOKEN #IMPLIED @@ -505,7 +505,7 @@ following caveats: <!ELEMENT literal (#PCDATA)> <!ATTLIST literal %basic.atts;> -<!ELEMENT reference (%text.model;)> +<!ELEMENT reference %text.model;> <!ATTLIST reference %basic.atts; %reference.atts; @@ -522,17 +522,17 @@ following caveats: %basic.atts; %reference.atts;> -<!ELEMENT substitution_reference (%text.model;)> +<!ELEMENT substitution_reference %text.model;> <!ATTLIST substitution_reference %basic.atts; %refname.att;> -<!ELEMENT problematic (%text.model;)> +<!ELEMENT problematic %text.model;> <!ATTLIST problematic %basic.atts; %refid.att;> -<!ELEMENT generated (%text.model;)> +<!ELEMENT generated %text.model;> <!ATTLIST generated %basic.atts;> <!-- -- cgit v1.2.1 From 19bca75de1d1e09b962424cbeb061e8d455e0e54 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 Aug 2002 01:25:06 +0000 Subject: Added descriptions of bullet_list, enumerated_list, definition_list, and subelements. 29 down, 55 to go. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@591 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 631 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 608 insertions(+), 23 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index d9c54275b..68f914875 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -328,7 +328,7 @@ Attributes Parameter Entities The `%bibliographic.elements;`_ parameter entity directly includes ``address``. - + Examples @@ -509,7 +509,83 @@ context. ``bullet_list`` =============== -`To be completed`_. +The ``bullet_list`` element contains list_item_ elements which are +uniformly marked with bullets. Bullets are typically simple dingbats +(symbols) such as circles and squares. + + +Details +------- + +Category + `Compound Body Elements`_ + +Parents + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``bullet_list``. + +Children + ``bullet_list`` elements contain one or more list_item_ elements. + +Analogies + ``bullet_list`` is analogous to the HTML "ul" element and to the + DocBook "itemizedlist" element. HTML's "ul" is short for + "unordered list", which we consider to be a misnomer. "Unordered" + implies that the list items may be randomly rearranged without + affecting the meaning of the list. Bullet lists *are* often + ordered; the ordering is simply left implicit. + +Processing + Each list item should begin a new vertical block, prefaced by a + bullet/dingbat. + + +Content Model +------------- + +.. parsed-literal:: + + (list_item_+) + +Attributes + The ``bullet_list`` element contains the `common attributes`_ + (id_, name_, dupname_, source_, and class_), plus bullet_. + + ``bullet`` is used to record the style of bullet from the input + data. In reStructuredText, it contains one of "-", "+", or "*". + It may be ignored in processing. + +Parameter Entities + The `%body.elements;`_ parameter entity directly includes + ``bullet_list``. The `%structure.model;`_ parameter entity + indirectly includes ``bullet_list``. + + +Examples +-------- + +reStructuredText source:: + + - Item 1, paragraph 1. + + Item 1, paragraph 2. + + - Item 2. + +Pseudo-XML_ fragment from simple parsing:: + + <bullet_list bullet="-"> + <list_item> + <paragraph> + Item 1, paragraph 1. + <paragraph> + Item 1, paragraph 2. + <list_item> + <paragraph> + Item 2. + +See list_item_ for another example. ``caption`` @@ -539,7 +615,72 @@ context. ``classifier`` ============== -`To be completed`_. +The ``classifier`` element contains the classification or type of the +term_ being defined in a definition_list_. For example, it can be +used to indicate the type of a variable. + + +Details +------- + +Category + `Body Subelements`_ (simple) + +Parents + Only the definition_list_item_ element contains ``classifier``. + +Children + ``classifier`` elements may contain text data plus `inline elements`_. + +Analogies + ``classifier`` has no direct analogues in common DTDs. It can be + emulated with primitives or type effects. + +Processing + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``classifier`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +Here is a hypothetical data dictionary. reStructuredText source:: + + name : string + Customer name. + i : int + Temporary index variable. + +Pseudo-XML_ fragment from simple parsing:: + + <definition_list> + <definition_list_item> + <term> + name + <classifier> + string + <definition> + <paragraph> + Customer name. + <definition_list_item> + <term> + i + <classifier> + int + <definition> + <paragraph> + Temporary index variable. ``colspec`` @@ -782,9 +923,9 @@ Children ``decoration`` elements may contain `decorative elements`_. Analogies - There are no direct analogies to ``decoration`` in HTML or DocBook. - Equivalents are typically constructed from primitives and/or - generated by the processing system. + There are no direct analogies to ``decoration`` in HTML or in + DocBook. Equivalents are typically constructed from primitives + and/or generated by the processing system. Processing See the individual `decorative elements`_. @@ -827,19 +968,213 @@ setting has been supplied:: ``definition`` ============== -`To be completed`_. +The ``definition`` element is a container for the body elements used +to define a term_ in a definition_list_. + + +Details +------- + +Category + `Body Subelements`_ (compound) + +Parents + Only definition_list_item_ elements contain ``definition``. + +Children + ``definition`` elements may contain `body elements`_. + +Analogies + ``definition`` is analogous to the HTML "dd" element and to the + DocBook "listitem" element (inside a "variablelistentry" element). + +Processing + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +Attributes + The ``definition`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the definition_list_, definition_list_item_, and +classifier_ elements. ``definition_list`` =================== -`To be completed`_. +The ``definition_list`` element contains a list of terms and their +definitions. It can be used for glossaries or dictionaries, to +describe or classify things, for dialogues, or to itemize subtopics +(such as in this reference). + + +Details +------- + +Category + `Compound Body Elements`_ + +Parents + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``definition_list``. + +Children + ``definition_list`` elements contain one or more + definition_list_item_ elements. + +Analogies + ``definition_list`` is analogous to the HTML "dl" element and to + the DocBook "variablelist" element. + +Processing + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + (definition_list_item_+) + +Attributes + The ``definition_list`` element contains only the `common + attributes`_: id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%body.elements;`_ parameter entity directly includes + ``definition_list``. The `%structure.model;`_ parameter entity + indirectly includes ``definition_list``. + + +Examples +-------- + +reStructuredText source:: + + Term + Definition. + + Term : classifier + The ' : ' indicates a classifier in + definition list item terms only. + +Pseudo-XML_ fragment from simple parsing:: + + <definition_list> + <definition_list_item> + <term> + Term + <definition> + <paragraph> + Definition. + <definition_list_item> + <term> + Term + <classifier> + classifier + <definition> + <paragraph> + The ' : ' indicates a classifier in + definition list item terms only. + +See definition_list_item_ and classifier_ for further examples. ``definition_list_item`` ======================== -`To be completed`_. +The ``definition_list_item`` element contains a single +term_/definition_ pair (with optional classifier_). + + +Details +------- + +Category + `Body Subelements`_ (compound) + +Parents + Only the definition_list_ element contains + ``definition_list_item``. + +Children + ``definition_list_item`` elements each contain a single term_, + an optional classifier_, and a definition_. + +Analogies + ``definition_list_item`` is analogous to the DocBook + "variablelistentry" element. + +Processing + The optional classifier_ can be rendered differently from the + term_. They should be separated visually, typically by spaces + plus a colon or dash. + + +Content Model +------------- + +.. parsed-literal:: + + (term_, classifier_?, definition_) + +Attributes + The ``definition_list_item`` element contains only the `common + attributes`_: id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +reStructuredText source:: + + Tyrannosaurus Rex : carnivore + Big and scary; the "Tyrant King". + + Brontosaurus : herbivore + Small at one end, big in the middle, + and small again at the other end. + + -- Anne Elk, Miss + +Pseudo-XML_ fragment from simple parsing:: + + <definition_list> + <definition_list_item> + <term> + Tyrannosaurus Rex + <classifier> + carnivore + <definition> + <paragraph> + Big and scary; the "Tyrant King". + <definition_list_item> + <term> + Brontosaurus + <classifier> + herbivore + <definition> + <paragraph> + Small at one end, big in the middle, + and small again at the other end. + <paragraph> + -- Anne Elk, Miss + +See definition_list_ and classifier_ for further examples. ``description`` @@ -1058,7 +1393,107 @@ document title:: ``enumerated_list`` =================== -`To be completed`_. +The ``enumerated_list`` element contains list_item_ elements which are +uniformly marked with enumerator labels. + + +Details +------- + +Category + `Compound Body Elements`_ + +Parents + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``enumerated_list``. + +Children + ``enumerated_list`` elements contain one or more list_item_ + elements. + +Analogies + ``enumerated_list`` is analogous to the HTML "ol" element and to + the DocBook "orderedlist" element. + +Processing + Each list item should begin a new vertical block, prefaced by a + enumeration marker (such as "1."). + + +Content Model +------------- + +.. parsed-literal:: + + (list_item_+) + +Attributes + The ``enumerated_list`` element contains the `common attributes`_ + (id_, name_, dupname_, source_, and class_), plus enumtype_, + prefix_, suffix_, and start_. + + ``enumtype`` is used to record the intended enumeration sequence, + one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z), + "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ..., + mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ..., + MMMMCMXCIX [4999]). + + ``prefix`` stores the formatting characters used before the + enumerator. In documents originating from reStructuredText data, + it will contain either "" (empty string) or "(" (left + parenthesis). It may or may not affect processing. + + ``suffix`` stores the formatting characters used after the + enumerator. In documents originating from reStructuredText data, + it will contain either "." (period) or ")" (right parenthesis). + Depending on the capabilities of the output format, this attribute + may or may not affect processing. + + ``start`` contains the ordinal value of the first item in the + list, in decimal. For lists beginning at value 1 ("1", "a", "A", + "i", or "I"), this attribute may be omitted. + +Parameter Entities + The `%body.elements;`_ parameter entity directly includes + ``enumerated_list``. The `%structure.model;`_ parameter entity + indirectly includes ``enumerated_list``. + + +Examples +-------- + +reStructuredText source:: + + 1. Item 1. + + (A) Item A. + (B) Item B. + (C) Item C. + + 2. Item 2. + +Pseudo-XML_ fragment from simple parsing:: + + <enumerated_list enumtype="arabic" prefix="" suffix="."> + <list_item> + <paragraph> + Item 1. + <enumerated_list enumtype="upperalpha" prefix="(" suffix=")"> + <list_item> + <paragraph> + Item A. + <list_item> + <paragraph> + Item B. + <list_item> + <paragraph> + Item C. + <list_item> + <paragraph> + Item 2. + +See list_item_ for another example. ``error`` @@ -1269,7 +1704,73 @@ None. ``list_item`` ============= -`To be completed`_. +The ``list_item`` element is a container for the elements of a list +item. + + +Details +------- + +Category + `Body Subelements`_ (compound) + +Parents + The bullet_list_ and enumerated_list_ elements contain + ``list_item``. + +Children + ``list_item`` elements may contain `body elements`_. + +Analogies + ``list_item`` is analogous to the HTML "li" element and to the + DocBook "listitem" element. + +Processing + See bullet_list_ or enumerated_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +Attributes + The ``list_item`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +reStructuredText source:: + + 1. Outer list, item 1. + + * Inner list, item 1. + * Inner list, item 2. + + 2. Outer list, item 2. + +Pseudo-XML_ fragment from simple parsing:: + + <enumerated_list enumtype="arabic" prefix="" suffix="."> + <list_item> + <paragraph> + Outer list, item 1. + <bullet_list bullet="*"> + <list_item> + <paragraph> + Inner list, item 1. + <list_item> + <paragraph> + Inner list, item 2. + <list_item> + <paragraph> + Outer list, item 2. + +See bullet_list_ or enumerated_list_ for further examples. ``literal`` @@ -1404,7 +1905,7 @@ Details ------- Category - `Body Elements`_ + `Simple Body Elements`_ Parents All elements employing the `%body.elements;`_ or @@ -1416,8 +1917,8 @@ Children elements`_. Analogies - ``paragraph`` is analogous to the HTML "p" element and the DocBook - "para" elements. + ``paragraph`` is analogous to the HTML "p" element and to the + DocBook "para" elements. Content Model @@ -1609,15 +2110,15 @@ reStructuredText source:: Title 1 ======= Paragraph 1. - + Title 2 ------- Paragraph 2. - + Title 3 ======= Paragraph 3. - + Title 4 ------- Paragraph 4. @@ -1826,7 +2327,47 @@ attributes are stored in the ``subtitle`` element. ``term`` ======== -`To be completed`_. +The ``term`` element contains a word or phrase being defined in a +definition_list_. + + +Details +------- + +Category + `Body Subelements`_ (simple) + +Parents + Only the definition_list_item_ element contains ``term``. + +Children + ``term`` elements may contain text data plus `inline elements`_. + +Analogies + ``term`` is analogous to the HTML "dt" element and to the DocBook + "term" element. + +Processing + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``term`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the definition_list_, definition_list_item_, and +classifier_ elements. ``tgroup`` @@ -2038,9 +2579,9 @@ Examples reStructuredText source:: Paragraph 1. - + -------- - + Paragraph 2. Complete pseudo-XML_ result after parsing:: @@ -2174,6 +2715,9 @@ Attribute types: is a parameter entity which resolves to a ``NMTOKEN`` attribute type. +enumeration + The attribute value may be one of a specified list of values. + ``anonymous`` ============= @@ -2205,6 +2749,14 @@ references, used for backlinks from footnote_, citation_, and system_message_ elements (via the `%backrefs.att;`_ parameter entity). +``bullet`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``bullet`` attribute is used in the bullet_list_ element. + + ``class`` ========= @@ -2230,6 +2782,15 @@ not both. ``dupname`` is one of the `common attributes`_, shared by all Docutils elements. +``enumtype`` +============ + +`Attribute type`_: enumeration, one of "arabic", "loweralpha", +"upperalpha", "lowerroman", or "upperroman". Default value: none. + +The ``enumtype`` attribute is used in the enumerated_list_ element. + + ``id`` ====== @@ -2253,6 +2814,14 @@ of the ``name`` or ``dupname`` attributes, but not both. ``name`` is one of the `common attributes`_, shared by all Docutils elements. +``prefix`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``prefix`` attribute is used in the enumerated_list_ element. + + ``refid`` ========= @@ -2300,6 +2869,22 @@ source text that was used to produce the document tree. It is one of the `common attributes`_, shared by all Docutils elements. +``start`` +========= + +`Attribute type`_: ``%number;``. Default value: none. + +The ``start`` attribute is used in the enumerated_list_ element. + + +``suffix`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``suffix`` attribute is used in the enumerated_list_ element. + + ``xml:space`` ============= @@ -2315,9 +2900,9 @@ whitespace. The attribute value should not be set in a document instance. --------------------- - Parameter Entities --------------------- +---------------------------- + Parameter Entity Reference +---------------------------- .. contents:: :local: :depth: 1 -- cgit v1.2.1 From 244db0bd4cc8375e7347d9cffdfc3f881aae71e6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 Aug 2002 16:00:34 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@594 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 ++ docs/ref/rst/restructuredtext.txt | 9 +++++---- 2 files changed, 7 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 3e9d2da41..c44ca0fb7 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -474,12 +474,14 @@ 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} diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index f96e86fe6..9c6996e80 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1790,10 +1790,11 @@ used after the directive type for these reasons: a literal block, and a level-3 (error) system message generated. Thus "::" is a natural choice. -Any text on the first line after the directive indicator is directive -data. The interpretation of directive data is up to the directive -code. Directive data may be interpreted as arguments to the -directive, or simply as the first line of the directive's text block. +Any text on the first line of the directive, after the directive +indicator, is directive data. The interpretation of directive data is +up to the directive code. Directive data may be interpreted as +arguments to the directive, or simply as the first line of the +directive's text block. Actions taken in response to directives and the interpretation of text in the directive block or subsequent text block(s) are -- cgit v1.2.1 From 3f7e74c966e10eae283a349bcb80055fc8723da2 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 27 Aug 2002 00:39:56 +0000 Subject: Updated directive description. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@596 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 104 +++++++++++++++++++++++--------------- 1 file changed, 62 insertions(+), 42 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 9c6996e80..6cb80cf1f 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -773,11 +773,11 @@ DTD elements: field_list, field, field_name, field_argument, field_body. Field lists are most often used as part of an extension syntax, such -as attributes for directives_, or database-like records meant for -further processing. They are not intended to be an alternative to -definition lists. Applications of reStructuredText may recognize -field names and transform fields or field bodies in certain contexts. -See `Bibliographic Fields`_ below for one example, or the "image" +as options for directives_, or database-like records meant for further +processing. They are not intended to be an alternative to definition +lists. Applications of reStructuredText may recognize field names and +transform fields or field bodies in certain contexts. See +`Bibliographic Fields`_ below for one example, or the "image" directive in `reStructuredText Directives`_ for another. Field lists are mappings from field names to field bodies, modeled on @@ -1305,9 +1305,9 @@ column. In that case, that line of text is parsed as a continuation line. For this reason, cells in the first column of new rows (*not* continuation lines) *must* contain some text; blank cells would lead to a misinterpretation. An empty comment ("..") is sufficient and -will be omitted from the processed output. Also, this mechanism -limits cells in the first column to only one line of text. Use `grid -tables`_ if this limitation is unacceptable. +will be omitted from the processed output (see Comments_ below). +Also, this mechanism limits cells in the first column to only one line +of text. Use `grid tables`_ if this limitation is unacceptable. Underlines of '-' may also be used to visually separate rows, even if there are no column spans. This is especially useful in long tables, @@ -1775,10 +1775,11 @@ An admonition (note, caution, etc.) contains other body elements:: - Here is a bullet list. Directives are indicated by an explicit markup start (".. ") followed -by the directive type, two colons, and whitespace. Directive types -are case-insensitive single words (alphanumerics plus internal -hyphens, underscores, and periods; no whitespace). Two colons are -used after the directive type for these reasons: +by the directive type, two colons, and whitespace (together called the +"directive marker"). Directive types are case-insensitive single +words (alphanumerics plus internal hyphens, underscores, and periods; +no whitespace). Two colons are used after the directive type for +these reasons: - To avoid clashes with common comment text like:: @@ -1790,41 +1791,60 @@ used after the directive type for these reasons: a literal block, and a level-3 (error) system message generated. Thus "::" is a natural choice. -Any text on the first line of the directive, after the directive -indicator, is directive data. The interpretation of directive data is -up to the directive code. Directive data may be interpreted as -arguments to the directive, or simply as the first line of the -directive's text block. +The directive block is consists of any text on the first line of the +directive after the directive marker, and any subsequent indented +text. The interpretation of the directive block is up to the +directive code. There are three logical parts to the directive block: + +1. Directive arguments. +2. Directive options. +3. Directive content. + +Individual directives can employ any combination of these parts. +Directive arguments can be filesystem paths, URLs, title text, etc. +Directive options are indicated using `field lists`_; the field names +and contents are directive-specific. Argumens and options must form a +contiguous block beginning on the first or second line of the +directive; a blank line indicates the beginning of the directive +content block. If either arguments and/or options are employed by the +directive, a blank line must separate them from the directive content. +The "figure" directive employs all three parts:: + + .. figure:: larch.png + :scale: 50 + + The larch. + +Simple directives may not require any content. If a directive that +does not employ a content block is followed by indented text anyway, +it is an error. If a block quote should immediately follow a +directive, use an empty comment in-between (see Comments_ below). Actions taken in response to directives and the interpretation of text -in the directive block or subsequent text block(s) are -directive-dependent. Indented text following a directive may be -interpreted as a directive block. Simple directives may not require -any text beyond the directive data (if that), and will not process any -following indented text. - -Directives are meant for the arbitrary processing of their contents -(the directive data & text block), which can be transformed into -something possibly unrelated to the original text. It may also be -possible for directives to be used as pragmas, to modify the behavior -of the parser, such as to experiment with alternate syntax. There is -no parser support for this functionality at present; if a reasonable -need for pragma directives is found, they may be supported. - -Directives do not survive as "directive" elements past the parsing -stage; they are a *parser construct* only, and have no intrinsic -meaning outside of reStructuredText. Instead, the parser will -transform recognized directives into (possibly specialized) document -elements. Unknown directives will trigger level-3 (error) system -messages. +in the directive content block or subsequent text block(s) are +directive-dependent. See `reStructuredText Directives`_ for details. + +Directives are meant for the arbitrary processing of their contents, +which can be transformed into something possibly unrelated to the +original text. It may also be possible for directives to be used as +pragmas, to modify the behavior of the parser, such as to experiment +with alternate syntax. There is no parser support for this +functionality at present; if a reasonable need for pragma directives +is found, they may be supported. + +Directives do not generate "directive" elements; they are a *parser +construct* only, and have no intrinsic meaning outside of +reStructuredText. Instead, the parser will transform recognized +directives into (possibly specialized) document elements. Unknown +directives will trigger level-3 (error) system messages. Syntax diagram:: - +-------+--------------------------+ - | ".. " | directive type "::" data | - +-------+ directive block | - | | - +--------------------------+ + +-------+-------------------------------+ + | ".. " | directive type "::" directive | + +-------+ block | + | | + +-------------------------------+ Substitution Definitions -- cgit v1.2.1 From d109beb80e5e9429ee8ce649dd5d43e65e97e31e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 27 Aug 2002 00:40:56 +0000 Subject: Added directive: "include". Formalized descriptions of directive details. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@598 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 274 +++++++++++++++++++++++++++++++------------- 1 file changed, 194 insertions(+), 80 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index c44ca0fb7..5f38e9503 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -11,17 +11,22 @@ reStructuredText parser. Directives have the following syntax:: - +-------+--------------------------+ - | ".. " | directive type "::" data | - +-------+ directive block | - | | - +--------------------------+ + +-------+-------------------------------+ + | ".. " | directive type "::" directive | + +-------+ block | + | | + +-------------------------------+ Directives begin with an explicit markup start (two periods and a -space), followed by the directive type, two colons, optional directive -data (on the same line as the directive type) and an optional -directive block (on subsequent lines). The directive block is -indented, aligned with the left edge of the directive type. +space), followed by the directive type and two colons (collectively, +the "directive marker"). The directive block begins immediately after +the directive marker, and includes all subsequent indented lines. The +directive block is divided into arguments, options (a field list), and +content. See the Directives_ section in the `reStructuredText Markup +Specification`_ for syntax details. + +.. _Directives: ./reStructuredText.html#directives +.. _reStructuredText Markup Specification: ./reStructuredText.html .. contents:: @@ -31,11 +36,17 @@ indented, aligned with the left edge of the directive type. Admonitions ------------- -DTD elements: attention, caution, danger, error, hint, important, -note, tip, warning. +* Directive Types: "attention", "caution", "danger", "error", "hint", + "important", "note", "tip", "warning" + +* DTD Elements: attention, caution, danger, error, hint, important, + note, tip, warning + +* Directive Block: -Directive block: directive data and all following indented text -are interpreted as body elements. + - Arguments: None. + - Options: None. + - Content: Interpreted as body elements. Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. @@ -90,25 +101,30 @@ There are two image directives: "image" and "figure". Image ===== -DTD element: image. +* Directive Type: "image" -Directive block: directive data and following indented lines (up to -the first blank line) are interpreted as image URI and optional -attributes. +* DTD Element: image + +* Directive Block: + + - Arguments: One, required (image URI). + - Options: Possible. + - Content: None. 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. +The URI for the image source file is specified in the directive +argument. 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 options`. For example:: .. image:: picture.jpeg :height: 100 @@ -116,7 +132,7 @@ _`image attributes`. For example:: :scale: 50 :alt: alternate text -The following attributes are recognized: +The following options are recognized: ``alt`` : text Alternate text: a short description of the image, displayed by @@ -136,15 +152,19 @@ The following attributes are recognized: Figure ====== -DTD elements: figure, image, caption, legend. +* Directive Type: "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. +* Directive Block: -A "figure" consists of image_ data (optionally including `image -attributes`_), an optional caption (a single paragraph), and an -optional legend (arbitrary body elements):: + - Arguments: One, required (image URI). + - Options: Possible. + - Content: Interpreted as the figure caption and an optional legend. + +A "figure" consists of image_ data (including `image options`_), an +optional caption (a single paragraph), and an optional legend +(arbitrary body elements):: .. figure:: picture.png :scale: 50 @@ -166,7 +186,7 @@ optional legend (arbitrary body elements):: | .. image:: peak.png | Mountain | +-----------------------+-----------------------+ -There must be a blank line before the caption paragraph and before the +There must be blank lines before the caption paragraph and before the legend. To specify a legend without a caption, use an empty comment ("..") in place of the caption. @@ -178,19 +198,25 @@ legend. To specify a legend without a caption, use an empty comment Topic ===== -DTD element: topic. +* Directive Type: "topic" + +* DTD Element: topic + +* Directive Block: -Directive block: directive data and all following indented lines are -collected. The first line is interpreted as the topic title; the -second line must be blank. All subsequent lines are the topic body, -interpreted as body elements. + - Arguments: None. + - Options: None. + - Content: Interpreted as the topic title and body. A topic is like a block quote with a title, or a self-contained section with no subsections. Use the "topic" directive to indicate a self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or transition may occur. Body -elements (including topics) may not contain nested topics. For -example:: +elements (including topics) may not contain nested topics. + +The first line of the directive content block is interpreted as the +topic title; the second line must be blank. All subsequent lines make +up the topic body, interpreted as body elements. For example:: topic:: Topic Title @@ -202,10 +228,15 @@ example:: Line Block ========== -DTD element: line_block. +* Directive Type: "line-block" + +* DTD Element: line_block + +* Directive Block: -Directive block: directive data and all following indented text become -the body of the line block. + - Arguments: None. + - Options: None. + - Content: Becomes the body of the line block. The "line-block" directive constructs an element where whitespace (including linebreaks) is significant and inline markup is supported. @@ -230,10 +261,15 @@ significant. For example, here's a classic:: Parsed Literal Block ==================== -DTD element: literal_block. +* Directive Type: "literal-block" -Directive block: directive data and all following indented text become -the body of the literal block. +* DTD Element: literal_block + +* Directive Block: + + - Arguments: None. + - Options: None. + - Content: Becomes the body of the literal block. Unlike an ordinary literal block, the "parsed-literal" directive constructs a literal block where the text is parsed for inline markup. @@ -242,6 +278,7 @@ typically in a typewriter/monospaced typeface, like an ordinary literal block. Parsed literal blocks are useful for adding hyperlinks to code examples. However, care must be taken with the text, because inline markup is recognized; there is no protection from parsing. +Backslash-escapes may be necessary in places. For example, all the element names in this content model are links:: @@ -261,16 +298,20 @@ For example, all the element names in this content model are links:: Table of Contents ================= -DTD elements: pending, topic. +* Directive Type: "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. +* Directive Block: + + - Arguments: One, optional: title. + - Options: Possible. + - Content: None. 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 +the TOC title and any options 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. @@ -290,17 +331,17 @@ 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:: +Options 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 +If the default title is to be used, the options field list may begin on the same line as the directive marker:: .. contents:: :depth: 2 -The following attributes are recognized: +The following options are recognized: ``depth`` : integer The number of section levels that are collected in the table of @@ -317,26 +358,31 @@ The following attributes are recognized: Automatic Section Numbering =========================== -DTD elements: pending, generated. +* Directive Type: "sectnum" or "section-autonumbering" (synonyms) + +* DTD Elements: pending, generated + +* Directive Block: -Directive block: directive data and following indented lines (up to -the first blank line) are interpreted as optional attributes. + - Arguments: None. + - Options: Possible. + - Content: None. The "sectnum" (or "section-autonumbering") directive automatically -numbers sections and subsections in a document. Section numbers of -the "multiple enumeration" form, where each level has a number, +numbers sections and subsections in a document. Section numbers are +of the "multiple enumeration" form, where each level has a number, separated by periods. For example, the title of section 1, subsection -2, subsubsection 3 would have "1.2.3" prefixed. +2, subsubsection 3 would have "1.2.3" prefixed. -The "sectnum" directive does its work in two passes: initial parse and -transform. During the initial parse, a "pending" element is generated -which acts as a placeholder, storing any attributes internally. At a -later stage in the processing, the "pending" element triggers a +The "sectnum" directive does its work in two passes: the initial parse +and a transform. During the initial parse, a "pending" element is +generated which acts as a placeholder, storing any options internally. +At a later stage in the processing, the "pending" element triggers a transform, which adds section numbers to titles. Section numbers are enclosed in a "generated" element, and titles have their "auto" attribute set to "1". -The following attributes are recognized: +The following options are recognized: ``depth`` : integer The number of section levels that are numbered by this directive. @@ -350,9 +396,15 @@ The following attributes are recognized: Target Footnotes ================ -DTD elements: pending, footnote, footnote_reference. +* Directive Type: "target-notes" -Directive block: unused; directive data must be empty. +* DTD Elements: pending, footnote, footnote_reference + +* Directive Block must be empty: + + - Arguments: None. + - Options: None. + - Content: None. The "target-notes" directive creates a footnote for each external target in the text, and corresponding footnote references after each @@ -366,7 +418,15 @@ Footnotes **NOT IMPLEMENTED YET** -DTD elements: pending, topic. +* Directive Type: "footnotes" + +* DTD Elements: pending, topic + +* Directive Block: + + - Arguments: None? + - Options: Possible? + - Content: None. @@@ @@ -376,7 +436,15 @@ Citations **NOT IMPLEMENTED YET** -DTD elements: pending, topic. +* Directive Type: "citations" + +* DTD Elements: pending, topic + +* Directive Block: + + - Arguments: None? + - Options: Possible? + - Content: None. @@@ @@ -388,10 +456,17 @@ DTD elements: pending, topic. Meta ==== -Non-standard element: meta. +. + +* Directive Type: "meta" + +* DTD Element: meta (non-standard) + +* Directive Block: -Directive block: directive data and following indented lines (up to -the first blank line) are parsed for a flat field list. + - Arguments: None. + - Options: None. + - Content: Must contain 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 @@ -452,20 +527,48 @@ Non-standard element: imagemap. Miscellaneous --------------- +Including an External Fragment +============================== + +**NOT IMPLEMENTED YET** + +* Directive Type: "include" + +* DTD Elements: depend on data being included + +* Directive Block: + + - Arguments: One, required (path to include file). + - Options: None. + - Content: None. + +The "include" directive reads a reStructuredText-formatted text file +and parses it in the current document's context at the point of the +directive. For example:: + + .. include:: inclusion.txt + + Raw Data Pass-Through ===================== **NOT IMPLEMENTED YET** -DTD element: pending. +* Directive Type: "raw" + +* DTD Element: pending -Directive block: the directive data is interpreted as an output format -type, and all following indented text is stored verbatim, -uninterpreted. +* Directive Block: + + - Arguments: One or two (?): one required (output format type), and + one optional (source path). + - Options: None? + - Content: Stored verbatim, uninterpreted. None (empty) if a source + path argument given. 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" +given in the first argument. 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. @@ -484,14 +587,25 @@ output stream:: \documentclass[twocolumn]{article} +Raw data can also be read from an external file, specified in an +optional second argument. In this case, the content block must be +empty. For example:: + + .. raw:: html inclusion.html + Restructuredtext-Test-Directive =============================== -DTD element: system_warning. +* Directive Type: "restructuredtext-test-directive" + +* DTD Element: system_warning + +* Directive Block: -Directive block: directive data is stored, and all following indented -text is interpreted as a literal block. + - Arguments: None. + - Options: None. + - Content: 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 -- cgit v1.2.1 From f5b14fd1f00f2a71b741df73e8aa6b75bbcc1113 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Aug 2002 00:22:54 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@601 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 5f38e9503..152bb37a7 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -456,8 +456,6 @@ Citations Meta ==== -. - * Directive Type: "meta" * DTD Element: meta (non-standard) -- cgit v1.2.1 From b02bac44e33d1df5fcba70c171ea3f38e0fe1c56 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Aug 2002 01:50:41 +0000 Subject: Fixed the quote from Anne Elk (MIss). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@603 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 68f914875..f0d8aec41 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1146,10 +1146,11 @@ reStructuredText source:: Big and scary; the "Tyrant King". Brontosaurus : herbivore - Small at one end, big in the middle, - and small again at the other end. + All brontosauruses are thin at one end, + much much thicker in the middle + and then thin again at the far end. - -- Anne Elk, Miss + -- Anne Elk (Miss) Pseudo-XML_ fragment from simple parsing:: @@ -1169,8 +1170,9 @@ Pseudo-XML_ fragment from simple parsing:: herbivore <definition> <paragraph> - Small at one end, big in the middle, - and small again at the other end. + All brontosauruses are thin at one end, + much much thicker in the middle + and then thin again at the far end. <paragraph> -- Anne Elk, Miss -- cgit v1.2.1 From 10c190454b624095d7e5d88a886b9409d9a5c3ae Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Aug 2002 01:53:32 +0000 Subject: oops git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@604 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index f0d8aec41..762d3e4b1 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1174,7 +1174,7 @@ Pseudo-XML_ fragment from simple parsing:: much much thicker in the middle and then thin again at the far end. <paragraph> - -- Anne Elk, Miss + -- Anne Elk (Miss) See definition_list_ and classifier_ for further examples. -- cgit v1.2.1 From 573c0a4a6e4d06733db75aa4226ad28296d14b46 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 4 Sep 2002 01:28:15 +0000 Subject: Added "line" attribute to ``system_message`` elements. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@620 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 244d4c9d0..a2d8a9e45 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -464,6 +464,7 @@ Table elements: table, tgroup, colspec, thead, tbody, row, entry. %basic.atts; %backrefs.att; level &number; #IMPLIED + line &number; #IMPLIED type NMTOKEN #IMPLIED> <!-- Used to pass raw data through the system. Also inline. --> -- cgit v1.2.1 From cd1e9b4d9c0e90cb2a42c23e70806ef6e531342f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 5 Sep 2002 03:29:58 +0000 Subject: Added a note redirecting newbies to the user docs. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@632 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 6cb80cf1f..fac98c63f 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -6,6 +6,17 @@ :Revision: $Revision$ :Date: $Date$ +.. Note:: + + This document is a detailed technical specification; it is not a + tutorial or a primer. If this is your first exposure to + reStructuredText, please read `A ReStructuredText Primer`_ and the + `Quick reStructuredText`_ user reference first. + +.. _A ReStructuredText Primer: ../../docs/rst/quickstart.html +.. _Quick reStructuredText: ../../docs/rst/quickref.html + + reStructuredText_ is plaintext that uses simple and intuitive constructs to indicate the structure of a document. These constructs are equally easy to read in raw and processed forms. This document is @@ -2515,10 +2526,8 @@ Markup errors are handled according to the specification in `PEP .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _Docutils: http://docutils.sourceforge.net/ -.. _Docutils Document Tree Structure: - http://docutils.sourceforge.net/spec/doctree.txt -.. _Generic Plaintext Document Interface DTD: - http://docutils.sourceforge.net/spec/gpdi.dtd +.. _Docutils Document Tree Structure: ../doctree.html +.. _Generic Plaintext Document Interface DTD: ../gpdi.dtd .. _transforms: http://docutils.sourceforge.net/docutils/transforms/ .. _Grouch: http://www.mems-exchange.org/software/grouch/ -- cgit v1.2.1 From ce0cc744ffdceb30b746c7292f2262a5841a0610 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 6 Sep 2002 02:13:56 +0000 Subject: Expanded description of inline markup start-strings in non-markup contexts. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@637 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index fac98c63f..6129f3f0f 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1506,7 +1506,7 @@ marks [#]_: .. [#] This list was inspired by the list of symbols for "Note Reference Marks" in The Chicago Manual of Style, 14th edition, - section 12.51. "Parallels" ("\|\|") were given in CMoS instead of + section 12.51. "Parallels" ("||") were given in CMoS instead of the pilcrow. The last four symbols (the card suits) were added arbitrarily. @@ -2189,8 +2189,21 @@ end-string will not be recognized or processed. literals`_. See `Escaping Mechanism`_ above for details. For example, none of the following are recognized as containing inline -markup start-strings: " * ", '"*"', "'*'", "(*)", "(* ", "[*]", "{*}", -"\*", " ` ", etc. +markup start-strings: + +- asterisks: * "*" '*' (*) (* [*] {*} 1*x BOM32_* +- double asterisks: ** a**b O(N**2) etc. +- backquotes: ` `` etc. +- underscores: _ __ __init__ __init__() etc. +- vertical bars: | || etc. + +It may be desirable to use inline literals for some of these anyhow, +especially if they represent code snippets. It's a judgement call. + +These cases *do* require either literal-quoting or escaping to avoid +misinterpretation:: + + *4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt The inline markup recognition rules were devised intentionally to allow 90% of non-markup uses of "*", "`", "_", and "|" *without* -- cgit v1.2.1 From 22255487b5b00ef04ccee60b61cf641a813e34a4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 7 Sep 2002 02:37:29 +0000 Subject: Tweaked the "line-block" description. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@648 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 152bb37a7..16e352cf8 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -242,20 +242,22 @@ The "line-block" directive constructs an element where whitespace (including linebreaks) is significant and inline markup is supported. It is equivalent to a `parsed literal block`_ with different rendering: typically in an ordinary serif typeface instead of a -typewriter/monospaced face. Line blocks are useful for address blocks -and verse (poetry, song lyrics), where the structure of lines is -significant. For example, here's a classic:: +typewriter/monospaced face, and not automatically indented. (Have the +line-block directive begin a block quote to get an indented line +block.) Line blocks are useful for address blocks and verse (poetry, +song lyrics), where the structure of lines is significant. For +example, here's a classic:: "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by Ewan McTeagle (for Lassie O'Shea): - .. line-block:: + .. line-block:: - Lend us a couple of bob till Thursday. - I'm absolutely skint. - But I'm expecting a postal order and I can pay you back - as soon as it comes. - Love, Ewan. + Lend us a couple of bob till Thursday. + I'm absolutely skint. + But I'm expecting a postal order and I can pay you back + as soon as it comes. + Love, Ewan. Parsed Literal Block -- cgit v1.2.1 From 25bf0b8d0031971e15ac206642bc3ca5ef279c33 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 7 Sep 2002 02:38:25 +0000 Subject: Added pointers to material for new users. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@649 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/introduction.txt | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index ea5c6ca90..0ec112a47 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -18,18 +18,25 @@ application domains. Its parser is a component of Docutils_. This document defines the goals_ of reStructuredText and provides a history_ of the project. It is written using the reStructuredText -markup, and therefore serves as an example of its use. Please also -see an analysis of the `Problems With StructuredText`_ and the -`reStructuredText Markup Specification`_ itself at the subproject's -web page, http://docutils.sourceforge.net/rst.html. +markup, and therefore serves as an example of its use. For a gentle +introduction to using reStructuredText, please read `A +ReStructuredText Primer`_. The `Quick reStructuredText`_ user +reference is also useful. The `reStructuredText Markup +Specification`_ is the definitive reference. There is also an +analysis of the `Problems With StructuredText`_. + +ReStructuredText's web page is +http://docutils.sourceforge.net/rst.html. .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _StructuredText: http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage .. _Setext: http://docutils.sourceforge.net/mirror/setext.html .. _Docutils: http://docutils.sourceforge.net/ -.. _Problems with StructuredText: problems.html +.. _A ReStructuredText Primer: ../../docs/rst/quickstart.html +.. _Quick reStructuredText: ../../docs/rst/quickref.html .. _reStructuredText Markup Specification: reStructuredText.html +.. _Problems with StructuredText: problems.html Goals -- cgit v1.2.1 From 27cbc2015c36bac9e75417045fc0ba2fc949d72c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 7 Sep 2002 02:39:01 +0000 Subject: Strengthened the admonition against using field lists arbitrarily. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@650 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 6129f3f0f..f8ed0e167 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -783,13 +783,15 @@ Field Lists DTD elements: field_list, field, field_name, field_argument, field_body. -Field lists are most often used as part of an extension syntax, such -as options for directives_, or database-like records meant for further +Field lists are used as part of an extension syntax, such as options +for directives_, or database-like records meant for further processing. They are not intended to be an alternative to definition -lists. Applications of reStructuredText may recognize field names and -transform fields or field bodies in certain contexts. See -`Bibliographic Fields`_ below for one example, or the "image" -directive in `reStructuredText Directives`_ for another. +lists or tables. Applications of reStructuredText may recognize field +names and transform fields or field bodies in certain contexts. Field +lists should only be used when and where application code specifically +expects them; they should *not* be used as arbitrary constructs in +documents. See `Bibliographic Fields`_ below for one example, or the +"image" directive in `reStructuredText Directives`_ for another. Field lists are mappings from field names to field bodies, modeled on RFC822_ headers. A field name is made up of one or more letters, -- cgit v1.2.1 From 9a91d7c843178280693025015b88590c8355f820 Mon Sep 17 00:00:00 2001 From: chodorowski <chodorowski@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 9 Sep 2002 17:27:35 +0000 Subject: Updated with respect to the 'align' option of the 'image' directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@656 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 16e352cf8..9df09b2d1 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -131,6 +131,7 @@ _`image options`. For example:: :width: 200 :scale: 50 :alt: alternate text + :align: right The following options are recognized: @@ -147,6 +148,12 @@ The following options are recognized: ``scale`` : integer The uniform scaling factor of the image, a percentage (but no "%" symbol is required or allowed). "100" means full-size. +``align`` : keyword + The alignment of the image. Allowed values are "top", "middle" and + "bottom" which control the vertical alignment (relative to the text + baseline) in addition to "left", "center" and "right" which control + the horizontal alignment (allowing you to float the image, having the + text flow around it). Figure -- cgit v1.2.1 From 92bce10953abbbdee17337bd6cdcb01208144810 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 10 Sep 2002 03:25:23 +0000 Subject: Clarified the "image" directive's "align" attribute description. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@657 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 9df09b2d1..897e276eb 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -148,12 +148,15 @@ The following options are recognized: ``scale`` : integer The uniform scaling factor of the image, a percentage (but no "%" symbol is required or allowed). "100" means full-size. -``align`` : keyword - The alignment of the image. Allowed values are "top", "middle" and - "bottom" which control the vertical alignment (relative to the text - baseline) in addition to "left", "center" and "right" which control - the horizontal alignment (allowing you to float the image, having the - text flow around it). +``align`` : "top", "middle", "bottom", "left", "center", or "right" + The alignment of the image, equivalent to the HTML ``<img>`` tag's + "align" attribute. The values "top", "middle", and "bottom" + control an image's vertical alignment (relative to the text + baseline); they are only useful for inline images (substitutions). + The values "left", "center", and "right" control an image's + horizontal alignment, allowing the image to float and have the + text flow around it. The specific behavior depends upon the + browser or rendering software used. Figure -- cgit v1.2.1 From a07bc663d7654004db7594bb1601525b18d46f4a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 11 Sep 2002 02:52:01 +0000 Subject: Removed "field_argument" element & support; "field_name" may contain multiple words and whitespace. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@664 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 9 +------ docs/ref/docutils.dtd | 6 +---- docs/ref/rst/restructuredtext.txt | 57 +++++++++++++++++---------------------- 3 files changed, 26 insertions(+), 46 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 762d3e4b1..16a700ce4 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -185,8 +185,7 @@ always occur within specific parent elements, never at the body element level (beside paragraphs, etc.). Category members (simple): caption_, classifier_, colspec_, -field_argument_, field_name_, label_, option_argument_, -option_string_, term_ +field_name_, label_, option_argument_, option_string_, term_ Category members (compound): definition_, definition_list_item_, description_, entry_, field_, field_body_, legend_, list_item_, @@ -1510,12 +1509,6 @@ See list_item_ for another example. `To be completed`_. -``field_argument`` -================== - -`To be completed`_. - - ``field_body`` ============== diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index a2d8a9e45..19094bbf2 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -314,16 +314,12 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT field_list (field+)> <!ATTLIST field_list %basic.atts;> -<!ELEMENT field (field_name, field_argument*, field_body)> +<!ELEMENT field (field_name, field_body)> <!ATTLIST field %basic.atts;> <!ELEMENT field_name (#PCDATA)> <!ATTLIST field_name %basic.atts;> -<!-- Support for Javadoc-style tags with arguments. --> -<!ELEMENT field_argument (#PCDATA)> -<!ATTLIST field_argument %basic.atts;> - <!-- May be empty. --> <!ELEMENT field_body (%body.elements;)*> <!ATTLIST field_body %basic.atts;> diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index f8ed0e167..96a5449b8 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -102,8 +102,8 @@ Here are examples of `body elements`_: database records. They are often part of an extension syntax. - :how: The field marker is a colon, the field name, optional - field arguments, and a colon. + :how: The field marker is a colon, the field name, and a + colon. The field body may contain one or more body elements, indented relative to the field marker. @@ -780,30 +780,26 @@ Syntax diagram:: Field Lists ----------- -DTD elements: field_list, field, field_name, field_argument, -field_body. +DTD elements: field_list, field, field_name, field_body. Field lists are used as part of an extension syntax, such as options for directives_, or database-like records meant for further -processing. They are not intended to be an alternative to definition -lists or tables. Applications of reStructuredText may recognize field -names and transform fields or field bodies in certain contexts. Field -lists should only be used when and where application code specifically -expects them; they should *not* be used as arbitrary constructs in -documents. See `Bibliographic Fields`_ below for one example, or the -"image" directive in `reStructuredText Directives`_ for another. +processing. They may also be used for two-column table-like +structures resembling database records (label & data pairs). +Applications of reStructuredText may recognize field names and +transform fields or field bodies in certain contexts. For examples, +see `Bibliographic Fields`_ below, or the "image" and "meta" +directives in `reStructuredText Directives`_. Field lists are mappings from field names to field bodies, modeled on RFC822_ headers. A field name is made up of one or more letters, -numbers, and punctuation, except colons (":") and whitespace. Field -names are case-insensitive. There may be additional data separated -from the field name, called field arguments. The field name and -optional field argument(s), along with a single colon prefix and -suffix, together form the field marker. The field marker is followed -by whitespace and the field body. The field body may contain multiple -body elements, indented relative to the field marker. The first line -after the field name marker determines the indentation of the field -body. For example:: +numbers, whitespace, and punctuation, except colons (":"). Field +names are case-insensitive. The field name, along with a single colon +prefix and suffix, together form the field marker. The field marker +is followed by whitespace and the field body. The field body may +contain multiple body elements, indented relative to the field marker. +The first line after the field name marker determines the indentation +of the field body. For example:: :Date: 2001-08-16 :Version: 1 @@ -816,16 +812,11 @@ body. For example:: field name marker, and they must line up with each other. :Parameter i: integer -Field arguments are separated from the field name and each other by -whitespace, and may not contain colons (":"). The interpretation of -field arguments is up to the application. For example:: - - :name1 word number=1: - Both "word" and "number=1" are single words. - -The syntax for field arguments may be extended in the future. For -example, quoted phrases may be treated as a single argument, and -direct support for the "name=value" syntax may be added. +The interpretation of individual words in a multi-word field name is +up to the application. The application may specify a syntax for the +field name. For example, second and subsequent words may be treated +as "arguments", quoted phrases may be treated as a single argument, +and direct support for the "name=value" syntax may be added. Standard RFC822_ headers cannot be used for this construct because they are ambiguous. A word followed by a colon at the beginning of a @@ -836,9 +827,9 @@ used. Syntax diagram (simplified):: - +------------------------------+------------+ - | ":" name (" " argument)* ":" | field body | - +-------+----------------------+ | + +--------------------+----------------------+ + | ":" field name ":" | field body | + +-------+------------+ | | (body elements)+ | +-----------------------------------+ -- cgit v1.2.1 From 7cbb92de5ba3bbe3a995f9b73f5775d7ef1c4d9e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 15 Sep 2002 16:34:13 +0000 Subject: updated "raw" and "include" directive descriptions; converted bullet lists to field lists git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@682 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 250 +++++++++++++++++++------------------------- 1 file changed, 109 insertions(+), 141 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 897e276eb..c78e572c2 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -36,17 +36,14 @@ Specification`_ for syntax details. Admonitions ------------- -* Directive Types: "attention", "caution", "danger", "error", "hint", - "important", "note", "tip", "warning" - -* DTD Elements: attention, caution, danger, error, hint, important, - note, tip, warning - -* Directive Block: - - - Arguments: None. - - Options: None. - - Content: Interpreted as body elements. +:Directive Types: "attention", "caution", "danger", "error", "hint", + "important", "note", "tip", "warning" +:DTD Elements: attention, caution, danger, error, hint, important, + note, tip, warning +:Directive Block: + :Arguments: None. + :Options: None. + :Content: Interpreted as body elements. Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. @@ -101,15 +98,12 @@ There are two image directives: "image" and "figure". Image ===== -* Directive Type: "image" - -* DTD Element: image - -* Directive Block: - - - Arguments: One, required (image URI). - - Options: Possible. - - Content: None. +:Directive Type: "image" +:DTD Element: image +:Directive Block: + :Arguments: One, required (image URI). + :Options: Possible. + :Content: None. An "image" is a simple picture:: @@ -162,15 +156,13 @@ The following options are recognized: Figure ====== -* Directive Type: "figure" - -* DTD Elements: figure, image, caption, legend +:Directive Type: "figure" +:DTD Elements: figure, image, caption, legend +:Directive Block: -* Directive Block: - - - Arguments: One, required (image URI). - - Options: Possible. - - Content: Interpreted as the figure caption and an optional legend. + :Arguments: One, required (image URI). + :Options: Possible. + :Content: Interpreted as the figure caption and an optional legend. A "figure" consists of image_ data (including `image options`_), an optional caption (a single paragraph), and an optional legend @@ -208,15 +200,12 @@ legend. To specify a legend without a caption, use an empty comment Topic ===== -* Directive Type: "topic" - -* DTD Element: topic - -* Directive Block: - - - Arguments: None. - - Options: None. - - Content: Interpreted as the topic title and body. +:Directive Type: "topic" +:DTD Element: topic +:Directive Block: + :Arguments: None. + :Options: None. + :Content: Interpreted as the topic title and body. A topic is like a block quote with a title, or a self-contained section with no subsections. Use the "topic" directive to indicate a @@ -238,15 +227,12 @@ up the topic body, interpreted as body elements. For example:: Line Block ========== -* Directive Type: "line-block" - -* DTD Element: line_block - -* Directive Block: - - - Arguments: None. - - Options: None. - - Content: Becomes the body of the line block. +:Directive Type: "line-block" +:DTD Element: line_block +:Directive Block: + :Arguments: None. + :Options: None. + :Content: Becomes the body of the line block. The "line-block" directive constructs an element where whitespace (including linebreaks) is significant and inline markup is supported. @@ -273,15 +259,12 @@ example, here's a classic:: Parsed Literal Block ==================== -* Directive Type: "literal-block" - -* DTD Element: literal_block - -* Directive Block: - - - Arguments: None. - - Options: None. - - Content: Becomes the body of the literal block. +:Directive Type: "literal-block" +:DTD Element: literal_block +:Directive Block: + :Arguments: None. + :Options: None. + :Content: Becomes the body of the literal block. Unlike an ordinary literal block, the "parsed-literal" directive constructs a literal block where the text is parsed for inline markup. @@ -310,15 +293,12 @@ For example, all the element names in this content model are links:: Table of Contents ================= -* Directive Type: "contents" - -* DTD Elements: pending, topic - -* Directive Block: - - - Arguments: One, optional: title. - - Options: Possible. - - Content: None. +:Directive Type: "contents" +:DTD Elements: pending, topic +:Directive Block: + :Arguments: One, optional: title. + :Options: Possible. + :Content: None. The "contents" directive inserts a table of contents (TOC) in two passes: initial parse and transform. During the initial parse, a @@ -370,15 +350,12 @@ The following options are recognized: Automatic Section Numbering =========================== -* Directive Type: "sectnum" or "section-autonumbering" (synonyms) - -* DTD Elements: pending, generated - -* Directive Block: - - - Arguments: None. - - Options: Possible. - - Content: None. +:Directive Type: "sectnum" or "section-autonumbering" (synonyms) +:DTD Elements: pending, generated +:Directive Block: + :Arguments: None. + :Options: Possible. + :Content: None. The "sectnum" (or "section-autonumbering") directive automatically numbers sections and subsections in a document. Section numbers are @@ -408,15 +385,12 @@ The following options are recognized: Target Footnotes ================ -* Directive Type: "target-notes" - -* DTD Elements: pending, footnote, footnote_reference - -* Directive Block must be empty: - - - Arguments: None. - - Options: None. - - Content: None. +:Directive Type: "target-notes" +:DTD Elements: pending, footnote, footnote_reference +:Directive Block: + :Arguments: None. + :Options: None. + :Content: None. The "target-notes" directive creates a footnote for each external target in the text, and corresponding footnote references after each @@ -430,15 +404,12 @@ Footnotes **NOT IMPLEMENTED YET** -* Directive Type: "footnotes" - -* DTD Elements: pending, topic - -* Directive Block: - - - Arguments: None? - - Options: Possible? - - Content: None. +:Directive Type: "footnotes" +:DTD Elements: pending, topic +:Directive Block: + :Arguments: None? + :Options: Possible? + :Content: None. @@@ @@ -448,15 +419,12 @@ Citations **NOT IMPLEMENTED YET** -* Directive Type: "citations" - -* DTD Elements: pending, topic - -* Directive Block: - - - Arguments: None? - - Options: Possible? - - Content: None. +:Directive Type: "citations" +:DTD Elements: pending, topic +:Directive Block: + :Arguments: None? + :Options: Possible? + :Content: None. @@@ @@ -468,15 +436,12 @@ Citations Meta ==== -* Directive Type: "meta" - -* DTD Element: meta (non-standard) - -* Directive Block: - - - Arguments: None. - - Options: None. - - Content: Must contain a flat field list. +:Directive Type: "meta" +:DTD Element: meta (non-standard) +:Directive Block: + :Arguments: None. + :Options: None. + :Content: Must contain 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 @@ -542,15 +507,12 @@ Including an External Fragment **NOT IMPLEMENTED YET** -* Directive Type: "include" - -* DTD Elements: depend on data being included - -* Directive Block: - - - Arguments: One, required (path to include file). - - Options: None. - - Content: None. +:Directive Type: "include" +:DTD Elements: depend on data being included +:Directive Block: + :Arguments: One, required (path to include file). + :Options: Possible. + :Content: None. The "include" directive reads a reStructuredText-formatted text file and parses it in the current document's context at the point of the @@ -558,23 +520,25 @@ directive. For example:: .. include:: inclusion.txt +The following options are recognized: + +``literal`` : empty + The entire included text is inserted into the document as a single + literal block (useful for program listings). + Raw Data Pass-Through ===================== **NOT IMPLEMENTED YET** -* Directive Type: "raw" - -* DTD Element: pending - -* Directive Block: - - - Arguments: One or two (?): one required (output format type), and - one optional (source path). - - Options: None? - - Content: Stored verbatim, uninterpreted. None (empty) if a source - path argument given. +:Directive Type: "raw" +:DTD Element: pending +:Directive Block: + :Arguments: One, required (output format type). + :Options: Possible + :Content: Stored verbatim, uninterpreted. None (empty) if a + "file" or "url" option given. The "raw" directive indicates non-reStructuredText data that is to be passed untouched to the Writer. The name of the output format is @@ -598,24 +562,28 @@ output stream:: \documentclass[twocolumn]{article} Raw data can also be read from an external file, specified in an -optional second argument. In this case, the content block must be -empty. For example:: - - .. raw:: html inclusion.html +option. In this case, the content block must be empty. For example:: + .. raw:: html + :file: inclusion.html -Restructuredtext-Test-Directive -=============================== +The following options are recognized: -* Directive Type: "restructuredtext-test-directive" +``file`` : string + The filesystem path of a raw data file to be included. +``url`` : string + An Internet URL reference to a raw data file to be included. -* DTD Element: system_warning -* Directive Block: +Restructuredtext-Test-Directive +=============================== - - Arguments: None. - - Options: None. - - Content: Interpreted as a literal block. +:Directive Type: "restructuredtext-test-directive" +:DTD Element: system_warning +:Directive Block: + :Arguments: None. + :Options: None. + :Content: 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 -- cgit v1.2.1 From 3726101cf3b5aaab4e52591a64de77f7dc0fcbcc Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 19 Sep 2002 00:38:22 +0000 Subject: Removed the 4-character minimum for section title underlines. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@688 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 96a5449b8..46673010b 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -452,12 +452,10 @@ matching "overlines" above the title. An underline/overline is a single repeated punctuation character that begins in column 1 and forms a line extending at least as far as the right edge of the title text. Specifically, an underline/overline character may be any -non-alphanumeric printable 7-bit ASCII character [#]_. An -underline/overline must be at least 4 characters long (to avoid -mistaking ellipses ["..."] for overlines). When an overline is used, -the length and character used must match the underline. There may be -any number of levels of section titles, although some output formats -may have limits (HTML has 6 levels). +non-alphanumeric printable 7-bit ASCII character [#]_. When an +overline is used, the length and character used must match the +underline. There may be any number of levels of section titles, +although some output formats may have limits (HTML has 6 levels). .. [#] The following are all valid section title adornment characters:: -- cgit v1.2.1 From b95ac892ffd6bcd165b5459b0b0f656099c896cf Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 19 Sep 2002 00:46:40 +0000 Subject: converted definition lists to field lists git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@693 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 399 ++++++++++++++++++++++++--------------------------- 1 file changed, 185 insertions(+), 214 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 16a700ce4..c490e5044 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -293,19 +293,18 @@ line_block_ element: whitespace is significant, especially newlines. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: The following elements may contain ``address``: docinfo_, authors_ -Children +:Children: ``address`` elements contain text data plus `inline elements`_. -Analogies +:Analogies: ``address`` is analogous to the DocBook "address" element. -Processing +:Processing: As with the line_block_ element, newlines and other whitespace is significant and must be preserved. However, a monospaced typeface need not be used. @@ -320,11 +319,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``address`` element contains the `common attributes`_ (id_, name_, dupname_, source_, and class_), plus `xml:space`_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``address``. @@ -370,19 +369,18 @@ The ``author`` element holds the name of the author of the document. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: The following elements may contain ``author``: docinfo_, authors_ -Children +:Children: ``author`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``author`` is analogous to the DocBook "author" element. -Processing +:Processing: See docinfo_. @@ -393,11 +391,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``author`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``author``. @@ -435,20 +433,19 @@ documents with multiple authors. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``authors``. -Children +:Children: ``authors`` elements may contain the following elements: author_, organization_, address_, contact_ -Analogies +:Analogies: ``authors`` is analogous to the DocBook "authors" element. -Processing +:Processing: See docinfo_. @@ -459,11 +456,11 @@ Content Model ((author_, organization_?, address_?, contact_?)+) -Attributes +:Attributes: The ``authors`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``authors``. @@ -516,18 +513,17 @@ uniformly marked with bullets. Bullets are typically simple dingbats Details ------- -Category - `Compound Body Elements`_ +:Category: `Compound Body Elements`_ -Parents +:Parents: All elements employing the `%body.elements;`_ or `%structure.model;`_ parameter entities in their content models may contain ``bullet_list``. -Children +:Children: ``bullet_list`` elements contain one or more list_item_ elements. -Analogies +:Analogies: ``bullet_list`` is analogous to the HTML "ul" element and to the DocBook "itemizedlist" element. HTML's "ul" is short for "unordered list", which we consider to be a misnomer. "Unordered" @@ -535,7 +531,7 @@ Analogies affecting the meaning of the list. Bullet lists *are* often ordered; the ordering is simply left implicit. -Processing +:Processing: Each list item should begin a new vertical block, prefaced by a bullet/dingbat. @@ -547,7 +543,7 @@ Content Model (list_item_+) -Attributes +:Attributes: The ``bullet_list`` element contains the `common attributes`_ (id_, name_, dupname_, source_, and class_), plus bullet_. @@ -555,7 +551,7 @@ Attributes data. In reStructuredText, it contains one of "-", "+", or "*". It may be ignored in processing. -Parameter Entities +:Parameter Entities: The `%body.elements;`_ parameter entity directly includes ``bullet_list``. The `%structure.model;`_ parameter entity indirectly includes ``bullet_list``. @@ -622,20 +618,19 @@ used to indicate the type of a variable. Details ------- -Category - `Body Subelements`_ (simple) +:Category: `Body Subelements`_ (simple) -Parents +:Parents: Only the definition_list_item_ element contains ``classifier``. -Children +:Children: ``classifier`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``classifier`` has no direct analogues in common DTDs. It can be emulated with primitives or type effects. -Processing +:Processing: See definition_list_item_. @@ -646,7 +641,7 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``classifier`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -705,21 +700,20 @@ is typically used for an email or web address. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: The following elements may contain ``contact``: docinfo_, authors_ -Children +:Children: ``contact`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``contact`` is analogous to the DocBook "email" element. The HTML "address" element serves a similar purpose. -Processing +:Processing: See docinfo_. @@ -730,11 +724,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``contact`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``contact``. @@ -772,20 +766,19 @@ The ``copyright`` element contains the document's copyright statement. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``copyright``. -Children +:Children: ``copyright`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``copyright`` is analogous to the DocBook "copyright" element. -Processing +:Processing: See docinfo_. @@ -796,11 +789,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``copyright`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``copyright``. @@ -844,19 +837,18 @@ last modification of the document. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``date``. -Children +:Children: ``date`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``date`` is analogous to the DocBook "date" element. -Processing +:Processing: Often used with the RCS/CVS keyword "Date". See docinfo_. @@ -867,11 +859,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``date`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``date``. @@ -912,21 +904,20 @@ footer_ element is implemented, populated with processing information Details ------- -Category - `Structural Subelements`_ +:Category: `Structural Subelements`_ -Parents +:Parents: Only the document_ element contains ``decoration``. -Children +:Children: ``decoration`` elements may contain `decorative elements`_. -Analogies +:Analogies: There are no direct analogies to ``decoration`` in HTML or in DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. -Processing +:Processing: See the individual `decorative elements`_. Content Model @@ -939,7 +930,7 @@ Content Model Although the content model doesn't specifically require contents, no empty ``decoration`` elements are ever created. -Attributes +:Attributes: The ``decoration`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -974,20 +965,19 @@ to define a term_ in a definition_list_. Details ------- -Category - `Body Subelements`_ (compound) +:Category: `Body Subelements`_ (compound) -Parents +:Parents: Only definition_list_item_ elements contain ``definition``. -Children +:Children: ``definition`` elements may contain `body elements`_. -Analogies +:Analogies: ``definition`` is analogous to the HTML "dd" element and to the DocBook "listitem" element (inside a "variablelistentry" element). -Processing +:Processing: See definition_list_item_. @@ -998,7 +988,7 @@ Content Model (`%body.elements;`_)+ -Attributes +:Attributes: The ``definition`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1022,23 +1012,22 @@ describe or classify things, for dialogues, or to itemize subtopics Details ------- -Category - `Compound Body Elements`_ +:Category: `Compound Body Elements`_ -Parents +:Parents: All elements employing the `%body.elements;`_ or `%structure.model;`_ parameter entities in their content models may contain ``definition_list``. -Children +:Children: ``definition_list`` elements contain one or more definition_list_item_ elements. -Analogies +:Analogies: ``definition_list`` is analogous to the HTML "dl" element and to the DocBook "variablelist" element. -Processing +:Processing: See definition_list_item_. @@ -1049,11 +1038,11 @@ Content Model (definition_list_item_+) -Attributes +:Attributes: The ``definition_list`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%body.elements;`_ parameter entity directly includes ``definition_list``. The `%structure.model;`_ parameter entity indirectly includes ``definition_list``. @@ -1103,22 +1092,21 @@ term_/definition_ pair (with optional classifier_). Details ------- -Category - `Body Subelements`_ (compound) +:Category: `Body Subelements`_ (compound) -Parents +:Parents: Only the definition_list_ element contains ``definition_list_item``. -Children +:Children: ``definition_list_item`` elements each contain a single term_, an optional classifier_, and a definition_. -Analogies +:Analogies: ``definition_list_item`` is analogous to the DocBook "variablelistentry" element. -Processing +:Processing: The optional classifier_ can be rendered differently from the term_. They should be separated visually, typically by spaces plus a colon or dash. @@ -1131,7 +1119,7 @@ Content Model (term_, classifier_?, definition_) -Attributes +:Attributes: The ``definition_list_item`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1195,21 +1183,20 @@ front matter of a book, such as the title page and copyright page. Details ------- -Category - `Structural Subelements`_ +:Category: `Structural Subelements`_ -Parents +:Parents: Only the document_ element contains ``docinfo``. -Children +:Children: ``docinfo`` elements contain `bibliographic elements`_. -Analogies +:Analogies: ``docinfo`` is analogous to DocBook "info" elements ("bookinfo" etc.). There are no directly analogous HTML elements; the "meta" element carries some of the same information, albeit invisibly. -Processing +:Processing: The ``docinfo`` element may be rendered as a two-column table or in other styles. It may even be invisible or omitted from the processed output. Meta-data may be extracted from ``docinfo`` @@ -1231,7 +1218,7 @@ Content Model (`%bibliographic.elements;`_)+ -Attributes +:Attributes: The ``docinfo`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1307,17 +1294,16 @@ tree. It is the starting point for a document. Details ------- -Category - `Structural Elements`_ +:Category: `Structural Elements`_ -Parents +:Parents: The ``document`` element has no parents. -Children +:Children: ``document`` elements may contain `structural subelements`_, `structural elements`_, and `body elements`_. -Analogies +:Analogies: ``document`` is analogous to the HTML "html" element and to several DocBook elements such as "book". @@ -1345,7 +1331,7 @@ programmatically. See the `%structure.model;`_ parameter entity for details of the body of a ``document``. -Attributes +:Attributes: The ``document`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1401,23 +1387,22 @@ uniformly marked with enumerator labels. Details ------- -Category - `Compound Body Elements`_ +:Category: `Compound Body Elements`_ -Parents +:Parents: All elements employing the `%body.elements;`_ or `%structure.model;`_ parameter entities in their content models may contain ``enumerated_list``. -Children +:Children: ``enumerated_list`` elements contain one or more list_item_ elements. -Analogies +:Analogies: ``enumerated_list`` is analogous to the HTML "ol" element and to the DocBook "orderedlist" element. -Processing +:Processing: Each list item should begin a new vertical block, prefaced by a enumeration marker (such as "1."). @@ -1429,7 +1414,7 @@ Content Model (list_item_+) -Attributes +:Attributes: The ``enumerated_list`` element contains the `common attributes`_ (id_, name_, dupname_, source_, and class_), plus enumtype_, prefix_, suffix_, and start_. @@ -1455,7 +1440,7 @@ Attributes list, in decimal. For lists beginning at value 1 ("1", "a", "A", "i", or "I"), this attribute may be omitted. -Parameter Entities +:Parameter Entities: The `%body.elements;`_ parameter entity directly includes ``enumerated_list``. The `%structure.model;`_ parameter entity indirectly includes ``enumerated_list``. @@ -1545,16 +1530,15 @@ processing information (datestamp, a link to Docutils_, etc.). Details ------- -Category - `Decorative Elements`_ +:Category: `Decorative Elements`_ -Parents +:Parents: Only the decoration_ element contains ``footer``. -Children +:Children: ``footer`` elements may contain `body elements`_. -Analogies +:Analogies: There are no direct analogies to ``footer`` in HTML or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. @@ -1567,7 +1551,7 @@ Content Model (`%body.elements;`_)+ -Attributes +:Attributes: The ``footer`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1621,16 +1605,15 @@ page. Docutils does not yet make use of the ``header`` element. Details ------- -Category - `Decorative Elements`_ +:Category: `Decorative Elements`_ -Parents +:Parents: Only the decoration_ element contains ``header``. -Children +:Children: ``header`` elements may contain `body elements`_. -Analogies +:Analogies: There are no direct analogies to ``header`` in HTML or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. @@ -1643,7 +1626,7 @@ Content Model (`%body.elements;`_)+ -Attributes +:Attributes: The ``header`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1706,21 +1689,20 @@ item. Details ------- -Category - `Body Subelements`_ (compound) +:Category: `Body Subelements`_ (compound) -Parents +:Parents: The bullet_list_ and enumerated_list_ elements contain ``list_item``. -Children +:Children: ``list_item`` elements may contain `body elements`_. -Analogies +:Analogies: ``list_item`` is analogous to the HTML "li" element and to the DocBook "listitem" element. -Processing +:Processing: See bullet_list_ or enumerated_list_. @@ -1731,7 +1713,7 @@ Content Model (`%body.elements;`_)+ -Attributes +:Attributes: The ``list_item`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1832,21 +1814,20 @@ organization, or the organization responsible for the document. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``organization``. -Children +:Children: ``organization`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``organization`` is analogous to the DocBook "orgname", "corpname", or "publishername" elements. -Processing +:Processing: See docinfo_. @@ -1857,11 +1838,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``organization`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``organization``. @@ -1899,19 +1880,18 @@ single paragraph, a fundamental building block of documents. Details ------- -Category - `Simple Body Elements`_ +:Category: `Simple Body Elements`_ -Parents +:Parents: All elements employing the `%body.elements;`_ or `%structure.model;`_ parameter entities in their content models may contain ``paragraph``. -Children +:Children: ``paragraph`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``paragraph`` is analogous to the HTML "p" element and to the DocBook "para" elements. @@ -1923,11 +1903,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``paragraph`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%body.elements;`_ parameter entity directly includes ``paragraph``. The `%structure.model;`_ parameter entity indirectly includes ``paragraph``. @@ -1980,22 +1960,21 @@ It can be used alone or in conjunction with version_. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``revision``. -Children +:Children: ``revision`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``revision`` is analogous to but simpler than the DocBook "revision" element. It closely matches the DocBook "revnumber" element, but in a simpler context. -Processing +:Processing: Often used with the RCS/CVS keyword "Revision". See docinfo_. @@ -2006,11 +1985,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``revision`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``revision``. @@ -2060,18 +2039,17 @@ not after it. Details ------- -Category - `Structural Elements`_ +:Category: `Structural Elements`_ -Parents +:Parents: The following elements may contain ``section``: document_, section_ -Children +:Children: ``section`` elements begin with a title_, and may contain `body elements`_ and transition_ and topic_ elements. -Analogies +:Analogies: ``section`` is analogous to DocBook recursive "section" elements, and to HTML "div" elements combined with "h1" etc. title elements. @@ -2087,11 +2065,11 @@ Content Model See the `%structure.model;`_ parameter entity for details of the body of a ``section``. -Attributes +:Attributes: The ``section`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%section.elements;`_ parameter entity directly includes ``section``. The `%structure.model;`_ parameter entity indirectly includes ``section``. @@ -2153,19 +2131,18 @@ such as "Draft", "Final", "Work In Progress", etc. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``status``. -Children +:Children: ``status`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``status`` is analogous to the DocBook "status" element. -Processing +:Processing: See docinfo_. @@ -2176,11 +2153,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``status`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``status``. @@ -2235,21 +2212,20 @@ The ``subtitle`` element stores the subtitle of a document_. Details ------- -Category - `Structural Subelements`_ +:Category: `Structural Subelements`_ -Parents +:Parents: Only the document_ element contains ``subtitle``. -Children +:Children: ``subtitle`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``subtitle`` is analogous to HTML header elements ("h2" etc.) and to the DocBook "subtitle" element. -Processing +:Processing: A document's subtitle is usually rendered smaller than its title_. @@ -2260,7 +2236,7 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``subtitle`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -2329,20 +2305,19 @@ definition_list_. Details ------- -Category - `Body Subelements`_ (simple) +:Category: `Body Subelements`_ (simple) -Parents +:Parents: Only the definition_list_item_ element contains ``term``. -Children +:Children: ``term`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``term`` is analogous to the HTML "dt" element and to the DocBook "term" element. -Processing +:Processing: See definition_list_item_. @@ -2353,7 +2328,7 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``term`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -2393,17 +2368,16 @@ topic_. Details ------- -Category - `Structural Subelements`_ +:Category: `Structural Subelements`_ -Parents +:Parents: The following elements may contain ``title``: document_, section_, topic_ -Children +:Children: ``title`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``title`` is analogous to HTML "title" and header ("h1" etc.) elements, and to the DocBook "title" element. @@ -2415,7 +2389,7 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``title`` element contains the `common attributes`_ (id_, name_, dupname_, source_, and class_), plus refid_ and auto_. @@ -2457,20 +2431,19 @@ a ``table`` or a ``list``, or inside another ``topic``. Details ------- -Category - `Structural Elements`_ +:Category: `Structural Elements`_ -Parents +:Parents: The following elements may contain ``topic``: document_, section_ -Children +:Children: ``topic`` elements begin with a title_ and may contain `body elements`_. -Analogies +:Analogies: ``topic`` is analogous to the DocBook "simplesect" element. -Processing +:Processing: A ``topic`` element should be set off from the rest of the document somehow, such as with indentation or a border. @@ -2483,11 +2456,11 @@ Content Model (title_?, (`%body.elements;`_)+) -Attributes +:Attributes: The ``topic`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%structure.model;`_ parameter entity directly includes ``topic``. @@ -2529,20 +2502,19 @@ See `Representation of Horizontal Rules`_ below. Details ------- -Category - `Structural Subelements`_ +:Category: `Structural Subelements`_ -Parents +:Parents: The following elements may contain ``transition``: document_, section_ -Children +:Children: ``transition`` is an empty element and has no children. -Analogies +:Analogies: ``transition`` is analogous to the HTML "hr" element. -Processing +:Processing: The ``transition`` element is typically rendered as vertical whitespace (more than that separating paragraphs), with or without a horizontal line or row of asterisks. In novels, transitions are @@ -2559,11 +2531,11 @@ Content Model The ``transition`` element has no content; it is a "point element". -Attributes +:Attributes: The ``transition`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%structure.model;`_ parameter entity directly includes ``transition``. @@ -2599,21 +2571,20 @@ It can be used alone or in conjunction with revision_. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``version``. -Children +:Children: ``version`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``version`` may be considered analogous to the DocBook "revision", "revnumber", or "biblioid" elements. -Processing +:Processing: Sometimes used with the RCS/CVS keyword "Revision". See docinfo_ and revision_. @@ -2625,11 +2596,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``version`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``version``. -- cgit v1.2.1 From a017e088a148600bf4ec7e20e0dd8967ea9837d0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 19 Sep 2002 00:47:24 +0000 Subject: simplified data field lists git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@694 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 117 +++++++++++++++++++------------------------- 1 file changed, 51 insertions(+), 66 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index c78e572c2..cb22c621b 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -40,10 +40,9 @@ Specification`_ for syntax details. "important", "note", "tip", "warning" :DTD Elements: attention, caution, danger, error, hint, important, note, tip, warning -:Directive Block: - :Arguments: None. - :Options: None. - :Content: Interpreted as body elements. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Interpreted as body elements. Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. @@ -100,10 +99,9 @@ Image :Directive Type: "image" :DTD Element: image -:Directive Block: - :Arguments: One, required (image URI). - :Options: Possible. - :Content: None. +:Directive Arguments: One, required (image URI). +:Directive Options: Possible. +:Directive Content: None. An "image" is a simple picture:: @@ -158,11 +156,10 @@ Figure :Directive Type: "figure" :DTD Elements: figure, image, caption, legend -:Directive Block: - - :Arguments: One, required (image URI). - :Options: Possible. - :Content: Interpreted as the figure caption and an optional legend. +:Directive Arguments: One, required (image URI). +:Directive Options: Possible. +:Directive Content: Interpreted as the figure caption and an optional + legend. A "figure" consists of image_ data (including `image options`_), an optional caption (a single paragraph), and an optional legend @@ -202,10 +199,9 @@ Topic :Directive Type: "topic" :DTD Element: topic -:Directive Block: - :Arguments: None. - :Options: None. - :Content: Interpreted as the topic title and body. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Interpreted as the topic title and body. A topic is like a block quote with a title, or a self-contained section with no subsections. Use the "topic" directive to indicate a @@ -229,10 +225,9 @@ Line Block :Directive Type: "line-block" :DTD Element: line_block -:Directive Block: - :Arguments: None. - :Options: None. - :Content: Becomes the body of the line block. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Becomes the body of the line block. The "line-block" directive constructs an element where whitespace (including linebreaks) is significant and inline markup is supported. @@ -261,10 +256,9 @@ Parsed Literal Block :Directive Type: "literal-block" :DTD Element: literal_block -:Directive Block: - :Arguments: None. - :Options: None. - :Content: Becomes the body of the literal block. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Becomes the body of the literal block. Unlike an ordinary literal block, the "parsed-literal" directive constructs a literal block where the text is parsed for inline markup. @@ -278,11 +272,11 @@ Backslash-escapes may be necessary in places. For example, all the element names in this content model are links:: .. parsed-literal:: - + ((title_, - subtitle_?)?, - docinfo_?, - decoration_?, + subtitle_?)?, + docinfo_?, + decoration_?, `%structure.model;`_) @@ -295,10 +289,9 @@ Table of Contents :Directive Type: "contents" :DTD Elements: pending, topic -:Directive Block: - :Arguments: One, optional: title. - :Options: Possible. - :Content: None. +:Directive Arguments: One, optional: title. +:Directive Options: Possible. +:Directive Content: None. The "contents" directive inserts a table of contents (TOC) in two passes: initial parse and transform. During the initial parse, a @@ -352,10 +345,9 @@ Automatic Section Numbering :Directive Type: "sectnum" or "section-autonumbering" (synonyms) :DTD Elements: pending, generated -:Directive Block: - :Arguments: None. - :Options: Possible. - :Content: None. +:Directive Arguments: None. +:Directive Options: Possible. +:Directive Content: None. The "sectnum" (or "section-autonumbering") directive automatically numbers sections and subsections in a document. Section numbers are @@ -387,10 +379,9 @@ Target Footnotes :Directive Type: "target-notes" :DTD Elements: pending, footnote, footnote_reference -:Directive Block: - :Arguments: None. - :Options: None. - :Content: None. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: None. The "target-notes" directive creates a footnote for each external target in the text, and corresponding footnote references after each @@ -406,10 +397,9 @@ Footnotes :Directive Type: "footnotes" :DTD Elements: pending, topic -:Directive Block: - :Arguments: None? - :Options: Possible? - :Content: None. +:Directive Arguments: None? +:Directive Options: Possible? +:Directive Content: None. @@@ @@ -421,10 +411,9 @@ Citations :Directive Type: "citations" :DTD Elements: pending, topic -:Directive Block: - :Arguments: None? - :Options: Possible? - :Content: None. +:Directive Arguments: None? +:Directive Options: Possible? +:Directive Content: None. @@@ @@ -438,10 +427,9 @@ Meta :Directive Type: "meta" :DTD Element: meta (non-standard) -:Directive Block: - :Arguments: None. - :Options: None. - :Content: Must contain a flat field list. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Must contain 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 @@ -509,10 +497,9 @@ Including an External Fragment :Directive Type: "include" :DTD Elements: depend on data being included -:Directive Block: - :Arguments: One, required (path to include file). - :Options: Possible. - :Content: None. +:Directive Arguments: One, required (path to include file). +:Directive Options: Possible. +:Directive Content: None. The "include" directive reads a reStructuredText-formatted text file and parses it in the current document's context at the point of the @@ -534,11 +521,10 @@ Raw Data Pass-Through :Directive Type: "raw" :DTD Element: pending -:Directive Block: - :Arguments: One, required (output format type). - :Options: Possible - :Content: Stored verbatim, uninterpreted. None (empty) if a - "file" or "url" option given. +:Directive Arguments: One, required (output format type). +:Directive Options: Possible +:Directive Content: Stored verbatim, uninterpreted. None (empty) if a + "file" or "url" option given. The "raw" directive indicates non-reStructuredText data that is to be passed untouched to the Writer. The name of the output format is @@ -580,10 +566,9 @@ Restructuredtext-Test-Directive :Directive Type: "restructuredtext-test-directive" :DTD Element: system_warning -:Directive Block: - :Arguments: None. - :Options: None. - :Content: Interpreted as a literal block. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: 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 -- cgit v1.2.1 From 9af81413d14f2f8e27b1ce1230c7f59872b40c39 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 20 Sep 2002 02:49:37 +0000 Subject: spellchecked & updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@698 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 46673010b..0538d23c9 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -54,7 +54,7 @@ elements, and may be structured into sections. Sections_ are indicated through title style (underlines & optional overlines). Sections contain body elements and/or subsections. Some body elements contain further elements, such as lists containing list items, which -in turn may contain paragraphs and other body elemens. Others, such +in turn may contain paragraphs and other body elements. Others, such as paragraphs, contain text and `inline markup`_ elements. Here are examples of `body elements`_: @@ -325,7 +325,7 @@ the field names):: :Hello: This field has a short field name, so aligning the field body with the first line is feasible. - :Number-of-African-swallows-requried-to-carry-a-coconut: It would + :Number-of-African-swallows-required-to-carry-a-coconut: It would be very difficult to align the field body with the left edge of the first line. It may even be preferable not to begin the body on the same line as the marker. @@ -370,11 +370,11 @@ Reference Names =============== Simple reference names are single words consisting of alphanumerics -plus internal hypens, underscores, and periods; no whitespace or other -characters are allowed. Footnote labels (Footnotes_ & `Footnote -References`_), citation labels (Citations_ & `Citation References`_), -`interpreted text`_ roles, and some `hyperlink references`_ use the -simple reference name syntax. +plus isolated (no two adjacent) internal hyphens, underscores, and +periods; no whitespace or other characters are allowed. Footnote +labels (Footnotes_ & `Footnote References`_), citation labels +(Citations_ & `Citation References`_), `interpreted text`_ roles, and +some `hyperlink references`_ use the simple reference name syntax. Reference names using punctuation or whose names are phrases (two or more space-separated words) are called "phrase-references". @@ -566,7 +566,7 @@ enforced, nor do differences in transition markers accomplish anything. It is recommended that a single consistent style be used. The processing system is free to render transitions in output in any -way it likes. For example, horizontal rules (``<HR>``) in HTML output +way it likes. For example, horizontal rules (``<hr>``) in HTML output would be an obvious choice. @@ -633,7 +633,7 @@ Here are examples of **incorrectly** formatted bullet lists:: (Warning) - The following line appears to be a new sublist, but it is not: - - This is a paragraph contination, not a sublist (since there's + - This is a paragraph continuation, not a sublist (since there's no blank line). This line is also incorrectly indented. - Warnings may be issued by the implementation. @@ -919,7 +919,7 @@ The RCS keyword processing only kicks in when all of these conditions hold: 1. The field list is in bibliographic context (first non-comment - contstruct in the document, after a document title if there is + construct in the document, after a document title if there is one). 2. The field name is a recognized bibliographic field name. @@ -949,7 +949,7 @@ descriptions, documenting a program's options. For example:: This is the second. Blank lines may be omitted between options (as above) or left in (as here and below). - --very-long-option A VMS-syle option. Note the adjustment for + --very-long-option A VMS-style option. Note the adjustment for the required two spaces. --an-even-longer-option @@ -1628,7 +1628,7 @@ indirect. After processing into HTML, the hyperlink might be expressed as:: - See the <A HREF="http://www.python.org">Python</A> home page + See the <a href="http://www.python.org">Python</a> home page for info. An external hyperlink's URI may begin on the same line as the @@ -1805,8 +1805,8 @@ directive code. There are three logical parts to the directive block: Individual directives can employ any combination of these parts. Directive arguments can be filesystem paths, URLs, title text, etc. Directive options are indicated using `field lists`_; the field names -and contents are directive-specific. Argumens and options must form a -contiguous block beginning on the first or second line of the +and contents are directive-specific. Arguments and options must form +a contiguous block beginning on the first or second line of the directive; a blank line indicates the beginning of the directive content block. If either arguments and/or options are employed by the directive, a blank line must separate them from the directive content. @@ -1982,7 +1982,7 @@ Styles [#]_ Interpreted text is unsuitable for this purpose because the set of style names cannot be predefined - it is the domain of the content author, not the author of the parser and output - formatter - and there is no way to associate a stylename + formatter - and there is no way to associate a style name argument with an interpreted text style role. Also, it may be desirable to use the same mechanism for styling blocks:: @@ -2189,7 +2189,7 @@ markup start-strings: - vertical bars: | || etc. It may be desirable to use inline literals for some of these anyhow, -especially if they represent code snippets. It's a judgement call. +especially if they represent code snippets. It's a judgment call. These cases *do* require either literal-quoting or escaping to avoid misinterpretation:: @@ -2293,7 +2293,7 @@ references`_, we can add "index entry", "acronym", "class", "red", A role marker consists of a colon, the role name, and another colon. A role name is a single word consisting of alphanumerics plus internal -hypens, underscores, and periods; no whitespace or other characters +hyphens, underscores, and periods; no whitespace or other characters are allowed. @@ -2470,7 +2470,7 @@ as the link's text. For example:: would be marked up in HTML as:: - See <A HREF="http://www.python.org">http://www.python.org</A> for + See <a href="http://www.python.org">http://www.python.org</a> for info. Two forms of URI are recognized: @@ -2507,7 +2507,7 @@ Two forms of URI are recognized: recognize any absolute URI, as defined in RFC2396_ and RFC2732_. 2. Standalone email addresses, which are treated as if they were - ablsolute URIs with a "mailto:" scheme. Example:: + absolute URIs with a "mailto:" scheme. Example:: someone@somewhere.com -- cgit v1.2.1 From 794964358a1bb001f592d7e7c8b77559fe9ad24f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 24 Sep 2002 02:21:48 +0000 Subject: Changed public identifier to docutils.sf.net. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@715 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 19094bbf2..97efa9477 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -14,9 +14,9 @@ Docutils project can be found at http://docutils.sourceforge.net/. The latest version of this DTD is available from http://docutils.sourceforge.net/spec/docutils.dtd. -The proposed formal public identifier for this DTD is:: +The formal public identifier for this DTD is:: - +//IDN python.org//DTD Docutils Generic//EN//XML + +//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML --> <!-- -- cgit v1.2.1 From 40e2dd54976161f6884757dfc13325bee259f686 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 24 Sep 2002 02:22:07 +0000 Subject: fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@716 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index c490e5044..b7901b370 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -108,9 +108,7 @@ Category members: document_, section_, topic_ Structural Subelements ---------------------- -Structural subelements are child elements of structural elements, but -contain no further structure of their own (except for text and inline -elements). +Structural subelements are child elements of structural elements. Category members: title_, subtitle_, docinfo_, decoration_, transition_ -- cgit v1.2.1 From e1d2f1face2a58f022aa0bb0e9b3b6fb11adf900 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 24 Sep 2002 02:24:06 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@717 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- docs/ref/rst/introduction.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index cb22c621b..242c01564 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -254,7 +254,7 @@ example, here's a classic:: Parsed Literal Block ==================== -:Directive Type: "literal-block" +:Directive Type: "parsed-literal" :DTD Element: literal_block :Directive Arguments: None. :Directive Options: None. diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index 0ec112a47..5ff6d2878 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -202,7 +202,7 @@ motivations (the "itches" I aim to "scratch") are as follows: a markup language specification and a reference parser implementation, but it does not aspire to be the entire system. I don't want reStructuredText or a hypothetical Python documentation - processor to die stillborn because of overambition. + processor to die stillborn because of over-ambition. - Most of all, I want to help ease the documentation chore, the bane of many a programmer. -- cgit v1.2.1 From 456d58fa344070e7b3d782ecd44ea5f4c793eb2c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 25 Sep 2002 03:02:00 +0000 Subject: fixed typos git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@718 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 97efa9477..41eb5d791 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -430,7 +430,7 @@ either the string separating it from the `option` (typically either <!ELEMENT pending EMPTY> <!ATTLIST pending %basic.atts;> -<!ELEMENT figure (image, ((caption, legend?) | legend) > +<!ELEMENT figure (image, ((caption, legend?) | legend)) > <!ATTLIST figure %basic.atts;> <!-- Also an inline element. --> @@ -439,9 +439,9 @@ either the string separating it from the `option` (typically either %basic.atts; uri CDATA #REQUIRED alt CDATA #IMPLIED - height &number; #IMPLIED - width &number; #IMPLIED - scale &number; #IMPLIED> + height %number; #IMPLIED + width %number; #IMPLIED + scale %number; #IMPLIED> <!ELEMENT caption %text.model;> <!ATTLIST caption %basic.atts;> @@ -459,8 +459,8 @@ Table elements: table, tgroup, colspec, thead, tbody, row, entry. <!ATTLIST system_message %basic.atts; %backrefs.att; - level &number; #IMPLIED - line &number; #IMPLIED + level %number; #IMPLIED + line %number; #IMPLIED type NMTOKEN #IMPLIED> <!-- Used to pass raw data through the system. Also inline. --> -- cgit v1.2.1 From 2aec785bc1ae304360badbf509f5b3a8ef786fb5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 2 Oct 2002 03:22:29 +0000 Subject: Added "replace" directive. Updated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@748 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 77 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 58 insertions(+), 19 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 242c01564..6f6b1ca88 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -22,8 +22,9 @@ space), followed by the directive type and two colons (collectively, the "directive marker"). The directive block begins immediately after the directive marker, and includes all subsequent indented lines. The directive block is divided into arguments, options (a field list), and -content. See the Directives_ section in the `reStructuredText Markup -Specification`_ for syntax details. +content (in that order), any of which may appear. See the Directives_ +section in the `reStructuredText Markup Specification`_ for syntax +details. .. _Directives: ./reStructuredText.html#directives .. _reStructuredText Markup Specification: ./reStructuredText.html @@ -199,9 +200,9 @@ Topic :Directive Type: "topic" :DTD Element: topic -:Directive Arguments: None. +:Directive Arguments: 1, required (topic title). :Directive Options: None. -:Directive Content: Interpreted as the topic title and body. +:Directive Content: Interpreted as the topic body. A topic is like a block quote with a title, or a self-contained section with no subsections. Use the "topic" directive to indicate a @@ -209,9 +210,9 @@ self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or transition may occur. Body elements (including topics) may not contain nested topics. -The first line of the directive content block is interpreted as the -topic title; the second line must be blank. All subsequent lines make -up the topic body, interpreted as body elements. For example:: +The directive's sole argument is interpreted as the topic title; the +next line must be blank. All subsequent lines make up the topic body, +interpreted as body elements. For example:: topic:: Topic Title @@ -331,7 +332,7 @@ The following options are recognized: ``depth`` : integer The number of section levels that are collected in the table of contents. The default is unlimited depth. -``local`` : empty +``local`` : flag (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. @@ -490,10 +491,8 @@ Non-standard element: imagemap. Miscellaneous --------------- -Including an External Fragment -============================== - -**NOT IMPLEMENTED YET** +Including an External Document Fragment +======================================= :Directive Type: "include" :DTD Elements: depend on data being included @@ -505,11 +504,23 @@ The "include" directive reads a reStructuredText-formatted text file and parses it in the current document's context at the point of the directive. For example:: + This first example will be parsed at the document level, and can + thus contain any construct, including section headers. + .. include:: inclusion.txt + This second will be parsed in a block quote context. + Therefore it may only contain body elements. It may not + contain section headers. + + .. include:: inclusion.txt + +If an included document fragment contains section structure, the title +adornments must match those of the master document. + The following options are recognized: -``literal`` : empty +``literal`` : flag (empty) The entire included text is inserted into the document as a single literal block (useful for program listings). @@ -517,12 +528,10 @@ The following options are recognized: Raw Data Pass-Through ===================== -**NOT IMPLEMENTED YET** - :Directive Type: "raw" :DTD Element: pending :Directive Arguments: One, required (output format type). -:Directive Options: Possible +:Directive Options: Possible. :Directive Content: Stored verbatim, uninterpreted. None (empty) if a "file" or "url" option given. @@ -547,8 +556,9 @@ output stream:: \documentclass[twocolumn]{article} -Raw data can also be read from an external file, specified in an -option. In this case, the content block must be empty. For example:: +Raw data can also be read from an external file, specified in a +directive option. In this case, the content block must be empty. For +example:: .. raw:: html :file: inclusion.html @@ -556,11 +566,40 @@ option. In this case, the content block must be empty. For example:: The following options are recognized: ``file`` : string - The filesystem path of a raw data file to be included. + The local filesystem path of a raw data file to be included. ``url`` : string An Internet URL reference to a raw data file to be included. +Replacement Text +================ + +:Directive Type: "replace" +:DTD Element: pending +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: A single paragraph; may contain inline markup. + +The "replace" directive is used to indicate replacement text for a +substitution reference. It may be used within substitution +definitions only. For example, this directive can be used to expand +abbreviations:: + + .. |reST| replace:: reStructuredText + + Yes, |reST| is a long word, so I can't blame anyone for wanting to + abbreviate it. + +As reStructuredText doesn't support nested inline markup, the only way +to create a reference with styled text is to use substitutions with +the "replace" directive:: + + I recommend you try |Python|_. + + .. |Python| replace:: Python, *the* best language around + .. _Python: http://www.python.org/ + + Restructuredtext-Test-Directive =============================== -- cgit v1.2.1 From d3256371e06859fd101eacc5e35f21364b74b651 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Oct 2002 01:38:26 +0000 Subject: Added field_list, field, field_name, field_body elements. Changed "Analogies" to "Analogues". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@754 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 270 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 236 insertions(+), 34 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index b7901b370..a67b00db4 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -229,7 +229,7 @@ following subsections: - Children: A list of elements which may occur within the element. - - Analogies: Describes analogous elements in well-known document + - Analogues: Describes analogous elements in well-known document models such as HTML_ or DocBook_. Lists similarities and differences. @@ -299,7 +299,7 @@ Details :Children: ``address`` elements contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``address`` is analogous to the DocBook "address" element. :Processing: @@ -375,7 +375,7 @@ Details :Children: ``author`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``author`` is analogous to the DocBook "author" element. :Processing: @@ -440,7 +440,7 @@ Details ``authors`` elements may contain the following elements: author_, organization_, address_, contact_ -:Analogies: +:Analogues: ``authors`` is analogous to the DocBook "authors" element. :Processing: @@ -521,7 +521,7 @@ Details :Children: ``bullet_list`` elements contain one or more list_item_ elements. -:Analogies: +:Analogues: ``bullet_list`` is analogous to the HTML "ul" element and to the DocBook "itemizedlist" element. HTML's "ul" is short for "unordered list", which we consider to be a misnomer. "Unordered" @@ -624,7 +624,7 @@ Details :Children: ``classifier`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``classifier`` has no direct analogues in common DTDs. It can be emulated with primitives or type effects. @@ -707,7 +707,7 @@ Details ``contact`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``contact`` is analogous to the DocBook "email" element. The HTML "address" element serves a similar purpose. @@ -773,7 +773,7 @@ Details ``copyright`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``copyright`` is analogous to the DocBook "copyright" element. :Processing: @@ -843,7 +843,7 @@ Details :Children: ``date`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``date`` is analogous to the DocBook "date" element. :Processing: @@ -910,7 +910,7 @@ Details :Children: ``decoration`` elements may contain `decorative elements`_. -:Analogies: +:Analogues: There are no direct analogies to ``decoration`` in HTML or in DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. @@ -971,7 +971,7 @@ Details :Children: ``definition`` elements may contain `body elements`_. -:Analogies: +:Analogues: ``definition`` is analogous to the HTML "dd" element and to the DocBook "listitem" element (inside a "variablelistentry" element). @@ -1021,7 +1021,7 @@ Details ``definition_list`` elements contain one or more definition_list_item_ elements. -:Analogies: +:Analogues: ``definition_list`` is analogous to the HTML "dl" element and to the DocBook "variablelist" element. @@ -1100,7 +1100,7 @@ Details ``definition_list_item`` elements each contain a single term_, an optional classifier_, and a definition_. -:Analogies: +:Analogues: ``definition_list_item`` is analogous to the DocBook "variablelistentry" element. @@ -1189,7 +1189,7 @@ Details :Children: ``docinfo`` elements contain `bibliographic elements`_. -:Analogies: +:Analogues: ``docinfo`` is analogous to DocBook "info" elements ("bookinfo" etc.). There are no directly analogous HTML elements; the "meta" element carries some of the same information, albeit invisibly. @@ -1301,7 +1301,7 @@ Details ``document`` elements may contain `structural subelements`_, `structural elements`_, and `body elements`_. -:Analogies: +:Analogues: ``document`` is analogous to the HTML "html" element and to several DocBook elements such as "book". @@ -1396,7 +1396,7 @@ Details ``enumerated_list`` elements contain one or more list_item_ elements. -:Analogies: +:Analogues: ``enumerated_list`` is analogous to the HTML "ol" element and to the DocBook "orderedlist" element. @@ -1489,25 +1489,227 @@ See list_item_ for another example. ``field`` ========= -`To be completed`_. +The ``field`` element contains a pair of field_name_ and field_body_ +elements. + + +Details +------- + +:Category: `Body Subelements`_ + +:Parents: + The following elements may contain ``field``: docinfo_, + field_list_ + +:Children: + Each ``field`` element contains one field_name_ and one + field_body_ element. + +:Analogues: + ``field`` has no direct analogues in common DTDs. + +:Processing: See field_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (field_name_, field_body_) + +:Attributes: + The ``field`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``field``. + + +Examples +-------- + +See the examples for the field_list_ and docinfo_ elements. ``field_body`` ============== -`To be completed`_. +The ``field_body`` element contains body elements. It is analogous to +a database field's data. + + +Details +------- + +:Category: `Body Subelements`_ + +:Parents: + Only the field_ element contains ``field_body``. + +:Children: + ``field_body`` elements may contain `body elements`_. + +:Analogues: + ``field_body`` has no direct analogues in common DTDs. + +:Processing: See field_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)* + +:Attributes: + The ``field_body`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the field_list_ and docinfo_ elements. ``field_list`` ============== -`To be completed`_. +The ``field_list`` element contains two-column table-like structures +resembling database records (label & data pairs). Field lists are +often meant for further processing. In reStructuredText, field lists +are used to represent bibliographic fields (contents of the docinfo_ +element) and directive options. + + +Details +------- + +:Category: `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``field_list``. + +:Children: + ``field_list`` elements contain one or more field_ elements. + +:Analogues: + ``field_list`` has no direct analogues in common DTDs. It can be + emulated with primitives such as tables. + +:Processing: + A ``field_list`` is typically rendered as a two-column list, where + the first column contains "labels" (usually with a colon suffix). + However, field lists are often used for extension syntax or + special processing. Such structures do not survive as field lists + to be rendered. + + +Content Model +------------- + +.. parsed-literal:: + + (field_+) + +:Attributes: + The ``field_list`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``field_list``. The `%structure.model;`_ parameter entity + indirectly includes ``field_list``. + + +Examples +-------- + +reStructuredText source:: + + :Author: Me + :Version: 1 + :Date: 2001-08-11 + :Parameter i: integer + +Pseudo-XML_ fragment from simple parsing:: + + <field_list> + <field> + <field_name> + Author + <field_body> + <paragraph> + Me + <field> + <field_name> + Version + <field_body> + <paragraph> + 1 + <field> + <field_name> + Date + <field_body> + <paragraph> + 2001-08-11 + <field> + <field_name> + Parameter i + <field_body> + <paragraph> + integer + +Complete pseudo-XML_ result after parsing and applying transforms:: ``field_name`` ============== -`To be completed`_. +The ``field_name`` element contains text data only. It is analogous +to a database field's name. + + +Details +------- + +:Category: `Body Subelements`_ + +:Parents: + Only the field_ element contains ``field_name``. + +:Children: + ``field_name`` elements have no children. They may contain text + data only. + +:Analogues: + ``field_name`` has no direct analogues in common DTDs. + +:Processing: See field_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (#PCDATA) + +:Attributes: + The ``field_name`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the field_list_ and docinfo_ elements. ``figure`` @@ -1536,7 +1738,7 @@ Details :Children: ``footer`` elements may contain `body elements`_. -:Analogies: +:Analogues: There are no direct analogies to ``footer`` in HTML or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. @@ -1611,7 +1813,7 @@ Details :Children: ``header`` elements may contain `body elements`_. -:Analogies: +:Analogues: There are no direct analogies to ``header`` in HTML or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. @@ -1696,7 +1898,7 @@ Details :Children: ``list_item`` elements may contain `body elements`_. -:Analogies: +:Analogues: ``list_item`` is analogous to the HTML "li" element and to the DocBook "listitem" element. @@ -1821,7 +2023,7 @@ Details ``organization`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``organization`` is analogous to the DocBook "orgname", "corpname", or "publishername" elements. @@ -1889,7 +2091,7 @@ Details ``paragraph`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``paragraph`` is analogous to the HTML "p" element and to the DocBook "para" elements. @@ -1967,7 +2169,7 @@ Details ``revision`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``revision`` is analogous to but simpler than the DocBook "revision" element. It closely matches the DocBook "revnumber" element, but in a simpler context. @@ -2047,7 +2249,7 @@ Details ``section`` elements begin with a title_, and may contain `body elements`_ and transition_ and topic_ elements. -:Analogies: +:Analogues: ``section`` is analogous to DocBook recursive "section" elements, and to HTML "div" elements combined with "h1" etc. title elements. @@ -2137,7 +2339,7 @@ Details :Children: ``status`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``status`` is analogous to the DocBook "status" element. :Processing: @@ -2219,7 +2421,7 @@ Details ``subtitle`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``subtitle`` is analogous to HTML header elements ("h2" etc.) and to the DocBook "subtitle" element. @@ -2311,7 +2513,7 @@ Details :Children: ``term`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``term`` is analogous to the HTML "dt" element and to the DocBook "term" element. @@ -2375,7 +2577,7 @@ Details :Children: ``title`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``title`` is analogous to HTML "title" and header ("h1" etc.) elements, and to the DocBook "title" element. @@ -2438,7 +2640,7 @@ Details ``topic`` elements begin with a title_ and may contain `body elements`_. -:Analogies: +:Analogues: ``topic`` is analogous to the DocBook "simplesect" element. :Processing: @@ -2509,7 +2711,7 @@ Details :Children: ``transition`` is an empty element and has no children. -:Analogies: +:Analogues: ``transition`` is analogous to the HTML "hr" element. :Processing: @@ -2578,7 +2780,7 @@ Details ``version`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``version`` may be considered analogous to the DocBook "revision", "revnumber", or "biblioid" elements. -- cgit v1.2.1 From 96b04fd6263cf2a87810a3fdeec2ee023c2392f5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Oct 2002 01:56:16 +0000 Subject: fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@756 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index a67b00db4..75f57ef1c 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1666,8 +1666,6 @@ Pseudo-XML_ fragment from simple parsing:: <paragraph> integer -Complete pseudo-XML_ result after parsing and applying transforms:: - ``field_name`` ============== -- cgit v1.2.1 From 35448a37349d3788f2daafb762fd4e730d184b00 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Oct 2002 22:20:13 +0000 Subject: Clarified term/classifier delimiter & inline markup ambiguity (definition lists). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@759 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 0538d23c9..88d7a4917 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -733,13 +733,13 @@ definition. Each definition list item contains a term, an optional classifier, and a definition. A term is a simple one-line word or phrase. An -optional classifier may follow the term on the same line, after " : " -(space, colon, space). A definition is a block indented relative to -the term, and may contain multiple paragraphs and other body elements. -There may be no blank line between a term and a definition (this -distinguishes definition lists from `block quotes`_). Blank lines are -required before the first and after the last definition list item, but -are optional in-between. For example:: +optional classifier may follow the term on the same line, after an +inline " : " (space, colon, space). A definition is a block indented +relative to the term, and may contain multiple paragraphs and other +body elements. There may be no blank line between a term line and a +definition block (this distinguishes definition lists from `block +quotes`_). Blank lines are required before the first and after the +last definition list item, but are optional in-between. For example:: term 1 Definition 1. @@ -752,6 +752,10 @@ are optional in-between. For example:: term 3 : classifier Definition 3. +Inline markup is parsed in the term line before the term/classifier +delimiter (" : ") is recognized. The delimiter will only be +recognized if it appears outside of any inline markup. + A definition list may be used in various ways, including: - As a dictionary or glossary. The term is the word itself, a -- cgit v1.2.1 From 54fa9c50bab333a45d75a6a72d5d82a4faf083f4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Oct 2002 22:25:42 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@763 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 41eb5d791..f55f6bcea 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -340,10 +340,10 @@ http://www.oasis-open.org/html/tm9901.htm). <!ATTLIST option_string %basic.atts;> <!-- -`delimiter` contains the string preceding the `option_argument`: -either the string separating it from the `option` (typically either -"=" or " ") or the string between option arguments (typically either -"," or " "). +`delimiter` contains the text preceding the `option_argument`: either +the text separating it from the `option_string` (typically either "=" +or " ") or the text between option arguments (typically either "," or +" "). --> <!ELEMENT option_argument (#PCDATA)> <!ATTLIST option_argument -- cgit v1.2.1 From 8bc9254160b3f3ff159192bfe612168fb89dca6d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 11 Oct 2002 01:40:35 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@787 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 6 +++++- docs/ref/rst/restructuredtext.txt | 10 ++++++---- 2 files changed, 11 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 6f6b1ca88..495fec567 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -132,15 +132,19 @@ The following options are recognized: 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. + ``align`` : "top", "middle", "bottom", "left", "center", or "right" The alignment of the image, equivalent to the HTML ``<img>`` tag's "align" attribute. The values "top", "middle", and "bottom" @@ -158,7 +162,7 @@ Figure :Directive Type: "figure" :DTD Elements: figure, image, caption, legend :Directive Arguments: One, required (image URI). -:Directive Options: Possible. +:Directive Options: Possible; same as those of the `image`_ directive. :Directive Content: Interpreted as the figure caption and an optional legend. diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 88d7a4917..642aace28 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -433,9 +433,9 @@ rearranging the document fragment into a complete document with a title and possibly other metadata elements (author, date, etc.; see `Bibliographic Fields`_). -Specifically, there is no way to specify a document title and subtitle -explicitly in reStructuredText. Instead, a lone top-level section -title (see Sections_ below) can be treated as the document +Specifically, there is no way to indicate a document title and +subtitle explicitly in reStructuredText. Instead, a lone top-level +section title (see Sections_ below) can be treated as the document title. Similarly, a lone second-level section title immediately after the "document title" can become the document subtitle. See the `DocTitle transform`_ for details. @@ -1483,7 +1483,9 @@ may be the only character in the label. For example:: .. [*] This is the footnote. A transform will insert symbols as labels into corresponding footnotes -and footnote references. +and footnote references. The number of references must be equal to +the number of footnotes. One symbol footnote cannot have multiple +references. The standard Docutils system uses the following symbols for footnote marks [#]_: -- cgit v1.2.1 From a91984c003e1f1ddff4cb4a6ff885381b0d6c155 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 17 Oct 2002 03:25:29 +0000 Subject: Removed "Representation of Horizontal Rules" to spec/rst/alternatives.txt. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@815 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 100 --------------------------------------------------- 1 file changed, 100 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 75f57ef1c..a0eeba191 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -3408,106 +3408,6 @@ strong_, substitution_definition_, substitution_reference_, subtitle_, target_, term_, title_, version_ ----------------------- - Miscellaneous Topics ----------------------- - -Representation of Horizontal Rules -================================== - -Having added the "horizontal rule" construct to the `reStructuredText -Markup Specification`_, a decision had to be made as to how to reflect -the construct in the implementation of the document tree. Given this -source:: - - Document - ======== - - Paragraph 1 - - -------- - - Paragraph 2 - -The horizontal rule indicates a "transition" (in prose terms) or the -start of a new "division". Before implementation, the parsed document -tree would be:: - - <document> - <section name="document"> - <title> - Document - <paragraph> - Paragraph 1 - -------- <--- error here - <paragraph> - Paragraph 2 - -There are several possibilities for the implementation: - -1. Implement horizontal rules as "divisions" or segments. A - "division" is a title-less, non-hierarchical section. The first - try at an implementation looked like this:: - - <document> - <section name="document"> - <title> - Document - <paragraph> - Paragraph 1 - <division> - <paragraph> - Paragraph 2 - - But the two paragraphs are really at the same level; they shouldn't - appear to be at different levels. There's really an invisible - "first division". The horizontal rule splits the document body - into two segments, which should be treated uniformly. - -2. Treating "divisions" uniformly brings us to the second - possibility:: - - <document> - <section name="document"> - <title> - Document - <division> - <paragraph> - Paragraph 1 - <division> - <paragraph> - Paragraph 2 - - With this change, documents and sections will directly contain - divisions and sections, but not body elements. Only divisions will - directly contain body elements. Even without a horizontal rule - anywhere, the body elements of a document or section would be - contained within a division element. This makes the document tree - deeper. This is similar to the way HTML_ treats document contents: - grouped within a ``<body>`` element. - -3. Implement them as "transitions", empty elements:: - - <document> - <section name="document"> - <title> - Document - <paragraph> - Paragraph 1 - <transition> - <paragraph> - Paragraph 2 - - A transition would be a "point element", not containing anything, - only identifying a point within the document structure. This keeps - the document tree flatter, but the idea of a "point element" like - "transition" smells bad. A transition isn't a thing itself, it's - the space between two divisions. However, transitions are a - practical solution. - -Solution 3 was chosen for incorporation into the document tree model. - - .. Local Variables: -- cgit v1.2.1 From 904a224b8e6591a78892cefe18463d2a875f6167 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 17 Oct 2002 03:32:57 +0000 Subject: fixed references git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@818 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index a0eeba191..5332ab96e 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -2694,7 +2694,11 @@ elements, dividing a section into untitled divisions. A transition may not begin or end a section or document, nor may two transitions be immediately adjacent. -See `Representation of Horizontal Rules`_ below. +See `Doctree Representation of Transitions`__ in `A Record of +reStructuredText Syntax Alternatives`__. + +__ rst/alternatives.txt#doctree-representation-of-transitions +__ rst/alternatives.txt Details -- cgit v1.2.1 From f8c63e4e07ebdcf7c41888c4f9f3ffe4e701a7a3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 24 Oct 2002 00:54:03 +0000 Subject: Added to project. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@855 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 113 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/ref/transforms.txt (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt new file mode 100644 index 000000000..92e85179c --- /dev/null +++ b/docs/ref/transforms.txt @@ -0,0 +1,113 @@ +===================== + Docutils Transforms +===================== + +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ +:Copyright: This document has been placed in the public domain. + + +.. contents:: + + +For background about transforms and the Transformer object, see `PEP +258`_. + +.. _PEP 258: pep-0258.html#transformer + + +Transforms Listed in Priority Order +=================================== + +============================== ====================== ======== +Transform: module.Class Added By Priority +============================== ====================== ======== +references.Substitutions standalone (r) 220 + + pep (r) + +frontmatter.DocTitle standalone (r) 320 + +frontmatter.DocInfo standalone (r) 340 + +peps.Headers pep (r) 360 + +peps.Contents pep (r) 380 + +references.ChainedTargets standalone (r) 420 + + pep (r) + +references.AnonymousHyperlinks standalone (r) 440 + + pep (r) + +references.IndirectHyperlinks standalone (r) 460 + + pep (r) + +peps.TargetNotes pep (r) 520 + +references.TargetNotes peps.TargetNotes (t) 0 + + "target-notes" (d) 540 + +references.Footnotes standalone (r) 620 + + pep (r) + +references.ExternalTargets standalone (r) 640 + + pep (r) + +references.InternalTargets standalone (r) 660 + + pep (r) + +parts.SectNum "sectnum" (d) 710 + +parts.Contents "contents" (d) 720 + + peps.Contents (t) + +peps.PEPZero pep.Headers (t) 760 + +components.Filter "meta" (d) 780 + +universal.Decorations all Readers 820 + +universal.FinalChecks all Writers 840 + +universal.Messages all Writers 860 + +universal.TestMessages DocutilsTestSupport 890 +============================== ====================== ======== + +Legend: + +* (r): Reader +* (d): Directive +* (t): Transform + + +Transform Priority Range Categories +=================================== + +==== ==== ================================================ + Priority Category +---------- ------------------------------------------------ +From To +==== ==== ================================================ + 0 immediate execution (added by another transform) +---------- ------------------------------------------------ + 1 99 unused + 100 199 very early (non-standard) + 200 299 very early + 300 399 early + 400 699 main + 700 799 late + 800 899 very late + 900 999 very late (non-standard) +==== ==== ================================================ -- cgit v1.2.1 From a714d9a65946eaec2c775e27e24159ce65ce10a1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 24 Oct 2002 01:01:53 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@856 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 642aace28..00445956c 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1254,9 +1254,9 @@ Simple Tables Simple tables provide a compact and easy to type but limited row-oriented table representation for simple data sets. Cell contents are typically single paragraphs, although arbitrary body elements may -be represented in most cells. Simple tables allow multi-line rows and -column spans, but not row spans. See `Grid Tables`_ above for a -complete table representation. +be represented in most cells. Simple tables allow multi-line rows (in +all but the first column) and column spans, but not row spans. See +`Grid Tables`_ above for a complete table representation. Simple tables are described with horizontal borders made up of "=" and "-" characters. The equals sign ("=") is used for top and bottom -- cgit v1.2.1 From 35a1beda765cd44715a9ea7c4064d71b1abbcf1e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 24 Oct 2002 23:33:52 +0000 Subject: minor updates & fixes git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@859 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 76 ++++++++++++++++++++----------------------------- 1 file changed, 31 insertions(+), 45 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 92e85179c..a5564f042 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -21,84 +21,70 @@ For background about transforms and the Transformer object, see `PEP Transforms Listed in Priority Order =================================== -============================== ====================== ======== -Transform: module.Class Added By Priority -============================== ====================== ======== -references.Substitutions standalone (r) 220 +============================== ============================ ======== +Transform: module.Class Added By Priority +============================== ============================ ======== +references.Substitutions standalone (r), pep (r) 220 - pep (r) +frontmatter.DocTitle standalone (r) 320 -frontmatter.DocTitle standalone (r) 320 +frontmatter.DocInfo standalone (r) 340 -frontmatter.DocInfo standalone (r) 340 +peps.Headers pep (r) 360 -peps.Headers pep (r) 360 +peps.Contents pep (r) 380 -peps.Contents pep (r) 380 +references.ChainedTargets standalone (r), pep (r) 420 -references.ChainedTargets standalone (r) 420 +references.AnonymousHyperlinks standalone (r), pep (r) 440 - pep (r) +references.IndirectHyperlinks standalone (r), pep (r) 460 -references.AnonymousHyperlinks standalone (r) 440 +peps.TargetNotes pep (r) 520 - pep (r) +references.TargetNotes peps.TargetNotes (t/p) 0 -references.IndirectHyperlinks standalone (r) 460 +references.TargetNotes "target-notes" (d/p) 540 - pep (r) +references.Footnotes standalone (r), pep (r) 620 -peps.TargetNotes pep (r) 520 +references.ExternalTargets standalone (r), pep (r) 640 -references.TargetNotes peps.TargetNotes (t) 0 +references.InternalTargets standalone (r), pep (r) 660 - "target-notes" (d) 540 +parts.SectNum "sectnum" (d/p) 710 -references.Footnotes standalone (r) 620 +parts.Contents "contents" (d/p), 720 + peps.Contents (t/p) - pep (r) +peps.PEPZero pep.Headers (t/p) 760 -references.ExternalTargets standalone (r) 640 +components.Filter "meta" (d/p) 780 - pep (r) +universal.Decorations Transformer 820 -references.InternalTargets standalone (r) 660 +universal.FinalChecks Transformer 840 - pep (r) +universal.Messages Transformer 860 -parts.SectNum "sectnum" (d) 710 +universal.TestMessages DocutilsTestSupport 890 +============================== ============================ ======== -parts.Contents "contents" (d) 720 - - peps.Contents (t) - -peps.PEPZero pep.Headers (t) 760 - -components.Filter "meta" (d) 780 - -universal.Decorations all Readers 820 - -universal.FinalChecks all Writers 840 - -universal.Messages all Writers 860 - -universal.TestMessages DocutilsTestSupport 890 -============================== ====================== ======== - -Legend: +Key: * (r): Reader * (d): Directive * (t): Transform +* (/p): Via a "pending" node Transform Priority Range Categories =================================== ==== ==== ================================================ - Priority Category + Priority ---------- ------------------------------------------------ -From To +From To Category ==== ==== ================================================ 0 immediate execution (added by another transform) ---------- ------------------------------------------------ -- cgit v1.2.1 From 4c472c98049e7fc5cc8ab42ad3d041ce85e12586 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 16 Nov 2002 02:30:31 +0000 Subject: Added "Embedded URIs". Updated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@958 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 66 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 63 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 00445956c..b82b648df 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1625,18 +1625,25 @@ indirect. An inline form of internal hyperlink target is available; see `Inline Internal Targets`_. -2. _`External hyperlink targets` have an absolute or relative URI in - their link blocks. For example, take the following input:: +2. _`External hyperlink targets` have an absolute or relative URI or + email address in their link blocks. For example, take the + following input:: See the Python_ home page for info. + `Write to me`_ with your questions. + .. _Python: http://www.python.org + .. _Write to me: jdoe@example.com - After processing into HTML, the hyperlink might be expressed as:: + After processing into HTML, the hyperlinks might be expressed as:: See the <a href="http://www.python.org">Python</a> home page for info. + <a href="mailto:jdoe@example.com">Write to me</a> with your + questions. + An external hyperlink's 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 @@ -1661,6 +1668,9 @@ indirect. .. _link: underscore\_ + It is possible (although not generally recommended) to include URIs + directly within hyperlink references. See `Embedded URIs`_ below. + 3. _`Indirect hyperlink targets` have a hyperlink reference in their link blocks. In the following example, target "one" indirectly references whatever target "two" references, and target "two" @@ -2367,6 +2377,56 @@ match references to targets, but otherwise behave similarly to named hyperlinks. +Embedded URIs +````````````` + +A hyperlink reference may directly embed a target URI inline, within +angle brackets ("<...>") as follows:: + + See the `Python home page <http://www.python.org>`_ for info. + +This is exactly equivalent to:: + + See the `Python home page`_ for info. + + .. _Python home page: http://www.python.org + +The bracketed URI must be preceded by whitespace and be the last text +before the end string. With a single trailing underscore, the +reference is named and the same target URI may be referred to again. + +With two trailing underscores, the reference and target are both +anonymous, and the target cannot be referred to again. These are +"one-off" hyperlinks. For example:: + + `RFC 2396 <http://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC + 2732 <http://www.rfc-editor.org/rfc/rfc2732.txt>`__ together + define the syntax of URIs. + +Equivalent to:: + + `RFC 2396`__ and `RFC 2732`__ together define the syntax of URIs. + + __ http://www.rfc-editor.org/rfc/rfc2396.txt + __ http://www.rfc-editor.org/rfc/rfc2732.txt + +If reference text happens to end with angle-bracketed text that is +*not* a URI, the open-angle-bracket needs to be backslash-escaped. +For example, here is a reference to a title describing a tag:: + + See `HTML Element: \<a>`_ below. + +.. Caution:: + + This construct offers easy authoring and maintenance of hyperlinks + at the expense of general readability. Inline URIs, especially + long ones, inevitably interrupt the natural flow of text. For + documents meant to be read in source form, the use of independent + block-level `hyperlink targets`_ is **strongly** recommended. The + embedded URI construct is most suited to documents intended *only* + to be read in processed form. + + Inline Internal Targets ------------------------ -- cgit v1.2.1 From 52056baf6fd0350e129e9ef589e9742c2bef1fea Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 16 Nov 2002 03:05:23 +0000 Subject: Updated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@963 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index b82b648df..5f7ae8ebd 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2422,7 +2422,7 @@ For example, here is a reference to a title describing a tag:: at the expense of general readability. Inline URIs, especially long ones, inevitably interrupt the natural flow of text. For documents meant to be read in source form, the use of independent - block-level `hyperlink targets`_ is **strongly** recommended. The + block-level `hyperlink targets`_ is **strongly recommended**. The embedded URI construct is most suited to documents intended *only* to be read in processed form. -- cgit v1.2.1 From 3b5fa2b5c2df5a84234f336164a0518480b93a54 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 21 Nov 2002 02:28:47 +0000 Subject: Added ``option_list`` & children (7 elements); fixed up. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@972 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 537 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 457 insertions(+), 80 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 5332ab96e..8e27088ca 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -246,7 +246,7 @@ following subsections: - Parameter Entities: Lists the parameter entities which directly or indirectly include the element. -* Examples: reStructuredText examples are shown along with +* Examples: reStructuredText_ examples are shown along with fragments of the document trees resulting from parsing. _`Pseudo-XML` is used for the results of parsing and processing. Pseudo-XML is a representation of XML where nesting is indicated by @@ -291,7 +291,8 @@ line_block_ element: whitespace is significant, especially newlines. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: The following elements may contain ``address``: docinfo_, authors_ @@ -330,7 +331,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -367,7 +368,8 @@ The ``author`` element holds the name of the author of the document. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: The following elements may contain ``author``: docinfo_, authors_ @@ -401,7 +403,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -431,7 +433,8 @@ documents with multiple authors. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``authors``. @@ -466,7 +469,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -511,7 +514,8 @@ uniformly marked with bullets. Bullets are typically simple dingbats Details ------- -:Category: `Compound Body Elements`_ +:Category: + `Compound Body Elements`_ :Parents: All elements employing the `%body.elements;`_ or @@ -539,15 +543,15 @@ Content Model .. parsed-literal:: - (list_item_+) + (list_item_ +) :Attributes: The ``bullet_list`` element contains the `common attributes`_ (id_, name_, dupname_, source_, and class_), plus bullet_. ``bullet`` is used to record the style of bullet from the input - data. In reStructuredText, it contains one of "-", "+", or "*". - It may be ignored in processing. + data. In documents processed from reStructuredText_, it contains + one of "-", "+", or "*". It may be ignored in processing. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -558,7 +562,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: - Item 1, paragraph 1. @@ -616,7 +620,8 @@ used to indicate the type of a variable. Details ------- -:Category: `Body Subelements`_ (simple) +:Category: + `Body Subelements`_ (simple) :Parents: Only the definition_list_item_ element contains ``classifier``. @@ -647,7 +652,7 @@ Content Model Examples -------- -Here is a hypothetical data dictionary. reStructuredText source:: +Here is a hypothetical data dictionary. reStructuredText_ source:: name : string Customer name. @@ -698,7 +703,8 @@ is typically used for an email or web address. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: The following elements may contain ``contact``: docinfo_, authors_ @@ -734,7 +740,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -764,7 +770,8 @@ The ``copyright`` element contains the document's copyright statement. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``copyright``. @@ -799,7 +806,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -835,7 +842,8 @@ last modification of the document. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``date``. @@ -869,7 +877,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -902,7 +910,8 @@ footer_ element is implemented, populated with processing information Details ------- -:Category: `Structural Subelements`_ +:Category: + `Structural Subelements`_ :Parents: Only the document_ element contains ``decoration``. @@ -936,7 +945,7 @@ empty ``decoration`` elements are ever created. Examples -------- -reStructuredText source:: +reStructuredText_ source:: A paragraph. @@ -963,7 +972,8 @@ to define a term_ in a definition_list_. Details ------- -:Category: `Body Subelements`_ (compound) +:Category: + `Body Subelements`_ (compound) :Parents: Only definition_list_item_ elements contain ``definition``. @@ -1010,7 +1020,8 @@ describe or classify things, for dialogues, or to itemize subtopics Details ------- -:Category: `Compound Body Elements`_ +:Category: + `Compound Body Elements`_ :Parents: All elements employing the `%body.elements;`_ or @@ -1034,7 +1045,7 @@ Content Model .. parsed-literal:: - (definition_list_item_+) + (definition_list_item_ +) :Attributes: The ``definition_list`` element contains only the `common @@ -1049,7 +1060,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Term Definition. @@ -1090,7 +1101,8 @@ term_/definition_ pair (with optional classifier_). Details ------- -:Category: `Body Subelements`_ (compound) +:Category: + `Body Subelements`_ (compound) :Parents: Only the definition_list_ element contains @@ -1125,7 +1137,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Tyrannosaurus Rex : carnivore Big and scary; the "Tyrant King". @@ -1167,7 +1179,45 @@ See definition_list_ and classifier_ for further examples. ``description`` =============== -`To be completed`_. +The ``description`` element contains body elements, describing the +purpose or effect of a command-line option or group of options. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_list_item_ element contains ``description``. + +:Children: + ``description`` elements may contain `body elements`_. + +:Analogues: + ``description`` has no direct analogues in common DTDs. + +:Processing: + See option_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``description`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the option_list_ element. ``docinfo`` @@ -1181,7 +1231,8 @@ front matter of a book, such as the title page and copyright page. Details ------- -:Category: `Structural Subelements`_ +:Category: + `Structural Subelements`_ :Parents: Only the document_ element contains ``docinfo``. @@ -1224,7 +1275,7 @@ Content Model Examples -------- -Docinfo is represented in reStructuredText by a field_list_ in a +Docinfo is represented in reStructuredText_ by a field_list_ in a bibliographic context: the first non-comment element of a document_, after any document title_/subtitle_. The field list is transformed into a ``docinfo`` element and its children by a transform. Source:: @@ -1292,7 +1343,8 @@ tree. It is the starting point for a document. Details ------- -:Category: `Structural Elements`_ +:Category: + `Structural Elements`_ :Parents: The ``document`` element has no parents. @@ -1337,7 +1389,7 @@ of a ``document``. Examples -------- -reStructuredText source:: +reStructuredText_ source:: A Title ======= @@ -1385,7 +1437,8 @@ uniformly marked with enumerator labels. Details ------- -:Category: `Compound Body Elements`_ +:Category: + `Compound Body Elements`_ :Parents: All elements employing the `%body.elements;`_ or @@ -1410,7 +1463,7 @@ Content Model .. parsed-literal:: - (list_item_+) + (list_item_ +) :Attributes: The ``enumerated_list`` element contains the `common attributes`_ @@ -1424,12 +1477,12 @@ Content Model MMMMCMXCIX [4999]). ``prefix`` stores the formatting characters used before the - enumerator. In documents originating from reStructuredText data, + enumerator. In documents originating from reStructuredText_ data, it will contain either "" (empty string) or "(" (left parenthesis). It may or may not affect processing. ``suffix`` stores the formatting characters used after the - enumerator. In documents originating from reStructuredText data, + enumerator. In documents originating from reStructuredText_ data, it will contain either "." (period) or ")" (right parenthesis). Depending on the capabilities of the output format, this attribute may or may not affect processing. @@ -1447,7 +1500,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: 1. Item 1. @@ -1496,7 +1549,8 @@ elements. Details ------- -:Category: `Body Subelements`_ +:Category: + `Body Subelements`_ :Parents: The following elements may contain ``field``: docinfo_, @@ -1509,7 +1563,8 @@ Details :Analogues: ``field`` has no direct analogues in common DTDs. -:Processing: See field_list_. +:Processing: + See field_list_. Content Model @@ -1544,7 +1599,8 @@ a database field's data. Details ------- -:Category: `Body Subelements`_ +:Category: + `Body Subelements`_ :Parents: Only the field_ element contains ``field_body``. @@ -1555,7 +1611,8 @@ Details :Analogues: ``field_body`` has no direct analogues in common DTDs. -:Processing: See field_list_. +:Processing: + See field_list_. Content Model @@ -1581,7 +1638,7 @@ See the examples for the field_list_ and docinfo_ elements. The ``field_list`` element contains two-column table-like structures resembling database records (label & data pairs). Field lists are -often meant for further processing. In reStructuredText, field lists +often meant for further processing. In reStructuredText_, field lists are used to represent bibliographic fields (contents of the docinfo_ element) and directive options. @@ -1589,7 +1646,8 @@ element) and directive options. Details ------- -:Category: `Compound Body Elements`_ +:Category: + `Compound Body Elements`_ :Parents: All elements employing the `%body.elements;`_ or @@ -1616,7 +1674,7 @@ Content Model .. parsed-literal:: - (field_+) + (field_ +) :Attributes: The ``field_list`` element contains only the `common attributes`_: @@ -1631,7 +1689,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: :Author: Me :Version: 1 @@ -1677,7 +1735,8 @@ to a database field's name. Details ------- -:Category: `Body Subelements`_ +:Category: + `Body Subelements`_ :Parents: Only the field_ element contains ``field_name``. @@ -1689,7 +1748,8 @@ Details :Analogues: ``field_name`` has no direct analogues in common DTDs. -:Processing: See field_list_. +:Processing: + See field_list_. Content Model @@ -1728,7 +1788,8 @@ processing information (datestamp, a link to Docutils_, etc.). Details ------- -:Category: `Decorative Elements`_ +:Category: + `Decorative Elements`_ :Parents: Only the decoration_ element contains ``footer``. @@ -1757,7 +1818,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: A paragraph. @@ -1803,7 +1864,8 @@ page. Docutils does not yet make use of the ``header`` element. Details ------- -:Category: `Decorative Elements`_ +:Category: + `Decorative Elements`_ :Parents: Only the decoration_ element contains ``header``. @@ -1887,7 +1949,8 @@ item. Details ------- -:Category: `Body Subelements`_ (compound) +:Category: + `Body Subelements`_ (compound) :Parents: The bullet_list_ and enumerated_list_ elements contain @@ -1919,7 +1982,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: 1. Outer list, item 1. @@ -1969,37 +2032,332 @@ See bullet_list_ or enumerated_list_ for further examples. ``option`` ========== -`To be completed`_. +The ``option`` element groups an option string together with zero or +more option argument placeholders. Note that reStructuredText_ +currently supports only one argument per option. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_group_ element contains ``option``. + +:Children: + Each ``option`` element contains one option_string_ and zero or + more option_argument_ elements. + +:Analogues: + ``option`` has no direct analogues in common DTDs. + +:Processing: + See option_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (option_string_, option_argument_ \*) + +:Attributes: + The ``option`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the option_list_ element. ``option_argument`` =================== -`To be completed`_. +The ``option_argument`` element contains placeholder text for option +arguments. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_ element contains ``option_argument``. + +:Children: + ``option_argument`` elements contain text data only. + +:Analogues: + ``option_argument`` has no direct analogues in common DTDs. + +:Processing: + The value of the "delimiter" attribute is prefixed to the + ``option_argument``, separating it from its option_string_ or a + preceding ``option_argument``. The ``option_argument`` text is + typically rendered in a monospaced typeface, possibly italicized + or otherwise altered to indicate its placeholder nature. + + +Content Model +------------- + +.. parsed-literal:: + + (#PCDATA) + +:Attributes: + The ``option_argument`` element contains the `common attributes`_ (id_, + name_, dupname_, source_, and class_), plus delimiter_. + + ``delimiter`` contains the text preceding the ``option_argument``: + either the text separating it from the option_string_ (typically + either "=" or " ") or the text between option arguments (typically + either "," or " "). + + +Examples +-------- + +See the examples for the option_list_ element. ``option_group`` ================ -`To be completed`_. +The ``option_group`` element groups together one or more option_ +elements, all synonyms. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_list_item_ element contains ``option_group``. + +:Children: + ``option_group`` elements contain one or more option_ elements. + + ``option_group`` is an empty element and has no children. + + Each ``option_group`` element contains one _ and + one _ element. + +:Analogues: + ``option_group`` has no direct analogues in common DTDs. + +:Processing: + Typically option_ elements within an ``option_group`` are joined + together in a comma-separated list. + + +Content Model +------------- + +.. parsed-literal:: + + (option_group_, description_) + +:Attributes: + The ``option_group`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the option_list_ element. ``option_list`` =============== -`To be completed`_. +Each ``option_list`` element contains a two-column list of +command-line options and descriptions, documenting a program's +options. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``option_list``. + +:Children: + ``option_list`` elements contain one or more option_list_item_ + elements. + +:Analogues: + ``option_list`` has no direct analogues in common DTDs. It can be + emulated with primitives such as tables. + +:Processing: + An ``option_list`` is typically rendered as a two-column list, + where the first column contains option strings and arguments, and + the second column contains descriptions. + + +Content Model +------------- + +.. parsed-literal:: + + (option_list_item_ +) + +:Attributes: + The ``option_list`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``option_list``. The `%structure.model;`_ parameter entity + indirectly includes ``option_list``. + + +Examples +-------- + +reStructuredText_ source:: + + -a command-line option "a" + -1 file, --one=file, --two file + Multiple options with arguments. + +Pseudo-XML_ fragment from simple parsing:: + + <option_list> + <option_list_item> + <option_group> + <option> + <option_string> + -a + <description> + <paragraph> + command-line option "a" + <option_list_item> + <option_group> + <option> + <option_string> + -1 + <option_argument delimiter=" "> + file + <option> + <option_string> + --one + <option_argument delimiter="="> + file + <option> + <option_string> + --two + <option_argument delimiter=" "> + file + <description> + <paragraph> + Multiple options with arguments. ``option_list_item`` ==================== -`To be completed`_. +The ``option_list_item`` element is a container for a pair of +option_group_ and description_ elements. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_list_ element contains ``option_list_item``. + +:Children: + Each ``option_list_item`` element contains one option_group_ and + one description_ element. + +:Analogues: + ``option_list_item`` has no direct analogues in common DTDs. + +:Processing: + See option_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (option_group_, description_) + +:Attributes: + The ``option_list_item`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the option_list_ element. ``option_string`` ================= -`To be completed`_. +The ``option_string`` element contains the text of a command-line +option. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_ element contains ``option_string``. + +:Children: + ``option_string`` elements contain text data only. + +:Analogues: + ``option_string`` has no direct analogues in common DTDs. + +:Processing: + The ``option_string`` text is typically rendered in a monospaced + typeface. + + +Content Model +------------- + +.. parsed-literal:: + + (#PCDATA) + +:Attributes: + The ``option_string`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the option_list_ element. ``organization`` @@ -2012,7 +2370,8 @@ organization, or the organization responsible for the document. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``organization``. @@ -2048,7 +2407,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -2078,7 +2437,8 @@ single paragraph, a fundamental building block of documents. Details ------- -:Category: `Simple Body Elements`_ +:Category: + `Simple Body Elements`_ :Parents: All elements employing the `%body.elements;`_ or @@ -2114,7 +2474,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: A paragraph. @@ -2158,7 +2518,8 @@ It can be used alone or in conjunction with version_. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``revision``. @@ -2195,7 +2556,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -2237,7 +2598,8 @@ not after it. Details ------- -:Category: `Structural Elements`_ +:Category: + `Structural Elements`_ :Parents: The following elements may contain ``section``: document_, @@ -2276,7 +2638,7 @@ of a ``section``. Examples -------- -reStructuredText source:: +reStructuredText_ source:: Title 1 ======= @@ -2329,7 +2691,8 @@ such as "Draft", "Final", "Work In Progress", etc. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``status``. @@ -2363,7 +2726,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -2410,7 +2773,8 @@ The ``subtitle`` element stores the subtitle of a document_. Details ------- -:Category: `Structural Subelements`_ +:Category: + `Structural Subelements`_ :Parents: Only the document_ element contains ``subtitle``. @@ -2442,7 +2806,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: ======= Title @@ -2503,7 +2867,8 @@ definition_list_. Details ------- -:Category: `Body Subelements`_ (simple) +:Category: + `Body Subelements`_ (simple) :Parents: Only the definition_list_item_ element contains ``term``. @@ -2566,7 +2931,8 @@ topic_. Details ------- -:Category: `Structural Subelements`_ +:Category: + `Structural Subelements`_ :Parents: The following elements may contain ``title``: document_, section_, @@ -2600,7 +2966,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: A Title ======= @@ -2629,7 +2995,8 @@ a ``table`` or a ``list``, or inside another ``topic``. Details ------- -:Category: `Structural Elements`_ +:Category: + `Structural Elements`_ :Parents: The following elements may contain ``topic``: document_, section_ @@ -2667,7 +3034,7 @@ Examples -------- The `"topic" directive`_ is used to create a ``topic`` element. -reStructuredText source:: +reStructuredText_ source:: .. topic:: Title @@ -2704,7 +3071,8 @@ __ rst/alternatives.txt Details ------- -:Category: `Structural Subelements`_ +:Category: + `Structural Subelements`_ :Parents: The following elements may contain ``transition``: document_, @@ -2745,7 +3113,7 @@ The ``transition`` element has no content; it is a "point element". Examples -------- -reStructuredText source:: +reStructuredText_ source:: Paragraph 1. @@ -2773,7 +3141,8 @@ It can be used alone or in conjunction with revision_. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``version``. @@ -2810,7 +3179,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -2937,6 +3306,14 @@ standardized document tree. ``class`` is one of the `common attributes`_, shared by all Docutils elements. +``delimiter`` +============= + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``delimiter`` attribute is used in the option_argument_ element. + + ``dupname`` =========== -- cgit v1.2.1 From 4ea8903f17cf86452afef915296820e8c7d8225f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 21 Nov 2002 02:31:16 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@973 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 495fec567..1e22f7bd9 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -522,6 +522,9 @@ directive. For example:: If an included document fragment contains section structure, the title adornments must match those of the master document. +The text encoding of the master input source is used for included +files. + The following options are recognized: ``literal`` : flag (empty) -- cgit v1.2.1 From 7e3ce390de2658e948d5c9c83df50bbc7ab12862 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 5 Dec 2002 02:37:37 +0000 Subject: completed 13 elements; 30 to go git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@993 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 967 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 893 insertions(+), 74 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 8e27088ca..f55aed5f3 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -356,7 +356,64 @@ context. ``attention`` ============= -`To be completed`_. +The ``attention`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): caution_, danger_, error_, +hint_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``attention``. + +:Children: + ``attention`` elements contain one or more `body elements`_. + +:Analogues: + ``attention`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Attention!" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``attention`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``attention``. The `%structure.model;`_ parameter entity + indirectly includes ``attention``. + + +Examples +-------- + +reStructuredText source:: + + .. Attention:: All your base are belong to us. + +Pseudo-XML_ fragment from simple parsing:: + + <attention> + <paragraph> + All your base are belong to us. ``author`` @@ -500,7 +557,70 @@ context. ``block_quote`` =============== -`To be completed`_. +The ``block_quote`` element is used for quotations set off from the +main text (standalone). + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``block_quote``. + +:Children: + ``block_quote`` elements may contain `body elements`_. + +:Analogues: + ``block_quote`` is analogous to the "blockquote" element in both + HTML and DocBook. + +:Processing: + ``block_quote`` elements serve to set their contents off from the + main text, typically with indentation and/or other decoration. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``block_quote`` element contains only the `common + attributes`_: id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``block_quote``. The `%structure.model;`_ parameter entity + indirectly includes ``block_quote``. + + +Examples +-------- + +reStructuredText source:: + + As a great paleontologist once said, + + This theory, that is mine, is mine. + + -- Anne Elk (Miss) + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + As a great paleontologist once said, + <block_quote> + <paragraph> + This theory, that is mine, is mine. + <paragraph> + -- Anne Elk (Miss) ``bullet_list`` @@ -594,7 +714,63 @@ See list_item_ for another example. ``caution`` =========== -`To be completed`_. +The ``caution`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, danger_, error_, +hint_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``caution``. + +:Children: + ``caution`` elements contain one or more `body elements`_. + +:Analogues: + ``caution`` is analogous to the DocBook "caution" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Caution" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``caution`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``caution``. The `%structure.model;`_ parameter entity + indirectly includes ``caution``. + + +Examples +-------- + +reStructuredText source:: + + .. Caution:: Don't take any wooden nickels. + +Pseudo-XML_ fragment from simple parsing:: + + <caution> + <paragraph> + Don't take any wooden nickels. ``citation`` @@ -829,7 +1005,64 @@ context. ``danger`` ========== -`To be completed`_. +The ``danger`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, error_, +hint_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``danger``. + +:Children: + ``danger`` elements contain one or more `body elements`_. + +:Analogues: + ``danger`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "!DANGER!" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``danger`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``danger``. The `%structure.model;`_ parameter entity + indirectly includes ``danger``. + + +Examples +-------- + +reStructuredText source:: + + .. DANGER:: Mad scientist at work! + +Pseudo-XML_ fragment from simple parsing:: + + <danger> + <paragraph> + Mad scientist at work! ``date`` @@ -1328,7 +1561,78 @@ see the individual examples for the various `bibliographic elements`_. ``doctest_block`` ================= -`To be completed`_. +The ``doctest_block`` element is a Python-specific variant of +literal_block_. It is a block of text where line breaks and +whitespace are significant and must be preserved. ``doctest_block`` +elements are used for interactive Python interpreter sessions, which +are distinguished by their input prompt: ``>>>``. 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 module: + http://www.python.org/doc/current/lib/module-doctest.html + + +Details +------- + +:Category: + `Simple Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``doctest_block``. + +:Children: + ``doctest_block`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``doctest_block`` is analogous to the HTML "pre" element and to + the DocBook "programlisting" and "screen" elements. + +:Processing: + As with literal_block_, ``doctest_block`` elements are typically + rendered in a monospaced typeface. It is crucial that all + whitespace and line breaks are preserved in the rendered form. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``doctest_block`` element contains the `common attributes`_ + (id_, name_, dupname_, source_, and class_), plus `xml:space`_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``doctest_block``. The `%structure.model;`_ parameter entity + indirectly includes ``doctest_block``. + + +Examples +-------- + +reStructuredText source:: + + This is an ordinary paragraph. + + >>> print 'this is a Doctest block' + this is a Doctest block + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + This is an ordinary paragraph. + <doctest_block xml:space="preserve"> + >>> print 'this is a Doctest block' + this is a Doctest block ``document`` @@ -1536,7 +1840,64 @@ See list_item_ for another example. ``error`` ========= -`To be completed`_. +The ``error`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, hint_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``error``. + +:Children: + ``error`` elements contain one or more `body elements`_. + +:Analogues: + ``error`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Error" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``error`` element contains only the `common attributes`_: id_, + name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``error``. The `%structure.model;`_ parameter entity indirectly + includes ``error``. + + +Examples +-------- + +reStructuredText source:: + + .. Error:: Does not compute. + +Pseudo-XML_ fragment from simple parsing:: + + <error> + <paragraph> + Does not compute. ``field`` @@ -1811,72 +2172,291 @@ Content Model (`%body.elements;`_)+ :Attributes: - The ``footer`` element contains only the `common attributes`_: + The ``footer`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +reStructuredText_ source:: + + A paragraph. + +Complete pseudo-XML_ result after parsing and applying transforms, +assuming that the datestamp command-line option or configuration +setting has been supplied:: + + <document> + <decoration> + <footer> + <paragraph> + Generated on: 2002-08-20. + <paragraph> + A paragraph. + + +``footnote`` +============ + +`To be completed`_. + + +``footnote_reference`` +====================== + +`To be completed`_. + + +``generated`` +============= + +`To be completed`_. + + +``header`` +========== + +The ``header`` element is a container element whose contents are meant +to appear at the top of a web page, or at the top of every printed +page. Docutils does not yet make use of the ``header`` element. + + +Details +------- + +:Category: + `Decorative Elements`_ + +:Parents: + Only the decoration_ element contains ``header``. + +:Children: + ``header`` elements may contain `body elements`_. + +:Analogues: + There are no direct analogies to ``header`` in HTML or DocBook. + Equivalents are typically constructed from primitives and/or + generated by the processing system. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``header`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +None. + + +``hint`` +======== + +The ``hint`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``hint``. + +:Children: + ``hint`` elements contain one or more `body elements`_. + +:Analogues: + ``hint`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Hint" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``hint`` element contains only the `common attributes`_: id_, + name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``hint``. The `%structure.model;`_ parameter entity indirectly + includes ``hint``. + + +Examples +-------- + +reStructuredText source:: + + .. Hint:: It's bigger than a bread box. + +Pseudo-XML_ fragment from simple parsing:: + + <hint> + <paragraph> + It's bigger than a bread box. + + +``image`` +========= + +`To be completed`_. + + +``important`` +============= + +The ``important`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, hint_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``important``. + +:Children: + ``important`` elements contain one or more `body elements`_. + +:Analogues: + ``important`` is analogous to the DocBook "important" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Important" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``important`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``important``. The `%structure.model;`_ parameter entity + indirectly includes ``important``. + Examples -------- -reStructuredText_ source:: +reStructuredText source:: - A paragraph. + .. Important:: -Complete pseudo-XML_ result after parsing and applying transforms, -assuming that the datestamp command-line option or configuration -setting has been supplied:: + * Wash behind your ears. + * Clean up your room. + * Back up your data. + * Call your mother. - <document> - <decoration> - <footer> +Pseudo-XML_ fragment from simple parsing:: + + <important> + <bullet_list> + <list_item> <paragraph> - Generated on: 2002-08-20. - <paragraph> - A paragraph. + Wash behind your ears. + <list_item> + <paragraph> + Clean up your room. + <list_item> + <paragraph> + Back up your data. + <list_item> + <paragraph> + Call your mother. -``footnote`` -============ +``interpreted`` +=============== `To be completed`_. -``footnote_reference`` -====================== +``label`` +========= `To be completed`_. -``generated`` -============= +``legend`` +========== `To be completed`_. -``header`` -========== +``line_block`` +============== -The ``header`` element is a container element whose contents are meant -to appear at the top of a web page, or at the top of every printed -page. Docutils does not yet make use of the ``header`` element. +The ``line_block`` element contains a block of text where line breaks +and whitespace are significant and must be preserved. ``line_block`` +elements are commonly used for verse and addresses. See `line_block`_ +for an alternative useful for program listings and interactive +computer sessions. Details ------- :Category: - `Decorative Elements`_ + `Simple Body Elements`_ :Parents: - Only the decoration_ element contains ``header``. + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``line_block``. :Children: - ``header`` elements may contain `body elements`_. + ``line_block`` elements may contain text data plus `inline + elements`_. :Analogues: - There are no direct analogies to ``header`` in HTML or DocBook. - Equivalents are typically constructed from primitives and/or - generated by the processing system. + ``line_block`` is analogous to the DocBook "literallayout" element + and to the HTML "pre" element (with modifications to typeface + styles). + +:Processing: + Unline ``literal_block``, ``line_block`` elements are typically + rendered in an ordinary text typeface. It is crucial that all + whitespace and line breaks are preserved in the rendered form. Content Model @@ -1884,59 +2464,60 @@ Content Model .. parsed-literal:: - (`%body.elements;`_)+ + `%text.model;`_ :Attributes: - The ``header`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + The ``line_block`` element contains the `common attributes`_ (id_, + name_, dupname_, source_, and class_), plus `xml:space`_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``line_block``. The `%structure.model;`_ parameter entity + indirectly includes ``line_block``. Examples -------- -None. - - -``hint`` -======== - -`To be completed`_. - - -``image`` -========= - -`To be completed`_. - +reStructuredText uses a directive to indicate a ``line_block``. +Example source:: -``important`` -============= - -`To be completed`_. - - -``interpreted`` -=============== + Take it away, Eric the Orchestra Leader! -`To be completed`_. + .. line-block:: + A one, two, a one two three four -``label`` -========= + Half a bee, philosophically, + must, *ipso facto*, half not be. + But half the bee has got to be, + *vis a vis* its entity. D'you see? -`To be completed`_. + But can a bee be said to be + or not to be an entire bee, + when half the bee is not a bee, + due to some ancient injury? + Singing... -``legend`` -========== +Pseudo-XML_ fragment from simple parsing:: -`To be completed`_. + <paragraph> + Take it away, Eric the Orchestra Leader! + <line_block xml:space="preserve"> + A one, two, a one two three four + Half a bee, philosophically, + must, <emphasis>ipso facto</emphasis>, half not be. + But half the bee has got to be, + <emphasis>vis a vis</emphasis>its entity. D'you see? -``line_block`` -============== + But can a bee be said to be + or not to be an entire bee, + when half the bee is not a bee, + due to some ancient injury? -`To be completed`_. + Singing... ``list_item`` @@ -2020,14 +2601,140 @@ See bullet_list_ or enumerated_list_ for further examples. ``literal_block`` ================= -`To be completed`_. +The ``literal_block`` element contains a block of text where line +breaks and whitespace are significant and must be preserved. +``literal_block`` elements are commonly used for program listings and +interactive computer sessions. See `line_block`_ for an alternative +useful for verse and addresses. + + +Details +------- + +:Category: + `Simple Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``literal_block``. + +:Children: + ``literal_block`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``literal_block`` is analogous to the HTML "pre" element and to + the DocBook "programlisting" and "screen" elements. + +:Processing: + ``literal_block`` elements are typically rendered in a monospaced + typeface. It is crucial that all whitespace and line breaks are + preserved in the rendered form. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``literal_block`` element contains the `common attributes`_ + (id_, name_, dupname_, source_, and class_), plus `xml:space`_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``literal_block``. The `%structure.model;`_ parameter entity + indirectly includes ``literal_block``. + + +Examples +-------- + +reStructuredText source:: + + Here is a literal block:: + + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + Here is a literal block: + <literal_block xml:space="preserve"> + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None ``note`` ======== -`To be completed`_. +The ``note`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, hint_, important_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``note``. + +:Children: + ``note`` elements contain one or more `body elements`_. + +:Analogues: + ``note`` is analogous to the DocBook "note" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Note" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ +:Attributes: + The ``note`` element contains only the `common attributes`_: id_, + name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``note``. The `%structure.model;`_ parameter entity indirectly + includes ``note``. + + +Examples +-------- + +reStructuredText source:: + + .. Note:: Admonitions can be handy to break up a + long boring technical document. + +Pseudo-XML_ fragment from simple parsing:: + + <note> + <paragraph> + Admonitions can be handy to break up a + long boring technical document. ``option`` ========== @@ -2918,7 +3625,63 @@ classifier_ elements. ``tip`` ======= -`To be completed`_. +The ``tip`` element is an admonition, a distinctive and self-contained +notice. Also see the other admonition elements Docutils offers (in +alphabetical order): attention_, caution_, danger_, error_, hint_, +important_, note_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``tip``. + +:Children: + ``tip`` elements contain one or more `body elements`_. + +:Analogues: + ``tip`` is analogous to the DocBook "tip" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Tip" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``tip`` element contains only the `common attributes`_: id_, + name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes ``tip``. + The `%structure.model;`_ parameter entity indirectly includes + ``tip``. + + +Examples +-------- + +reStructuredText source:: + + .. Tip:: 15% if the service is good. + +Pseudo-XML_ fragment from simple parsing:: + + <tip> + <paragraph> + 15% if the service is good. ``title`` @@ -3202,7 +3965,63 @@ context. ``warning`` =========== -`To be completed`_. +The ``warning`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, hint_, important_, note_, tip_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``warning``. + +:Children: + ``warning`` elements contain one or more `body elements`_. + +:Analogues: + ``warning`` is analogous to the DocBook "warning" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Warning" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``warning`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``warning``. The `%structure.model;`_ parameter entity indirectly + includes ``warning``. + + +Examples +-------- + +reStructuredText source:: + + .. WARNING:: Reader discretion is strongly advised. + +Pseudo-XML_ fragment from simple parsing:: + + <warning> + <paragraph> + Reader discretion is strongly advised. --------------------- -- cgit v1.2.1 From a4237939cd9815ee1f487ffab293398b843a6e25 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 5 Dec 2002 02:40:14 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@994 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 1e22f7bd9..3a0449f40 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -513,11 +513,13 @@ directive. For example:: .. include:: inclusion.txt - This second will be parsed in a block quote context. - Therefore it may only contain body elements. It may not - contain section headers. + Back in the main document. - .. include:: inclusion.txt + This second example will be parsed in a block quote context. + Therefore it may only contain body elements. It may not + contain section headers. + + .. include:: inclusion.txt If an included document fragment contains section structure, the title adornments must match those of the master document. -- cgit v1.2.1 From 3b2fad8136d9ba7c4db32426eb96f62640b14323 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 7 Dec 2002 03:11:38 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1005 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index a5564f042..7874bca3a 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -44,6 +44,8 @@ peps.TargetNotes pep (r) 520 references.TargetNotes peps.TargetNotes (t/p) 0 +misc.CallBack peps.TargetNotes (t/p) 1 + references.TargetNotes "target-notes" (d/p) 540 references.Footnotes standalone (r), pep (r) 620 @@ -68,6 +70,8 @@ universal.FinalChecks Transformer 840 universal.Messages Transformer 860 universal.TestMessages DocutilsTestSupport 890 + +misc.CallBack n/a 990 ============================== ============================ ======== Key: @@ -86,9 +90,7 @@ Transform Priority Range Categories ---------- ------------------------------------------------ From To Category ==== ==== ================================================ - 0 immediate execution (added by another transform) ----------- ------------------------------------------------ - 1 99 unused + 0 99 immediate execution (added by another transform) 100 199 very early (non-standard) 200 299 very early 300 399 early -- cgit v1.2.1 From eb82300e688f6e452b1db58d5abadd76be56025d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 17 Dec 2002 02:25:19 +0000 Subject: Added support for backslash-escape after inline markup. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1023 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 5f7ae8ebd..d2838ac72 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2140,9 +2140,9 @@ In reStructuredText, inline markup applies to words or phrases within a text block. The same whitespace and punctuation that serves to delimit words in written text is used to delimit the inline markup syntax constructs. The text within inline markup may not begin or end -with whitespace. Arbitrary character-level markup is not supported; -it is not possible to mark up individual characters within a word. -Inline markup cannot be nested. +with whitespace. Arbitrary character-level markup is not supported +[#]_; it is not possible to mark up individual characters within a +word. Inline markup cannot be nested. There are nine inline markup constructs. Five of the constructs use identical start-strings and end-strings to indicate the markup: @@ -2243,6 +2243,18 @@ each character. The inline markup recognition order is as follows: - `Standalone hyperlinks`_ are the last to be recognized. +.. [#] Backslash escapes can be used to allow arbitrary text to + immediately follow inline markup:: + + Python ``list``\s use square bracket syntax. + + The backslash will disappear from the processed document. The word + "list" will appear as inline literal text, and the letter "s" will + immediately follow it as normal text, with no space in-between. + + There is not yet any way for arbitrary text to immediately precede + inline markup. + Emphasis -------- -- cgit v1.2.1 From 223a5013b74c0a1eef9d183346c0115c22815e2b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 4 Jan 2003 15:02:22 +0000 Subject: added warning git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1063 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index f55f6bcea..a7b27a9ef 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -493,6 +493,11 @@ following caveats: <!ELEMENT strong %text.model;> <!ATTLIST strong %basic.atts;> +<!-- +WARNING: The "interpreted" element is a placeholder for testing +purposes only. Once proper parser support is in place, it will be +removed. +--> <!ELEMENT interpreted %text.model;> <!ATTLIST interpreted %basic.atts; -- cgit v1.2.1 From 0e726b1398ec735dfa2a109f4a3c152dcc7a2b9d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:15:32 +0000 Subject: Removed "interpreted" element; added "title_reference", "abbreviation", "acronym". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1081 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index f55aed5f3..2045552bf 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -198,9 +198,10 @@ Inline elements directly contain text data, and may also contain further inline elements. Inline elements are contained within simple body elements. Most inline elements have a "mixed content model". -Category members: citation_reference_, emphasis_, footnote_reference_, -generated_, image_, interpreted_, literal_, problematic_, reference_, -strong_, substitution_reference_, target_, raw_ +Category members: abbreviation_, acronym_, citation_reference_, +emphasis_, footnote_reference_, generated_, image_, literal_, +problematic_, reference_, strong_, substitution_reference_, target_, +title_reference_, raw_ .. _HTML: http://www.w3.org/MarkUp/ @@ -279,6 +280,18 @@ completed`". Please help complete this document by contributing to its writing. +``abbreviation`` +================ + +`To be completed`_. + + +``acronym`` +=========== + +`To be completed`_. + + ``address`` =========== @@ -2405,12 +2418,6 @@ Pseudo-XML_ fragment from simple parsing:: Call your mother. -``interpreted`` -=============== - -`To be completed`_. - - ``label`` ========= @@ -3745,6 +3752,12 @@ Pseudo-XML_ fragment from simple parsing:: A paragraph. +``title_reference`` +=================== + +`To be completed`_. + + ``topic`` ========= -- cgit v1.2.1 From 062a5e1abc7f92c84fff24ad40e24bf35eb167de Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:16:04 +0000 Subject: Removed "interpreted" element; added "title_reference", "abbreviation", "acronym". Removed "refuri" attribute from "footnote_reference" and "citation_reference". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1082 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index a7b27a9ef..e5bc5a46e 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -129,7 +129,9 @@ resolve to either an internal or external reference. <!ENTITY % inline.elements " emphasis | strong | interpreted | literal | reference | footnote_reference | citation_reference - | substitution_reference | problematic | generated + | substitution_reference | title_reference + | abbreviation | acronym | + | problematic | generated | target | image | raw %additional.inline.elements; "> @@ -493,17 +495,6 @@ following caveats: <!ELEMENT strong %text.model;> <!ATTLIST strong %basic.atts;> -<!-- -WARNING: The "interpreted" element is a placeholder for testing -purposes only. Once proper parser support is in place, it will be -removed. ---> -<!ELEMENT interpreted %text.model;> -<!ATTLIST interpreted - %basic.atts; - role NMTOKEN #IMPLIED - position (prefix | suffix) #IMPLIED> - <!ELEMENT literal (#PCDATA)> <!ATTLIST literal %basic.atts;> @@ -516,19 +507,30 @@ removed. <!ELEMENT footnote_reference (#PCDATA)> <!ATTLIST footnote_reference %basic.atts; - %reference.atts; + %refid.att; + %refname.att; %auto.att;> <!ELEMENT citation_reference (#PCDATA)> <!ATTLIST citation_reference %basic.atts; - %reference.atts;> + %refid.att; + %refname.att;> <!ELEMENT substitution_reference %text.model;> <!ATTLIST substitution_reference %basic.atts; %refname.att;> +<!ELEMENT title_reference %text.model;> +<!ATTLIST title_reference %basic.atts;> + +<!ELEMENT abbreviation %text.model;> +<!ATTLIST abbreviation %basic.atts;> + +<!ELEMENT acronym %text.model;> +<!ATTLIST acronym %basic.atts;> + <!ELEMENT problematic %text.model;> <!ATTLIST problematic %basic.atts; -- cgit v1.2.1 From 864c13ae2445706b95d038fa0b856293bf30a4e5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:18:05 +0000 Subject: Updated "Interpreted Text" section. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1084 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 52 ++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 28 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index d2838ac72..e99e31767 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2287,42 +2287,39 @@ Strongly emphasized text is typically displayed in boldface. Interpreted Text ---------------- -DTD element: interpreted. +DTD element: depends on the explicit or implicit role and processing. Start-string = end-string = "`". -Text enclosed by single backquote characters is interpreted:: +Interpreted text is text that is meant to be related, indexed, linked, +summarized, or otherwise processed, but the text itself is typically +left alone. Interpreted text is enclosed by single backquote +characters:: This is `interpreted text`. -Interpreted text is text that is meant to be related, indexed, linked, -summarized, or otherwise processed, but the text itself is left -alone. The text is "tagged" directly, in-place. The semantics of -interpreted text are domain-dependent. It can be used as implicit or -explicit descriptive markup (such as for program identifiers, as in -the `Python Source Reader`_), for cross-reference interpretation (such -as index entries), or for other applications where context can be -inferred. - -The role of the interpreted text determines how the text is -interpreted. It is normally inferred implicitly. The role of the -interpreted text may also be indicated explicitly, using a role -marker, either as a prefix or as a suffix to the interpreted text, -depending on which reads better:: +The "role" of the interpreted text determines how the text is +interpreted. The role may be inferred implicitly (as above; the +"default role" is used) or indicated explicitly, using a role marker. +A role marker consists of a colon, the role name, and another colon. +A role name is a single word consisting of alphanumerics plus internal +hyphens, underscores, and periods; no whitespace or other characters +are allowed. A role marker is either a prefix or a suffix to the +interpreted text, whichever reads better; it's up to the author:: :role:`interpreted text` `interpreted text`:role: -Roles are simply extensions of the available inline constructs; to -emphasis_, `strong emphasis`_, `inline literals`_, and `hyperlink -references`_, we can add "index entry", "acronym", "class", "red", -"blinking" or anything else we want. - -A role marker consists of a colon, the role name, and another colon. -A role name is a single word consisting of alphanumerics plus internal -hyphens, underscores, and periods; no whitespace or other characters -are allowed. +Interpreted text allows extensions to the available inline descriptive +markup constructs. To emphasis_, `strong emphasis`_, `inline +literals`_, and `hyperlink references`_, we can add "title reference", +"index entry", "acronym", "class", "red", "blinking" or anything else +we want. Only pre-determined roles are recognized; unknown roles will +generate errors. A core set of standard roles is implemented in the +reference parser; see `reStructuredText Interpreted Text Roles`_ for +individual descriptions. In addition, applications may support +specialized roles. Inline Literals @@ -2536,7 +2533,7 @@ Examples:: Standalone Hyperlinks --------------------- -DTD element: link. +DTD element: reference. Start-string = end-string = "" (empty string). @@ -2630,8 +2627,7 @@ Markup errors are handled according to the specification in `PEP .. _HTML Techniques for Web Content Accessibility Guidelines: http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text .. _reStructuredText Directives: directives.html -.. _Python Source Reader: - http://docutils.sourceforge.net/spec/pysource.txt +.. _reStructuredText Interpreted Text Roles: interpreted.html .. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt .. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt .. _Zope: http://www.zope.com/ -- cgit v1.2.1 From 798975af17442e34055e6cc48b807afea4a9213d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:19:01 +0000 Subject: Descriptions of interpreted text roles. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1085 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/ref/rst/roles.txt (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt new file mode 100644 index 000000000..64045b36d --- /dev/null +++ b/docs/ref/rst/roles.txt @@ -0,0 +1,84 @@ +========================================= + reStructuredText Interpreted Text Roles +========================================= +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +This document describes the interpreted text roles implemented in the +reference reStructuredText parser. + +Interpreted text uses backquotes (`) around the text. An explicit +role marker may optionally appear before or after the text, delimited +with colons. For example:: + + This is `interpreted text` using the default role. + + This is :title:`interpreted text` using an explicit role. + +A default role may be defined by applications of reStructuredText; it +is used if no explicit ``:role:`` prefix or suffix is given. The +"default default role" is `:title-reference:`_. + +See the `Interpreted Text`__ section in the `reStructuredText Markup +Specification`_ for syntax details. + +.. _Interpreted Text: ./reStructuredText.html#interpreted-text +.. _reStructuredText Markup Specification: ./reStructuredText.html + + +.. contents:: + + +``:pep-reference:`` +=================== + +:Aliases: ``:PEP:`` +:DTD Element: reference + +The ``:pep-reference:`` role is used to create an HTTP reference to a +PEP (Python Enhancement Proposal). The ``:PEP:`` alias is usually +used. For example:: + + See :PEP:`287` for more information about reStructuredText. + +This is equivalent to:: + + See `PEP 287`__ for more information about reStructuredText. + + __ http://www.python.org/peps/pep-0287.html + + +``:rfc-reference:`` +=================== + +:Aliases: ``:RFC:`` +:DTD Element: reference + +The ``:rfc-reference:`` role is used to create an HTTP reference to an +RFC (Internet Request for Comments). The ``:RFC:`` alias is usually +used. For example:: + + See :RFC:`2822` for information about email headers. + +This is equivalent to:: + + See `RFC 2822`__ for information about email headers. + + __ http://www.faqs.org/rfcs/rfc2822.html + + +``:title-reference:`` +===================== + +:Aliases: ``:title:``, ``:t:``. +:DTD Element: title_reference + +The ``:title-reference:`` role is used to describe the titles of +books, periodicals, and other materials. + +``:title-reference:`` is the default role in the standard +reStructuredText parser. This means that no explicit role is +required. Applications of reStructuredText may designate a different +default role, in which case the explicit role must be used. -- cgit v1.2.1 From c73dcd6968b586e767c9dab66a226f52f1260680 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:39:46 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1091 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 64045b36d..d3e1a7494 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -21,7 +21,7 @@ A default role may be defined by applications of reStructuredText; it is used if no explicit ``:role:`` prefix or suffix is given. The "default default role" is `:title-reference:`_. -See the `Interpreted Text`__ section in the `reStructuredText Markup +See the `Interpreted Text`_ section in the `reStructuredText Markup Specification`_ for syntax details. .. _Interpreted Text: ./reStructuredText.html#interpreted-text -- cgit v1.2.1 From 432dee48981911f7c4803fea7aac37aaa6218f1d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:44:30 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1092 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 29 ++++++++++++++++------------- docs/ref/docutils.dtd | 6 +++--- 2 files changed, 19 insertions(+), 16 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 2045552bf..3ee68f9d5 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -4447,9 +4447,11 @@ Entity definition: .. parsed-literal:: - emphasis_ | strong_ | interpreted_ | literal_ + emphasis_ | strong_ | literal_ | reference_ | footnote_reference_ | citation_reference_ - | substitution_reference_ | problematic_ | generated_ + | substitution_reference_ | title_reference_ + | abbreviation_ | acronym_ + | problematic_ | generated_ | target_ | image_ | raw_ %additional.inline.elements; @@ -4458,11 +4460,12 @@ wrapper DTDs to extend ``%inline.elements;``. Via `%text.model;`_, the ``%inline.elements;`` parameter entity is indirectly employed in the content models of the following elements: -address_, author_, caption_, classifier_, contact_, copyright_, date_, -doctest_block_, emphasis_, generated_, interpreted_, line_block_, -literal_block_, organization_, paragraph_, problematic_, raw_, -reference_, revision_, status_, strong_, substitution_definition_, -substitution_reference_, subtitle_, target_, term_, title_, version_ +abbreviation_, acronym_, address_, author_, caption_, classifier_, +contact_, copyright_, date_, doctest_block_, emphasis_, generated_, +line_block_, literal_block_, organization_, paragraph_, problematic_, +raw_, reference_, revision_, status_, strong_, +substitution_definition_, substitution_reference_, subtitle_, target_, +term_, title_, version_ ``%reference.atts;`` @@ -4613,12 +4616,12 @@ Entity definition: (#PCDATA | `%inline.elements;`_)* The ``%text.model;`` parameter entity is directly employed in the -content models of the following elements: address_, author_, caption_, -classifier_, contact_, copyright_, date_, doctest_block_, emphasis_, -generated_, interpreted_, line_block_, literal_block_, organization_, -paragraph_, problematic_, raw_, reference_, revision_, status_, -strong_, substitution_definition_, substitution_reference_, subtitle_, -target_, term_, title_, version_ +content models of the following elements: abbreviation_, acronym_, +address_, author_, caption_, classifier_, contact_, copyright_, date_, +doctest_block_, emphasis_, generated_, line_block_, literal_block_, +organization_, paragraph_, problematic_, raw_, reference_, revision_, +status_, strong_, substitution_definition_, substitution_reference_, +subtitle_, target_, term_, title_, version_ diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index e5bc5a46e..03a003b62 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -127,11 +127,11 @@ resolve to either an internal or external reference. <!ENTITY % additional.inline.elements ""> <!ENTITY % inline.elements - " emphasis | strong | interpreted | literal + " emphasis | strong | literal | reference | footnote_reference | citation_reference | substitution_reference | title_reference - | abbreviation | acronym | - | problematic | generated + | abbreviation | acronym + | problematic | generated | target | image | raw %additional.inline.elements; "> -- cgit v1.2.1 From 16979155f8d713326c1a9d5887372c7366196d7c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 11 Jan 2003 00:59:50 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1095 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index d3e1a7494..7b5e80b0a 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -76,9 +76,32 @@ This is equivalent to:: :DTD Element: title_reference The ``:title-reference:`` role is used to describe the titles of -books, periodicals, and other materials. +books, periodicals, and other materials. It is the equivalent of the +HTML "cite" element. Since title references are typically rendered +with italics, they are often marked up using ``*emphasis*``, which is +misleading and vague. The "title_reference" element provides accurate +and unambiguous descriptive markup. -``:title-reference:`` is the default role in the standard -reStructuredText parser. This means that no explicit role is +Let's assume ``:title-reference:`` is the default interpreted text +role (see below) for this example:: + + `Design Patterns` [GoF95]_ is an excellent read. + +The following document fragment (pseudo-XML_) will result from +processing:: + + <paragraph> + <title_reference> + Design Patterns + + <citation_reference refname="gof95"> + GoF95 + is an excellent read. + +``:title-reference:`` is the default interpreted text role in the +standard reStructuredText parser. This means that no explicit role is required. Applications of reStructuredText may designate a different default role, in which case the explicit role must be used. + + +.. _pseudo-XML: ../doctree.html#pseudo-xml -- cgit v1.2.1 From b203fb8fd7596191d692918697927f91fe3afe16 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 11 Jan 2003 22:39:52 +0000 Subject: clarified git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1130 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 7b5e80b0a..9a720eff0 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -77,10 +77,13 @@ This is equivalent to:: The ``:title-reference:`` role is used to describe the titles of books, periodicals, and other materials. It is the equivalent of the -HTML "cite" element. Since title references are typically rendered -with italics, they are often marked up using ``*emphasis*``, which is -misleading and vague. The "title_reference" element provides accurate -and unambiguous descriptive markup. +HTML "cite" element, and it is expected that HTML writers will +typically render "title_reference" elements using "cite". + +Since title references are typically rendered with italics, they are +often marked up using ``*emphasis*``, which is misleading and vague. +The "title_reference" element provides accurate and unambiguous +descriptive markup. Let's assume ``:title-reference:`` is the default interpreted text role (see below) for this example:: -- cgit v1.2.1 From ef4490e4ef04122123ffad9fe83accc867e0a5ed Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 21 Jan 2003 18:32:31 +0000 Subject: clarified section title adornment styles & doc title git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1152 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index e99e31767..eb58100ce 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -447,15 +447,17 @@ Sections DTD elements: section, title. Sections are identified through their titles, which are marked up with -adornment: "underlines" below the title text, and, in some cases, +adornment: "underlines" below the title text, or underlines and matching "overlines" above the title. An underline/overline is a single repeated punctuation character that begins in column 1 and forms a line extending at least as far as the right edge of the title text. Specifically, an underline/overline character may be any non-alphanumeric printable 7-bit ASCII character [#]_. When an overline is used, the length and character used must match the -underline. There may be any number of levels of section titles, -although some output formats may have limits (HTML has 6 levels). +underline. Underline-only adornment styles are distinct from +overline-and-underline styles that use the same character. There may +be any number of levels of section titles, although some output +formats may have limits (HTML has 6 levels). .. [#] The following are all valid section title adornment characters:: -- cgit v1.2.1 From 1fe7b9635381043c5ad87bf651e155a8cc983e21 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 19 Feb 2003 17:23:12 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1189 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 3a0449f40..9cd173714 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -218,7 +218,7 @@ The directive's sole argument is interpreted as the topic title; the next line must be blank. All subsequent lines make up the topic body, interpreted as body elements. For example:: - topic:: Topic Title + .. topic:: Topic Title Subsequent indented lines comprise the body of the topic, and are -- cgit v1.2.1 From 9d4fcb00e8f6023b8ab16b20679198ffbd1acf45 Mon Sep 17 00:00:00 2001 From: pobrien <pobrien@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 20 Feb 2003 14:19:55 +0000 Subject: Added sidebar directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1193 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 7 +++++-- docs/ref/rst/directives.txt | 28 ++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 03a003b62..8edc5f040 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -140,8 +140,8 @@ resolve to either an internal or external reference. ================================================================== --> <!ENTITY % structure.model - " ( ( (%body.elements; | topic)+, - (transition, (%body.elements; | topic)+ )*, + " ( ( (%body.elements; | topic | sidebar)+, + (transition, (%body.elements; | topic | sidebar)+ )*, (%section.elements;)* ) | (%section.elements;)+ ) "> @@ -265,6 +265,9 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT section (title, %structure.model;)> <!ATTLIST section %basic.atts;> +<!ELEMENT sidebar (title, subtitle?, (%body.elements;)+)> +<!ATTLIST sidebar %basic.atts;> + <!ELEMENT topic (title?, (%body.elements;)+)> <!ATTLIST topic %basic.atts;> diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 9cd173714..bdbd53e83 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -199,6 +199,34 @@ legend. To specify a legend without a caption, use an empty comment Body Elements --------------- +Sidebar +======= + +:Directive Type: "sidebar" +:DTD Element: sidebar +:Directive Arguments: One, required (sidebar title). +:Directive Options: Possible; optional subtitle. +:Directive Content: Interpreted as the sidebar body. + +A sidebar is like a block quote with a title, or a self-contained +section with no subsections. Use the "sidebar" directive to indicate a +self-contained idea that is separate from the flow of the document. +Sidebars may occur anywhere a section or transition may occur. Body +elements (including sidebars) may not contain nested sidebars. + +The directive's sole argument is interpreted as the sidebar title, +which may be followed by an optional subtitle; the next line must be +blank. All subsequent lines make up the sidebar body, interpreted as +body elements. For example:: + + .. sidebar:: Sidebar Title + :subtitle: Optional Sidebar Subtitle + + Subsequent indented lines comprise + the body of the sidebar, and are + interpreted as body elements. + + Topic ===== -- cgit v1.2.1 From 585c1818730f3d4cc3551839459ffc730fd6f914 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 20 Feb 2003 14:34:36 +0000 Subject: tweak git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1195 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index eb58100ce..6f260e180 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -467,7 +467,7 @@ formats may have limits (HTML has 6 levels). Some characters are more suitable than others. The following are recommended:: - = - ` : ' " ~ ^ _ * + # < > + = - ` : . ' " ~ ^ _ * + # Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered. -- cgit v1.2.1 From 813c817e2696f9eba43e10cd147ba4a04244a1d1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 20 Feb 2003 22:35:49 +0000 Subject: sidebar improvements git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1196 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 112 ++++++++++++++++++++++++++++++++++++++------ docs/ref/docutils.dtd | 6 +-- docs/ref/rst/directives.txt | 65 ++++++++++++++----------- 3 files changed, 138 insertions(+), 45 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 3ee68f9d5..b97c71b7d 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -102,7 +102,7 @@ directly contain text data. Structural elements may contain body elements or further structural elements. Structural elements can only be child elements of other structural elements. -Category members: document_, section_, topic_ +Category members: document_, section_, topic_, sidebar_ Structural Subelements @@ -3321,7 +3321,7 @@ Details :Children: ``section`` elements begin with a title_, and may contain `body - elements`_ and transition_ and topic_ elements. + elements`_ as well as transition_, topic_, and sidebar_ elements. :Analogues: ``section`` is analogous to DocBook recursive "section" elements, @@ -3395,6 +3395,89 @@ Complete pseudo-XML_ result after parsing:: Paragraph 4. +``sidebar`` +========= + +Sidebars are like miniature, parallel documents that occur inside +other documents, providing related or reference material. A +``sidebar`` is typically offset by a border and "floats" to the side +of the page; the document's main text may flow around it. Sidebars +can also be likened to super-footnotes; their content is outside of +the flow of the document's main text. + +The ``sidebar`` element is a nonrecursive section_-like construct +which may occur at the top level of a section_ wherever a body element +(list, table, etc.) is allowed. In other words, ``sidebar`` elements +cannot nest inside body elements, so you can't have a ``sidebar`` +inside a ``table`` or a ``list``, or inside another ``sidebar`` (or +topic_). + + +Details +------- + +:Category: + `Structural Elements`_ + +:Parents: + The following elements may contain ``sidebar``: document_, + section_ + +:Children: + ``sidebar`` elements begin with a title_ and an optional subtitle_ + and contain `body elements`_. + +:Analogues: + ``sidebar`` is analogous to the DocBook "sidebar" element. + +:Processing: + A ``sidebar`` element should be set off from the rest of the + document somehow, typically with a border. Sidebars typically + "float" to the side of the page and the document's main text flows + around them. + + +Content Model +------------- + +.. parsed-literal:: + + (title_, subtitle_?, + (`%body.elements;`_)+) + +:Attributes: + The ``sidebar`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%structure.model;`_ parameter entity directly includes + ``sidebar``. + + +Examples +-------- + +The `"sidebar" directive`_ is used to create a ``sidebar`` element. +reStructuredText_ source:: + + .. sidebar:: Title + :subtitle: If Desired + + Body. + +Pseudo-XML_ fragment from simple parsing:: + + <sidebar> + <title> + Title + <subtitle> + If Desired + <paragraph> + Body. + +.. _"sidebar" directive: rst/directives.html#sidebar + + ``status`` ========== @@ -3491,7 +3574,7 @@ Details `Structural Subelements`_ :Parents: - Only the document_ element contains ``subtitle``. + The document_ and sidebar_ elements may contain ``subtitle``. :Children: ``subtitle`` elements may contain text data plus `inline @@ -3694,8 +3777,8 @@ Pseudo-XML_ fragment from simple parsing:: ``title`` ========= -The ``title`` element stores the title of a document_, section_, or -topic_. +The ``title`` element stores the title of a document_, section_, +topic_, or sidebar_. Details @@ -3706,7 +3789,7 @@ Details :Parents: The following elements may contain ``title``: document_, section_, - topic_ + topic_, sidebar_ :Children: ``title`` elements may contain text data plus `inline elements`_. @@ -3765,7 +3848,7 @@ The ``topic`` element is a nonrecursive section_-like construct which may occur at the top level of a section_ wherever a body element (list, table, etc.) is allowed. In other words, ``topic`` elements cannot nest inside body elements, so you can't have a ``topic`` inside -a ``table`` or a ``list``, or inside another ``topic``. +a ``table`` or a ``list``, or inside another ``topic`` (or sidebar_). Details @@ -4412,7 +4495,8 @@ The ``%body.elements;`` parameter entity is directly employed in the content models of the following elements: attention_, block_quote_, caution_, citation_, danger_, definition_, description_, entry_, error_, field_body_, footer_, footnote_, header_, hint_, important_, -legend_, list_item_, note_, system_message_, tip_, topic_, warning_ +legend_, list_item_, note_, sidebar_, system_message_, tip_, topic_, +warning_ Via `%structure.model;`_, the ``%body.elements;`` parameter entity is indirectly employed in the content models of the document_ and @@ -4584,17 +4668,17 @@ Entity definition: .. parsed-literal:: - ( ( (`%body.elements;`_ | topic_)+, - (transition_, (`%body.elements;`_ | topic_)+ )*, + ( ( (`%body.elements;`_ | topic_ | sidebar_)+, + (transition_, (`%body.elements;`_ | topic_ | sidebar_)+ )*, (`%section.elements;`_)* ) | (`%section.elements;`_)+ ) Each document_ or section_ contains either: -- multiple body elements and/or topics, optionally interspersed with - transitions (but transitions cannot occur at the beginning or end, - nor may there be two transitions in a row), followed by zero or more - sections; or +- multiple body elements, topics, and/or sidebars, optionally + interspersed with transitions (but transitions cannot occur at the + beginning or end, nor may there be two transitions in a row), + followed by zero or more sections; or - one or more sections (whose contents are recursively the same as this model). diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 8edc5f040..5c8857ae9 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -265,12 +265,12 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT section (title, %structure.model;)> <!ATTLIST section %basic.atts;> -<!ELEMENT sidebar (title, subtitle?, (%body.elements;)+)> -<!ATTLIST sidebar %basic.atts;> - <!ELEMENT topic (title?, (%body.elements;)+)> <!ATTLIST topic %basic.atts;> +<!ELEMENT sidebar (title, subtitle?, (%body.elements;)+)> +<!ATTLIST sidebar %basic.atts;> + <!ELEMENT transition EMPTY> <!ATTLIST transition %basic.atts;> diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index bdbd53e83..ba93d7da0 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -199,34 +199,6 @@ legend. To specify a legend without a caption, use an empty comment Body Elements --------------- -Sidebar -======= - -:Directive Type: "sidebar" -:DTD Element: sidebar -:Directive Arguments: One, required (sidebar title). -:Directive Options: Possible; optional subtitle. -:Directive Content: Interpreted as the sidebar body. - -A sidebar is like a block quote with a title, or a self-contained -section with no subsections. Use the "sidebar" directive to indicate a -self-contained idea that is separate from the flow of the document. -Sidebars may occur anywhere a section or transition may occur. Body -elements (including sidebars) may not contain nested sidebars. - -The directive's sole argument is interpreted as the sidebar title, -which may be followed by an optional subtitle; the next line must be -blank. All subsequent lines make up the sidebar body, interpreted as -body elements. For example:: - - .. sidebar:: Sidebar Title - :subtitle: Optional Sidebar Subtitle - - Subsequent indented lines comprise - the body of the sidebar, and are - interpreted as body elements. - - Topic ===== @@ -253,6 +225,43 @@ interpreted as body elements. For example:: interpreted as body elements. +Sidebar +======= + +:Directive Type: "sidebar" +:DTD Element: sidebar +:Directive Arguments: One, required (sidebar title). +:Directive Options: Possible; optional subtitle. +:Directive Content: Interpreted as the sidebar body. + +Sidebars are like miniature, parallel documents that occur inside +other documents, providing related or reference material. A sidebar +is typically offset by a border and "floats" to the side of the page; +the document's main text may flow around it. Sidebars can also be +likened to super-footnotes; their content is outside of the flow of +the document's main text. + +Sidebars may occur anywhere a section or transition may occur. Body +elements (including sidebars) may not contain nested sidebars. + +The directive's sole argument is interpreted as the sidebar title, +which may be followed by a subtitle option (see below); the next line +must be blank. All subsequent lines make up the sidebar body, +interpreted as body elements. For example:: + + .. sidebar:: Sidebar Title + :subtitle: Optional Sidebar Subtitle + + Subsequent indented lines comprise + the body of the sidebar, and are + interpreted as body elements. + +The following option is recognized: + +``subtitle`` : text + The sidebar's subtitle. + + Line Block ========== -- cgit v1.2.1 From d256fff9547aa9bb1fde01c5c495243df35157f2 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 20 Feb 2003 22:44:31 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1197 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index b97c71b7d..baa45d04e 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -3396,7 +3396,7 @@ Complete pseudo-XML_ result after parsing:: ``sidebar`` -========= +=========== Sidebars are like miniature, parallel documents that occur inside other documents, providing related or reference material. A -- cgit v1.2.1 From 3cf105681c70001de69a7bc12e5d77dee6329e61 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 22 Mar 2003 06:02:17 +0000 Subject: support & docs for character-level inline markup git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1226 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 59 ++++++++++++++++++++++++++------------- 1 file changed, 40 insertions(+), 19 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 6f260e180..819d05d3f 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -343,12 +343,16 @@ mechanism to override the default meaning of the characters used for the markup. In reStructuredText we use the backslash, commonly used as an escaping character in other domains. -A backslash followed by any character escapes that character. The -escaped character represents the character itself, and is prevented -from playing a role in any markup interpretation. The backslash is -removed from the output. A literal backslash is represented by two -backslashes in a row (the first backslash "escapes" the second, -preventing it being interpreted in an "escaping" role). +A backslash followed by any character (except whitespace characters) +escapes that character. The escaped character represents the +character itself, and is prevented from playing a role in any markup +interpretation. The backslash is removed from the output. A literal +backslash is represented by two backslashes in a row (the first +backslash "escapes" the second, preventing it being interpreted in an +"escaping" role). + +Backslash-escaped whitespace characters are removed from the document. +This allows for character-level `inline markup`_. There are two contexts in which backslashes have no special meaning: literal blocks and inline literals. In these contexts, a single @@ -2142,9 +2146,8 @@ In reStructuredText, inline markup applies to words or phrases within a text block. The same whitespace and punctuation that serves to delimit words in written text is used to delimit the inline markup syntax constructs. The text within inline markup may not begin or end -with whitespace. Arbitrary character-level markup is not supported -[#]_; it is not possible to mark up individual characters within a -word. Inline markup cannot be nested. +with whitespace. Arbitrary `character-level inline markup`_ is +supported although not encouraged. Inline markup cannot be nested. There are nine inline markup constructs. Five of the constructs use identical start-strings and end-strings to indicate the markup: @@ -2183,7 +2186,7 @@ end-string will not be recognized or processed. 4. Inline markup end-strings must end a text block or be immediately followed by whitespace or one of:: - ' " ) ] } > - / : . , ; ! ? + ' " ) ] } > - / : . , ; ! ? \ 5. If an inline markup start-string is immediately preceded by a single or double quote, "(", "[", "{", or "<", it must not be @@ -2245,17 +2248,35 @@ each character. The inline markup recognition order is as follows: - `Standalone hyperlinks`_ are the last to be recognized. -.. [#] Backslash escapes can be used to allow arbitrary text to - immediately follow inline markup:: - Python ``list``\s use square bracket syntax. +Character-Level Inline Markup +----------------------------- + +It is possible to mark up individual characters within a word with +backslash escapes (see `Escaping Mechanism`_ above). Backslash +escapes can be used to allow arbitrary text to immediately follow +inline markup:: + + Python ``list``\s use square bracket syntax. + +The backslash will disappear from the processed document. The word +"list" will appear as inline literal text, and the letter "s" will +immediately follow it as normal text, with no space in-between. + +Arbitrary text may immediately precede inline markup using +backslash-escaped whitespace:: + + Possible in *re*\ ``Structured``\ *Text*, though not encouraged. - The backslash will disappear from the processed document. The word - "list" will appear as inline literal text, and the letter "s" will - immediately follow it as normal text, with no space in-between. +The backslashes and spaces separating "re", "Structured", and "Text" +above will disappear from the processed document. + +.. CAUTION:: - There is not yet any way for arbitrary text to immediately precede - inline markup. + The use of backslash-escapes for character-level inline markup is + not encouraged. Such use is ugly and detrimental to the + unprocessed document's readability. Please use this feature + sparingly and only where absolutely necessary. Emphasis @@ -2427,7 +2448,7 @@ For example, here is a reference to a title describing a tag:: See `HTML Element: \<a>`_ below. -.. Caution:: +.. CAUTION:: This construct offers easy authoring and maintenance of hyperlinks at the expense of general readability. Inline URIs, especially -- cgit v1.2.1 From 1c87d959eb6be73667ca61bbb48d69b075a846df Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 27 Mar 2003 03:56:37 +0000 Subject: substitutions made case-sensitive but forgiving (case-insensitive fallback) git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1236 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 819d05d3f..90f19e4e1 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1893,12 +1893,14 @@ indirectly contain a circular substitution reference. `Substitution references`_ are replaced in-line by the processed contents of the corresponding definition (linked by matching -substitution text). Substitution definitions allow the power and -flexibility of block-level directives_ to be shared by inline text. -They are a way to include arbitrarily complex inline structures within -text, while keeping the details out of the flow of text. They are the -equivalent of SGML/XML's named entities or programming language -macros. +substitution text). Matches are case-sensitive but forgiving; if no +exact match is found, a case-insensitive comparison is attempted. + +Substitution definitions allow the power and flexibility of +block-level directives_ to be shared by inline text. They are a way +to include arbitrarily complex inline structures within text, while +keeping the details out of the flow of text. They are the equivalent +of SGML/XML's named entities or programming language macros. Without the substitution mechanism, every time someone wants an application-specific new inline structure, they would have to petition @@ -2270,7 +2272,7 @@ backslash-escaped whitespace:: The backslashes and spaces separating "re", "Structured", and "Text" above will disappear from the processed document. - + .. CAUTION:: The use of backslash-escapes for character-level inline markup is @@ -2540,8 +2542,9 @@ a "_" (named) or "__" (anonymous) suffix; the substitution text is used for the reference text in the named case. The processing system replaces substitution references with the -processed contents of the corresponding `substitution definitions`_. -Substitution definitions produce inline-compatible elements. +processed contents of the corresponding `substitution definitions`_ +(which see for the definition of "correspond"). Substitution +definitions produce inline-compatible elements. Examples:: -- cgit v1.2.1 From 85926fa8addd84c3d6411d73039a5bf1c6bc196d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 18 Apr 2003 21:41:59 +0000 Subject: added "figwidth" option to "figure" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1280 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 4 +++- docs/ref/rst/directives.txt | 25 +++++++++++++++++++++++-- 2 files changed, 26 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 5c8857ae9..162cf212c 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -436,7 +436,9 @@ or " ") or the text between option arguments (typically either "," or <!ATTLIST pending %basic.atts;> <!ELEMENT figure (image, ((caption, legend?) | legend)) > -<!ATTLIST figure %basic.atts;> +<!ATTLIST figure + %basic.atts; + width %number; #IMPLIED> <!-- Also an inline element. --> <!ELEMENT image EMPTY> diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index ba93d7da0..4f07cdfe8 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -116,7 +116,7 @@ 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 +Optionally, the image link block may contain a flat field list, the _`image options`. For example:: .. image:: picture.jpeg @@ -162,7 +162,7 @@ Figure :Directive Type: "figure" :DTD Elements: figure, image, caption, legend :Directive Arguments: One, required (image URI). -:Directive Options: Possible; same as those of the `image`_ directive. +:Directive Options: Possible. :Directive Content: Interpreted as the figure caption and an optional legend. @@ -194,6 +194,27 @@ There must be blank lines before the caption paragraph and before the legend. To specify a legend without a caption, use an empty comment ("..") in place of the caption. +The "figure" directive supports all of the options of the "image" +directive (see `image options`_ above). In addition, the following +option is recognized: + +``figwidth`` : integer or "image" + The width of the figure in pixels, to limit the horizontal space + used. A special value of "image" is allowed, in which case the + included image's actual width is used (requires PIL_ [#]_). If the + image file is not found or the required software is unavailable, + this option is ignored. + + Sets the "width" attribute of the "figure" DTD element. + + This option does not scale the included image; use the "width" + `image`_ option for that. + +.. [#] `Python Imaging Library`__. + +.. _PIL: +__ http://www.pythonware.com/products/pil/ + --------------- Body Elements -- cgit v1.2.1 From 4af77fded54fea37831284fd05b436b9c698cc6f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 18 Apr 2003 22:28:19 +0000 Subject: changed "DTD element" to "doctree element" git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1282 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 51 ++++++++++++++----------- docs/ref/rst/restructuredtext.txt | 79 ++++++++++++++++++++------------------- 2 files changed, 69 insertions(+), 61 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 4f07cdfe8..a5b675ad8 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -6,6 +6,8 @@ :Revision: $Revision$ :Date: $Date$ +.. contents:: + This document describes the directives implemented in the reference reStructuredText parser. @@ -26,11 +28,16 @@ content (in that order), any of which may appear. See the Directives_ section in the `reStructuredText Markup Specification`_ for syntax details. +Descriptions below list "doctree elements" (document tree element +names; XML DTD generic identifiers) corresponding to individual +directives. For details on the hierarchy of elements, please see +`Docutils Document Tree Structure`_ and the `Generic Plaintext +Document Interface DTD`_ XML document type definition. + .. _Directives: ./reStructuredText.html#directives .. _reStructuredText Markup Specification: ./reStructuredText.html - - -.. contents:: +.. _Docutils Document Tree Structure: ../doctree.html +.. _Generic Plaintext Document Interface DTD: ../gpdi.dtd ------------- @@ -39,8 +46,8 @@ details. :Directive Types: "attention", "caution", "danger", "error", "hint", "important", "note", "tip", "warning" -:DTD Elements: attention, caution, danger, error, hint, important, - note, tip, warning +:Doctree Elements: attention, caution, danger, error, hint, important, + note, tip, warning :Directive Arguments: None. :Directive Options: None. :Directive Content: Interpreted as body elements. @@ -99,7 +106,7 @@ Image ===== :Directive Type: "image" -:DTD Element: image +:Doctree Element: image :Directive Arguments: One, required (image URI). :Directive Options: Possible. :Directive Content: None. @@ -160,7 +167,7 @@ Figure ====== :Directive Type: "figure" -:DTD Elements: figure, image, caption, legend +:Doctree Elements: figure, image, caption, legend :Directive Arguments: One, required (image URI). :Directive Options: Possible. :Directive Content: Interpreted as the figure caption and an optional @@ -205,7 +212,7 @@ option is recognized: image file is not found or the required software is unavailable, this option is ignored. - Sets the "width" attribute of the "figure" DTD element. + Sets the "width" attribute of the "figure" doctree element. This option does not scale the included image; use the "width" `image`_ option for that. @@ -224,7 +231,7 @@ Topic ===== :Directive Type: "topic" -:DTD Element: topic +:Doctree Element: topic :Directive Arguments: 1, required (topic title). :Directive Options: None. :Directive Content: Interpreted as the topic body. @@ -250,7 +257,7 @@ Sidebar ======= :Directive Type: "sidebar" -:DTD Element: sidebar +:Doctree Element: sidebar :Directive Arguments: One, required (sidebar title). :Directive Options: Possible; optional subtitle. :Directive Content: Interpreted as the sidebar body. @@ -287,7 +294,7 @@ Line Block ========== :Directive Type: "line-block" -:DTD Element: line_block +:Doctree Element: line_block :Directive Arguments: None. :Directive Options: None. :Directive Content: Becomes the body of the line block. @@ -318,7 +325,7 @@ Parsed Literal Block ==================== :Directive Type: "parsed-literal" -:DTD Element: literal_block +:Doctree Element: literal_block :Directive Arguments: None. :Directive Options: None. :Directive Content: Becomes the body of the literal block. @@ -351,7 +358,7 @@ Table of Contents ================= :Directive Type: "contents" -:DTD Elements: pending, topic +:Doctree Elements: pending, topic :Directive Arguments: One, optional: title. :Directive Options: Possible. :Directive Content: None. @@ -407,7 +414,7 @@ Automatic Section Numbering =========================== :Directive Type: "sectnum" or "section-autonumbering" (synonyms) -:DTD Elements: pending, generated +:Doctree Elements: pending, generated :Directive Arguments: None. :Directive Options: Possible. :Directive Content: None. @@ -441,7 +448,7 @@ Target Footnotes ================ :Directive Type: "target-notes" -:DTD Elements: pending, footnote, footnote_reference +:Doctree Elements: pending, footnote, footnote_reference :Directive Arguments: None. :Directive Options: None. :Directive Content: None. @@ -459,7 +466,7 @@ Footnotes **NOT IMPLEMENTED YET** :Directive Type: "footnotes" -:DTD Elements: pending, topic +:Doctree Elements: pending, topic :Directive Arguments: None? :Directive Options: Possible? :Directive Content: None. @@ -473,7 +480,7 @@ Citations **NOT IMPLEMENTED YET** :Directive Type: "citations" -:DTD Elements: pending, topic +:Doctree Elements: pending, topic :Directive Arguments: None? :Directive Options: Possible? :Directive Content: None. @@ -489,7 +496,7 @@ Meta ==== :Directive Type: "meta" -:DTD Element: meta (non-standard) +:Doctree Element: meta (non-standard) :Directive Arguments: None. :Directive Options: None. :Directive Content: Must contain a flat field list. @@ -557,7 +564,7 @@ Including an External Document Fragment ======================================= :Directive Type: "include" -:DTD Elements: depend on data being included +:Doctree Elements: depend on data being included :Directive Arguments: One, required (path to include file). :Directive Options: Possible. :Directive Content: None. @@ -596,7 +603,7 @@ Raw Data Pass-Through ===================== :Directive Type: "raw" -:DTD Element: pending +:Doctree Element: pending :Directive Arguments: One, required (output format type). :Directive Options: Possible. :Directive Content: Stored verbatim, uninterpreted. None (empty) if a @@ -642,7 +649,7 @@ Replacement Text ================ :Directive Type: "replace" -:DTD Element: pending +:Doctree Element: pending :Directive Arguments: None. :Directive Options: None. :Directive Content: A single paragraph; may contain inline markup. @@ -671,7 +678,7 @@ Restructuredtext-Test-Directive =============================== :Directive Type: "restructuredtext-test-directive" -:DTD Element: system_warning +:Doctree Element: system_warning :Directive Arguments: None. :Directive Options: None. :Directive Content: Interpreted as a literal block. diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 90f19e4e1..d714635a6 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -207,11 +207,11 @@ Here are examples of `body elements`_: Syntax Details ---------------- -Descriptions below list "DTD elements" (XML "generic identifiers") -corresponding to syntax constructs. For details on the hierarchy of -elements, please see `Docutils Document Tree Structure`_ and the -`Generic Plaintext Document Interface DTD`_ XML document type -definition. +Descriptions below list "doctree elements" (document tree element +names; XML DTD generic identifiers) corresponding to syntax +constructs. For details on the hierarchy of elements, please see +`Docutils Document Tree Structure`_ and the `Generic Plaintext +Document Interface DTD`_ XML document type definition. Whitespace @@ -425,7 +425,7 @@ Document Structure Document -------- -DTD element: document. +Doctree element: document. The top-level element of a parsed reStructuredText document is the "document" element. After initial parsing, the document element is a @@ -448,7 +448,7 @@ the "document title" can become the document subtitle. See the Sections -------- -DTD elements: section, title. +Doctree elements: section, title. Sections are identified through their titles, which are marked up with adornment: "underlines" below the title text, or underlines and @@ -542,7 +542,7 @@ sections. Transitions ----------- -DTD element: transition. +Doctree element: transition. Instead of subheads, extra space or a type ornament between paragraphs may be used to mark text divisions or to signal @@ -582,7 +582,7 @@ Body Elements Paragraphs ---------- -DTD element: paragraph. +Doctree element: paragraph. Paragraphs consist of blocks of left-aligned text with no markup indicating any other body element. Blank lines separate paragraphs @@ -605,7 +605,7 @@ Syntax diagram:: Bullet Lists ------------ -DTD elements: bullet_list, list_item. +Doctree elements: bullet_list, list_item. A text block which begins with a "-", "*", or "+", followed by whitespace, is a bullet list item (a.k.a. "unordered" list item). @@ -654,7 +654,7 @@ Syntax diagram:: Enumerated Lists ---------------- -DTD elements: enumerated_list, list_item. +Doctree elements: enumerated_list, list_item. Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists, but use enumerators instead of bullets. An enumerator consists of an @@ -734,8 +734,8 @@ Example syntax diagram:: Definition Lists ---------------- -DTD elements: definition_list, definition_list_item, term, classifier, -definition. +Doctree elements: definition_list, definition_list_item, term, +classifier, definition. Each definition list item contains a term, an optional classifier, and a definition. A term is a simple one-line word or phrase. An @@ -788,7 +788,7 @@ Syntax diagram:: Field Lists ----------- -DTD elements: field_list, field, field_name, field_body. +Doctree elements: field_list, field, field_name, field_body. Field lists are used as part of an extension syntax, such as options for directives_, or database-like records meant for further @@ -845,7 +845,7 @@ Syntax diagram (simplified):: Bibliographic Fields ```````````````````` -DTD elements: docinfo, author, authors, organization, contact, +Doctree elements: docinfo, author, authors, organization, contact, version, status, date, copyright, field, topic. When a field list is the first non-comment element in a document @@ -855,7 +855,7 @@ corresponds to the front matter of a book, such as the title page and copyright page. Certain registered field names (listed below) are recognized and -transformed to the corresponding DTD elements, most becoming child +transformed to the corresponding doctree elements, most becoming child elements of the "docinfo" element. No ordering is required of these fields, although they may be rearranged to fit the document structure, as noted. Unless otherwise indicated below, each of the bibliographic @@ -864,8 +864,8 @@ bodies may be checked for `RCS keywords`_ and cleaned up. Any unrecognized fields will remain as generic fields in the docinfo element. -The registered bibliographic field names and their corresponding DTD -elements are as follows: +The registered bibliographic field names and their corresponding +doctree elements are as follows: - Field name "Author": author element. - "Authors": authors. @@ -941,7 +941,7 @@ hold: Option Lists ------------ -DTD elements: option_list, option_list_item, option_group, option, +Doctree elements: option_list, option_list_item, option_group, option, option_string, option_argument, description. Option lists are two-column lists of command-line options and @@ -1025,7 +1025,7 @@ Syntax diagram (simplified):: Literal Blocks -------------- -DTD element: literal_block. +Doctree element: literal_block. A paragraph consisting of two colons ("::") signifies that all following **indented** text blocks comprise a literal block. No @@ -1098,7 +1098,7 @@ Syntax diagram:: Block Quotes ------------ -DTD element: block_quote. +Doctree element: block_quote. A text block that is indented relative to the preceding text, without markup indicating it to be a literal block, is a block quote. All @@ -1129,7 +1129,7 @@ Syntax diagram:: Doctest Blocks -------------- -DTD element: doctest_block. +Doctree element: doctest_block. Doctest blocks are interactive Python sessions cut-and-pasted into docstrings. They are meant to illustrate usage by example, and @@ -1159,7 +1159,7 @@ Indentation is not required for doctest blocks. Tables ------ -DTD elements: table, tgroup, colspec, thead, tbody, row, entry. +Doctree elements: table, tgroup, colspec, thead, tbody, row, entry. ReStructuredText provides two syntaxes for delineating table cells: `Grid Tables`_ and `Simple Tables`_. @@ -1377,7 +1377,7 @@ targets, directives, substitution definitions, and comments. Footnotes ````````` -DTD elements: footnote, label. +Doctree elements: footnote, label. Each footnote consists of an explicit markup start (".. "), a left square bracket, the footnote label, a right square bracket, and @@ -1562,7 +1562,7 @@ differently from footnotes. For example:: Hyperlink Targets ````````````````` -DTD element: target. +Doctree element: target. These are also called _`explicit hyperlink targets`, to differentiate them from `implicit hyperlink targets`_ defined below. @@ -1772,7 +1772,7 @@ require attention to the order of corresponding targets. Directives `````````` -DTD elements: depend on the directive. +Doctree elements: depend on the directive. Directives are an extension mechanism for reStructuredText, a way of adding support for new constructs without adding new syntax. All @@ -1874,7 +1874,7 @@ Syntax diagram:: Substitution Definitions ```````````````````````` -DTD element: substitution_definition. +Doctree element: substitution_definition. Substitution definitions are indicated by an explicit markup start (".. ") followed by a vertical bar, the substitution text, another @@ -2070,7 +2070,7 @@ Replacement text Comments ```````` -DTD element: comment. +Doctree element: comment. Arbitrary indented text may follow the explicit markup start and will be processed as a comment element. No further processing is done on @@ -2284,7 +2284,7 @@ above will disappear from the processed document. Emphasis -------- -DTD element: emphasis. +Doctree element: emphasis. Start-string = end-string = "*". @@ -2298,7 +2298,7 @@ Emphasized text is typically displayed in italics. Strong Emphasis --------------- -DTD element: strong. +Doctree element: strong. Start-string = end-string = "**". @@ -2312,7 +2312,8 @@ Strongly emphasized text is typically displayed in boldface. Interpreted Text ---------------- -DTD element: depends on the explicit or implicit role and processing. +Doctree element: depends on the explicit or implicit role and +processing. Start-string = end-string = "`". @@ -2350,7 +2351,7 @@ specialized roles. Inline Literals --------------- -DTD element: literal. +Doctree element: literal. Start-string = end-string = "``". @@ -2379,7 +2380,7 @@ Inline literals are useful for short code snippets. For example:: Hyperlink References -------------------- -DTD element: reference. +Doctree element: reference. - Named hyperlink references: @@ -2464,7 +2465,7 @@ For example, here is a reference to a title describing a tag:: Inline Internal Targets ------------------------ -DTD element: target. +Doctree element: target. Start-string = "_`", end-string = "`". @@ -2486,7 +2487,7 @@ reference names. Footnote References ------------------- -DTD element: footnote_reference. +Doctree element: footnote_reference. Start-string = "[", end-string = "]_". @@ -2512,7 +2513,7 @@ For example:: Citation References ------------------- -DTD element: citation_reference. +Doctree element: citation_reference. Start-string = "[", end-string = "]_". @@ -2531,7 +2532,7 @@ See Citations_ for the citation itself. Substitution References ----------------------- -DTD element: substitution_reference, reference. +Doctree element: substitution_reference, reference. Start-string = "|", end-string = "|" (optionally followed by "_" or "__"). @@ -2559,7 +2560,7 @@ Examples:: Standalone Hyperlinks --------------------- -DTD element: reference. +Doctree element: reference. Start-string = end-string = "" (empty string). @@ -2623,7 +2624,7 @@ Punctuation at the end of a URI is not considered part of the URI. Error Handling ---------------- -DTD element: system_message, problematic. +Doctree element: system_message, problematic. Markup errors are handled according to the specification in `PEP 258`_. -- cgit v1.2.1 From 027e6b5d677f682cf20e3ba3dd38c4511d02e14b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 18 Apr 2003 22:33:29 +0000 Subject: corrected ref titles git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1283 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 6 +++--- docs/ref/rst/restructuredtext.txt | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index a5b675ad8..e4f5b15cb 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -30,9 +30,9 @@ details. Descriptions below list "doctree elements" (document tree element names; XML DTD generic identifiers) corresponding to individual -directives. For details on the hierarchy of elements, please see -`Docutils Document Tree Structure`_ and the `Generic Plaintext -Document Interface DTD`_ XML document type definition. +directives. For details on the hierarchy of elements, please see `The +Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document +type definition. .. _Directives: ./reStructuredText.html#directives .. _reStructuredText Markup Specification: ./reStructuredText.html diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index d714635a6..3361762b7 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -209,9 +209,9 @@ Here are examples of `body elements`_: Descriptions below list "doctree elements" (document tree element names; XML DTD generic identifiers) corresponding to syntax -constructs. For details on the hierarchy of elements, please see -`Docutils Document Tree Structure`_ and the `Generic Plaintext -Document Interface DTD`_ XML document type definition. +constructs. For details on the hierarchy of elements, please see `The +Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document +type definition. Whitespace -- cgit v1.2.1 From b9ac2d2023345f155a457fece4e1e68042c6206a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 23 Apr 2003 23:39:40 +0000 Subject: fixed reference names git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1287 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 4 ++-- docs/ref/rst/restructuredtext.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index e4f5b15cb..8f142f110 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -36,8 +36,8 @@ type definition. .. _Directives: ./reStructuredText.html#directives .. _reStructuredText Markup Specification: ./reStructuredText.html -.. _Docutils Document Tree Structure: ../doctree.html -.. _Generic Plaintext Document Interface DTD: ../gpdi.dtd +.. _The Docutils Document Tree: ../doctree.html +.. _Docutils Generic DTD: ../gpdi.dtd ------------- diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 3361762b7..09ae893f7 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2632,8 +2632,8 @@ Markup errors are handled according to the specification in `PEP .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _Docutils: http://docutils.sourceforge.net/ -.. _Docutils Document Tree Structure: ../doctree.html -.. _Generic Plaintext Document Interface DTD: ../gpdi.dtd +.. _The Docutils Document Tree: ../doctree.html +.. _Docutils Generic DTD: ../gpdi.dtd .. _transforms: http://docutils.sourceforge.net/docutils/transforms/ .. _Grouch: http://www.mems-exchange.org/software/grouch/ -- cgit v1.2.1 From e95205d5c5b9aef0c7742a47e4c97213e844dffd Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 9 May 2003 13:06:43 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1307 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 9 +++++++++ docs/ref/rst/directives.txt | 23 +++++++++++++++++++---- 2 files changed, 28 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 162cf212c..3fec9ed4e 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -536,6 +536,15 @@ following caveats: <!ELEMENT acronym %text.model;> <!ATTLIST acronym %basic.atts;> +<!ELEMENT superscript %text.model;> +<!ATTLIST superscript %basic.atts;> + +<!ELEMENT subscript %text.model;> +<!ATTLIST subscript %basic.atts;> + +<!ELEMENT phrase %text.model;> +<!ATTLIST phrase %basic.atts;> + <!ELEMENT problematic %text.model;> <!ATTLIST problematic %basic.atts; diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 8f142f110..6dc607fed 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -215,12 +215,27 @@ option is recognized: Sets the "width" attribute of the "figure" doctree element. This option does not scale the included image; use the "width" - `image`_ option for that. - -.. [#] `Python Imaging Library`__. + `image`_ option for that. :: + + +---------------------------+ + | figure | + | | + |<------ figwidth --------->| + | | + | +---------------------+ | + | | image | | + | | | | + | |<--- width --------->| | + | +---------------------+ | + | | + |The figure's caption should| + |wrap at this width. | + +---------------------------+ + +.. [#] `Python Imaging Library`_. .. _PIL: -__ http://www.pythonware.com/products/pil/ +.. _Python Imaging Library: http://www.pythonware.com/products/pil/ --------------- -- cgit v1.2.1 From 776fa1e839b809608473c8270f23f33a48af5e22 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 May 2003 20:49:39 +0000 Subject: Added "sidebar", "rubric", "attribution", "admonition", "superscript", "subscript", and "inline" elements. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1337 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 3fec9ed4e..06fe4bf55 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -116,11 +116,11 @@ resolve to either an internal or external reference. <!ENTITY % additional.body.elements ""> <!ENTITY % body.elements " paragraph | literal_block | doctest_block | line_block | block_quote - | table | figure | image | footnote | citation + | table | figure | image | footnote | citation | rubric | bullet_list | enumerated_list | definition_list | field_list | option_list | attention | caution | danger | error | hint | important | note - | tip | warning + | tip | warning | admonition | target | substitution_definition | comment | pending | system_message | raw %additional.body.elements; "> @@ -130,8 +130,8 @@ resolve to either an internal or external reference. " emphasis | strong | literal | reference | footnote_reference | citation_reference | substitution_reference | title_reference - | abbreviation | acronym - | problematic | generated + | abbreviation | acronym | subscript | superscript + | inline | problematic | generated | target | image | raw %additional.inline.elements; "> @@ -368,9 +368,12 @@ or " ") or the text between option arguments (typically either "," or %basic.atts; %fixedspace.att;> -<!ELEMENT block_quote (%body.elements;)+> +<!ELEMENT block_quote ((%body.elements;)+, attribution?)> <!ATTLIST block_quote %basic.atts;> +<!ELEMENT attribution %text.model;> +<!ATTLIST attribution %basic.atts;> + <!ELEMENT doctest_block %text.model;> <!ATTLIST doctest_block %basic.atts; @@ -403,6 +406,9 @@ or " ") or the text between option arguments (typically either "," or <!ELEMENT warning (%body.elements;)+> <!ATTLIST warning %basic.atts;> +<!ELEMENT admonition (title, (%body.elements;)+)> +<!ATTLIST admonition %basic.atts;> + <!ELEMENT footnote (label?, (%body.elements;)+)> <!ATTLIST footnote %basic.atts; @@ -417,6 +423,9 @@ or " ") or the text between option arguments (typically either "," or <!ELEMENT label (#PCDATA)> <!ATTLIST label %basic.atts;> +<!ELEMENT rubric %text.model;> +<!ATTLIST rubric %basic.atts;> + <!-- Empty except when used as an inline element. --> <!ELEMENT target %text.model;> <!ATTLIST target @@ -542,8 +551,8 @@ following caveats: <!ELEMENT subscript %text.model;> <!ATTLIST subscript %basic.atts;> -<!ELEMENT phrase %text.model;> -<!ATTLIST phrase %basic.atts;> +<!ELEMENT inline %text.model;> +<!ATTLIST inline %basic.atts;> <!ELEMENT problematic %text.model;> <!ATTLIST problematic -- cgit v1.2.1 From b84157853aab34be40f1668f0bdecfe7ec503c36 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 May 2003 20:50:07 +0000 Subject: Added directives: "admonition", "rubric", "epigraph", "highlights", "unicode" and "class". Added "class" options to "topic", "sidebar", "line-block", "parsed-literal", "contents", and "image"; and "figclass" to "figure". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1338 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 247 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 233 insertions(+), 14 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 6dc607fed..0dfb52337 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -44,10 +44,13 @@ type definition. Admonitions ------------- +Specific Admonitions +==================== + :Directive Types: "attention", "caution", "danger", "error", "hint", - "important", "note", "tip", "warning" + "important", "note", "tip", "warning", "admonition" :Doctree Elements: attention, caution, danger, error, hint, important, - note, tip, warning + note, tip, warning, admonition, title :Directive Arguments: None. :Directive Options: None. :Directive Content: Interpreted as body elements. @@ -95,6 +98,43 @@ bullet list consisting of two list items:: - It includes this bullet list. +Generic Admonition +================== + +:Directive Type: "admonition" +:Doctree Elements: admonition, title +:Directive Arguments: One, required (admonition title) +:Directive Options: Possible. +:Directive Content: Interpreted as body elements. + +This is a generic, titled admonition. The title may be anything the +author desires. + +The author-supplied title is also used as a "class" attribute value +after being converted into a valid identifier form (down-cased; +non-alphanumeric characters converted to single hyphens; "admonition-" +prefixed). For example, this admonition:: + + .. admonition:: And, by the way... + + You can make up your own admonition too. + +becomes the following document tree (pseudo-XML):: + + <document source="test data"> + <admonition class="admonition-and-by-the-way"> + <title> + And, by the way... + <paragraph> + You can make up your own admonition too. + +The following option is recognized: + +``class`` : text + Override the computed "class" attribute value. See the class_ + directive below. + + -------- Images -------- @@ -162,6 +202,10 @@ The following options are recognized: text flow around it. The specific behavior depends upon the browser or rendering software used. +``class`` : text + Set a "class" attribute value on the image element. See the + class_ directive below. + Figure ====== @@ -203,7 +247,7 @@ legend. To specify a legend without a caption, use an empty comment The "figure" directive supports all of the options of the "image" directive (see `image options`_ above). In addition, the following -option is recognized: +options are recognized: ``figwidth`` : integer or "image" The width of the figure in pixels, to limit the horizontal space @@ -232,6 +276,10 @@ option is recognized: |wrap at this width. | +---------------------------+ +``figclass`` : text + Set a "class" attribute value on the figure element. See the + class_ directive below. + .. [#] `Python Imaging Library`_. .. _PIL: @@ -248,7 +296,7 @@ Topic :Directive Type: "topic" :Doctree Element: topic :Directive Arguments: 1, required (topic title). -:Directive Options: None. +:Directive Options: Possible. :Directive Content: Interpreted as the topic body. A topic is like a block quote with a title, or a self-contained @@ -267,6 +315,12 @@ interpreted as body elements. For example:: the body of the topic, and are interpreted as body elements. +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the topic element. See the + class_ directive below. + Sidebar ======= @@ -274,7 +328,7 @@ Sidebar :Directive Type: "sidebar" :Doctree Element: sidebar :Directive Arguments: One, required (sidebar title). -:Directive Options: Possible; optional subtitle. +:Directive Options: Possible. :Directive Content: Interpreted as the sidebar body. Sidebars are like miniature, parallel documents that occur inside @@ -299,11 +353,15 @@ interpreted as body elements. For example:: the body of the sidebar, and are interpreted as body elements. -The following option is recognized: +The following options are recognized: ``subtitle`` : text The sidebar's subtitle. +``class`` : text + Set a "class" attribute value on the sidebar element. See the + class_ directive below. + Line Block ========== @@ -311,7 +369,7 @@ Line Block :Directive Type: "line-block" :Doctree Element: line_block :Directive Arguments: None. -:Directive Options: None. +:Directive Options: Possible. :Directive Content: Becomes the body of the line block. The "line-block" directive constructs an element where whitespace @@ -335,6 +393,12 @@ example, here's a classic:: as soon as it comes. Love, Ewan. +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the line_block element. See the + class_ directive below. + Parsed Literal Block ==================== @@ -342,7 +406,7 @@ Parsed Literal Block :Directive Type: "parsed-literal" :Doctree Element: literal_block :Directive Arguments: None. -:Directive Options: None. +:Directive Options: Possible. :Directive Content: Becomes the body of the literal block. Unlike an ordinary literal block, the "parsed-literal" directive @@ -364,6 +428,76 @@ For example, all the element names in this content model are links:: decoration_?, `%structure.model;`_) +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the literal_block element. See + the class_ directive below. + + +Rubric +====== + +:Directive Type: "rubric" +:Doctree Element: rubric +:Directive Arguments: 1, required (rubric text). +:Directive Options: Possible. +:Directive Content: None. + + rubric n. 1. a title, heading, or the like, in a manuscript, + book, statute, etc., written or printed in red or otherwise + distinguished from the rest of the text. ... + + -- Random House Webster's College Dictionary, 1991 + +The "rubric" directive inserts a "rubric" element into the document +tree. A rubric is like an informal heading that doesn't correspond to +the document's structure. + +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the rubric element. See the + class_ directive below. + + +Epigraph +======== + +:Directive Type: "epigraph" +:Doctree Element: block_quote +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Interpreted as the body of the block quote. + +Produces an epigraph-class block quote. For example, this input:: + + .. epigraph:: + + No matter where you go, there you are. + + -- Buckaroo Banzai + +becomes this document tree fragment:: + + <block_quote class="epigraph"> + <paragraph> + No matter where you go, there you are. + <attribution> + Buckaroo Banzai + + +Highlights +======== + +:Directive Type: "highlights" +:Doctree Element: block_quote +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Interpreted as the body of the block quote. + +Produces a highlights-class block quote. See Epigraph_ above. + ---------------- Document Parts @@ -416,14 +550,20 @@ The following options are recognized: ``depth`` : integer The number of section levels that are collected in the table of contents. The default is unlimited depth. + ``local`` : flag (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. + ``backlinks`` : "entry" or "top" or "none" Generate links from section headers back to the table of contents entries, the table of contents itself, or generate no backlinks. +``class`` : text + Set a "class" attribute value on the topic element. See the + class_ directive below. + Automatic Section Numbering =========================== @@ -618,7 +758,7 @@ Raw Data Pass-Through ===================== :Directive Type: "raw" -:Doctree Element: pending +:Doctree Element: raw :Directive Arguments: One, required (output format type). :Directive Options: Possible. :Directive Content: Stored verbatim, uninterpreted. None (empty) if a @@ -626,10 +766,9 @@ Raw Data Pass-Through 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 first argument. 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. +given in the first argument. The interpretation of the raw data 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:: @@ -664,7 +803,7 @@ Replacement Text ================ :Directive Type: "replace" -:Doctree Element: pending +:Doctree Element: Text & inline elements :Directive Arguments: None. :Directive Options: None. :Directive Content: A single paragraph; may contain inline markup. @@ -689,6 +828,86 @@ the "replace" directive:: .. _Python: http://www.python.org/ +Unicode Character Codes +======================= + +:Directive Type: "unicode" +:Doctree Element: Text +:Directive Arguments: One or more, required (Unicode character codes + & text). +:Directive Options: None. +:Directive Content: None. + +The "unicode" directive converts Unicode character codes (numerical +values) to characters, and may be used in substitution definitions +only. Codes may be decimal numbers, hexadecimal numbers (prefixed by +``0x``, ``x``, ``\x``, ``u``, or ``\u``), or XML-style numbered +character entities (e.g. ``ᨫ``). Codes may be upper- or +lowercase. Spaces are ignored, and any other text remains as-is. + +Example:: + + "|copy|" is the copyright symbol. + + .. |copy| unicode:: 0xA9 + + +Class +===== + +:Directive Type: "class" +:Doctree Element: pending +:Directive Arguments: One, required (class name / attribute value). +:Directive Options: None. +:Directive Content: None. + +The "class" directive sets a "class" attribute value on the first +immediately following non-comment element [#]_. For details of the +"class" attribute, see `its entry`__ in `The Docutils Document Tree`_. +The "class" attribute value is converted to lowercase and all +non-alphanumeric characters are converted to hyphens in order to match +this regular expression: ``[a-z](-?[a-z0-9]+)*``. See the docstring +from ``docutils.nodes.make_id`` for the rationale. + +Examples:: + + .. class:: special + + This is a "special" paragraph. + + .. class:: exceptional + + An Exceptional Section + ====================== + + This is an ordinary paragraph. + +The text above is parsed and transformed into this doctree fragment:: + + <paragraph class="special"> + This is a "special" paragraph. + <section class="exceptional"> + <title> + An Exceptional Section + <paragraph> + This is an ordinary paragraph. + +.. [#] To set a "class" attribute value on a block quote, the "class" + directive must be followed by an empty comment:: + + .. class:: highlights + .. + + Block quote text. + + The directive doesn't allow content, therefore an empty comment is + required to terminate the directive. Without the empty comment, + the block quote text would be interpreted as the "class" + directive's content, and the parser would complain. + +__ ../doctree.html#class + + Restructuredtext-Test-Directive =============================== -- cgit v1.2.1 From e8c6ddb8ee857e0387997db70b0786243465b84b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 May 2003 20:54:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1340 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 186 +++++++++++++++++++++++++++++++------- docs/ref/rst/restructuredtext.txt | 12 ++- docs/ref/transforms.txt | 2 + 3 files changed, 165 insertions(+), 35 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index baa45d04e..285bb9c98 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -140,12 +140,13 @@ Body elements are contained within structural elements and compound body elements. There are two subcategories of body elements: simple and compound. -Category members: attention_, block_quote_, bullet_list_, caution_, -citation_, comment_, danger_, definition_list_, doctest_block_, -enumerated_list_, error_, field_list_, figure_, footnote_, hint_, -image_, important_, line_block_, literal_block_, note_, option_list_, -paragraph_, pending_, raw_, substitution_definition_, -system_message_, table_, target_, tip_, warning_ +Category members: admonition_, attention_, block_quote_, bullet_list_, +caution_, citation_, comment_, danger_, definition_list_, +doctest_block_, enumerated_list_, error_, field_list_, figure_, +footnote_, hint_, image_, important_, line_block_, literal_block_, +note_, option_list_, paragraph_, pending_, raw_, rubric_, +substitution_definition_, system_message_, table_, target_, tip_, +warning_ Simple Body Elements @@ -156,8 +157,8 @@ that contain text data may also contain inline elements. Such elements therefore have a "mixed content model". Category members: comment_, doctest_block_, image_, line_block_, -literal_block_, paragraph_, pending_, raw_, substitution_definition_, -target_ +literal_block_, paragraph_, pending_, raw_, rubric_, +substitution_definition_, target_ Compound Body Elements @@ -166,9 +167,9 @@ Compound Body Elements Compound body elements contain local substructure (body subelements) and further body elements. They do not directly contain text data. -Category members: attention_, block_quote_, bullet_list_, caution_, -citation_, danger_, definition_list_, enumerated_list_, error_, -field_list_, figure_, footnote_, hint_, important_, note_, +Category members: admonition_, attention_, block_quote_, bullet_list_, +caution_, citation_, danger_, definition_list_, enumerated_list_, +error_, field_list_, figure_, footnote_, hint_, important_, note_, option_list_, system_message_, table_, tip_, warning_ @@ -182,8 +183,8 @@ elements (containing text data, like field_name_). These subelements always occur within specific parent elements, never at the body element level (beside paragraphs, etc.). -Category members (simple): caption_, classifier_, colspec_, -field_name_, label_, option_argument_, option_string_, term_ +Category members (simple): attribution_, caption_, classifier_, +colspec_, field_name_, label_, option_argument_, option_string_, term_ Category members (compound): definition_, definition_list_item_, description_, entry_, field_, field_body_, legend_, list_item_, @@ -199,9 +200,9 @@ further inline elements. Inline elements are contained within simple body elements. Most inline elements have a "mixed content model". Category members: abbreviation_, acronym_, citation_reference_, -emphasis_, footnote_reference_, generated_, image_, literal_, -problematic_, reference_, strong_, substitution_reference_, target_, -title_reference_, raw_ +emphasis_, footnote_reference_, generated_, image_, inline_, literal_, +problematic_, reference_, strong_, subscript_, +substitution_reference_, superscript_, target_, title_reference_, raw_ .. _HTML: http://www.w3.org/MarkUp/ @@ -340,7 +341,6 @@ Content Model ``address``. - Examples -------- @@ -366,13 +366,79 @@ See docinfo_ for a more complete example, including processing context. +``admonition`` +============== + +This element is a generic, titled admonition. Also see the specific +admonition elements Docutils offers (in alphabetical order): caution_, +danger_, error_, hint_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``admonition``. + +:Children: + ``admonition`` elements begin with a title_ and may contain one or + more `body elements`_. + +:Analogues: + ``admonition`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.). + + +Content Model +------------- + +.. parsed-literal:: + + (title_, (`%body.elements;`_)+) + +:Attributes: + The ``admonition`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``admonition``. The `%structure.model;`_ parameter entity + indirectly includes ``admonition``. + + +Examples +-------- + +reStructuredText source:: + + .. admonition:: And, by the way... + + You can make up your own admonition too. + +Pseudo-XML_ fragment from simple parsing:: + + <admonition class="admonition-and-by-the-way"> + <title> + And, by the way... + <paragraph> + You can make up your own admonition too. + + ``attention`` ============= The ``attention`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): caution_, danger_, error_, -hint_, important_, note_, tip_, warning_. +hint_, important_, note_, tip_, warning_, and the generic admonition_. Details @@ -429,6 +495,12 @@ Pseudo-XML_ fragment from simple parsing:: All your base are belong to us. +``attribution`` +=============== + +`To be completed`_. + + ``author`` ========== @@ -586,7 +658,8 @@ Details may contain ``block_quote``. :Children: - ``block_quote`` elements may contain `body elements`_. + ``block_quote`` elements contain `body elements`_ followed by an + optional attribution_ element. :Analogues: ``block_quote`` is analogous to the "blockquote" element in both @@ -602,7 +675,7 @@ Content Model .. parsed-literal:: - (`%body.elements;`_)+ + ((`%body.elements;`_)+, attribution_?) :Attributes: The ``block_quote`` element contains only the `common @@ -730,7 +803,7 @@ See list_item_ for another example. The ``caution`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, danger_, error_, -hint_, important_, note_, tip_, warning_. +hint_, important_, note_, tip_, warning_, and the generic admonition_. Details @@ -1021,7 +1094,7 @@ context. The ``danger`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, caution_, error_, -hint_, important_, note_, tip_, warning_. +hint_, important_, note_, tip_, warning_, and the generic admonition_. Details @@ -1856,7 +1929,8 @@ See list_item_ for another example. The ``error`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, caution_, -danger_, hint_, important_, note_, tip_, warning_. +danger_, hint_, important_, note_, tip_, warning_, and the generic +admonition_. Details @@ -2277,7 +2351,8 @@ None. The ``hint`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, important_, note_, tip_, warning_. +danger_, error_, important_, note_, tip_, warning_, and the generic +admonition_. Details @@ -2346,7 +2421,8 @@ Pseudo-XML_ fragment from simple parsing:: The ``important`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, hint_, note_, tip_, warning_. +danger_, error_, hint_, note_, tip_, warning_, and the generic +admonition_. Details @@ -2418,6 +2494,12 @@ Pseudo-XML_ fragment from simple parsing:: Call your mother. +``inline`` +========== + +`To be completed`_. + + ``label`` ========= @@ -2686,7 +2768,8 @@ Pseudo-XML_ fragment from simple parsing:: The ``note`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, hint_, important_, tip_, warning_. +danger_, error_, hint_, important_, tip_, warning_, and the generic +admonition_. Details @@ -3299,6 +3382,21 @@ context. `To be completed`_. +``rubric`` +========== + + rubric n. 1. a title, heading, or the like, in a manuscript, + book, statute, etc., written or printed in red or otherwise + distinguished from the rest of the text. ... + + -- Random House Webster's College Dictionary, 1991 + +A rubric is like an informal heading that doesn't correspond to the +document's structure. + +`To be completed`_. + + ``section`` =========== @@ -3549,6 +3647,12 @@ context. `To be completed`_. +``subscript`` +============= + +`To be completed`_. + + ``substitution_definition`` =========================== @@ -3630,6 +3734,12 @@ structural element (document), the subsection's ``id`` and ``name`` attributes are stored in the ``subtitle`` element. +``superscript`` +=============== + +`To be completed`_. + + ``system_message`` ================== @@ -3718,7 +3828,7 @@ classifier_ elements. The ``tip`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, caution_, danger_, error_, hint_, -important_, note_, warning_. +important_, note_, warning_, and the generic admonition_. Details @@ -3778,7 +3888,7 @@ Pseudo-XML_ fragment from simple parsing:: ========= The ``title`` element stores the title of a document_, section_, -topic_, or sidebar_. +topic_, sidebar_, or generic admonition_. Details @@ -3789,7 +3899,7 @@ Details :Parents: The following elements may contain ``title``: document_, section_, - topic_, sidebar_ + topic_, sidebar_, admonition_ :Children: ``title`` elements may contain text data plus `inline elements`_. @@ -4215,10 +4325,20 @@ The ``bullet`` attribute is used in the bullet_list_ element. `Attribute type`_: ``NMTOKENS``. Default value: none. The ``class`` attribute contains one or more names used to classify an -element. It can be used to carry context forward between a Docutils -Reader and Writer, when a custom structure is reduced to a -standardized document tree. ``class`` is one of the `common -attributes`_, shared by all Docutils elements. +element. The purpose of the attribute is to indicate an "is-a" +variant relationship, to allow an extensible way of defining +sub-classes of existing elements. It can be used to carry context +forward between a Docutils Reader and Writer, when a custom structure +is reduced to a standardized document tree. One common use is in +conjunction with stylesheets, to add selection criteria. It should +not be used to carry formatting instructions or arbitrary content. + +The ``class`` attribute's contents should be ignorable. Writers that +are not familiar with the variant expressed should be able to ignore +the attribute. + +``class`` is one of the `common attributes`_, shared by all Docutils +elements. ``delimiter`` diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 09ae893f7..f4c09c1c9 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -137,7 +137,7 @@ Here are examples of `body elements`_: This theory, that is mine, is mine. - Anne Elk (Miss) + -- Anne Elk (Miss) - `Doctest blocks`_:: @@ -1098,7 +1098,7 @@ Syntax diagram:: Block Quotes ------------ -Doctree element: block_quote. +Doctree element: block_quote, attribution. A text block that is indented relative to the preceding text, without markup indicating it to be a literal block, is a block quote. All @@ -1111,6 +1111,11 @@ within the block quote:: -- Sherlock Holmes +If the final block of a block quote begins with "--" (flush left +within the block quote), it is interpreted as an attribution. If the +attribution consists of multiple lines, the left edges of the second +and subsequent lines must align. + Blank lines are required before and after a block quote, but these blank lines are not included as part of the block quote. @@ -1123,6 +1128,9 @@ Syntax diagram:: +---------------------------+ | block quote | | (body elements)+ | + | | + | -- attribution text | + | (optional) | +---------------------------+ diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 7874bca3a..4c5fe135a 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -24,6 +24,8 @@ Transforms Listed in Priority Order ============================== ============================ ======== Transform: module.Class Added By Priority ============================== ============================ ======== +misc.class "class" (d/p) 210 + references.Substitutions standalone (r), pep (r) 220 frontmatter.DocTitle standalone (r) 320 -- cgit v1.2.1 From 01e6459e01ffcd8cad09a6efaa169f164fc31df0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 May 2003 20:57:15 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1341 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 0dfb52337..49eaca399 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -488,7 +488,7 @@ becomes this document tree fragment:: Highlights -======== +========== :Directive Type: "highlights" :Doctree Element: block_quote -- cgit v1.2.1 From 5c5bd6ab687ef6831068f0487f4fc83175e2f498 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 May 2003 21:18:48 +0000 Subject: correction git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1342 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 285bb9c98..ad1bf7d9f 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -705,8 +705,8 @@ Pseudo-XML_ fragment from simple parsing:: <block_quote> <paragraph> This theory, that is mine, is mine. - <paragraph> - -- Anne Elk (Miss) + <attribution> + Anne Elk (Miss) ``bullet_list`` -- cgit v1.2.1 From e3b4eed0806159df66495014d21d73123b05a72e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 26 May 2003 20:39:38 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1350 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index ad1bf7d9f..7f0c6cd6d 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -4600,10 +4600,11 @@ Entity definition: paragraph_ | literal_block_ | doctest_block_ | line_block_ | block_quote_ | table_ | figure_ | image_ | footnote_ | citation_ + | rubric_ | bullet_list_ | enumerated_list_ | definition_list_ | field_list_ | option_list_ | attention_ | caution_ | danger_ | error_ | hint_ | important_ - | note_ | tip_ | warning_ + | note_ | tip_ | warning_ | admonition_ | target_ | substitution_definition_ | comment_ | pending_ | system_message_ | raw_ %additional.body.elements; @@ -4612,11 +4613,11 @@ The ``%additional.body.elements;`` parameter entity can be used by wrapper DTDs to extend ``%body.elements;``. The ``%body.elements;`` parameter entity is directly employed in the -content models of the following elements: attention_, block_quote_, -caution_, citation_, danger_, definition_, description_, entry_, -error_, field_body_, footer_, footnote_, header_, hint_, important_, -legend_, list_item_, note_, sidebar_, system_message_, tip_, topic_, -warning_ +content models of the following elements: admonition_, attention_, +block_quote_, caution_, citation_, danger_, definition_, description_, +entry_, error_, field_body_, footer_, footnote_, header_, hint_, +important_, legend_, list_item_, note_, sidebar_, system_message_, +tip_, topic_, warning_ Via `%structure.model;`_, the ``%body.elements;`` parameter entity is indirectly employed in the content models of the document_ and @@ -4654,8 +4655,8 @@ Entity definition: emphasis_ | strong_ | literal_ | reference_ | footnote_reference_ | citation_reference_ | substitution_reference_ | title_reference_ - | abbreviation_ | acronym_ - | problematic_ | generated_ + | abbreviation_ | acronym_ | subscript_ | superscript_ + | inline_ | problematic_ | generated_ | target_ | image_ | raw_ %additional.inline.elements; @@ -4664,12 +4665,13 @@ wrapper DTDs to extend ``%inline.elements;``. Via `%text.model;`_, the ``%inline.elements;`` parameter entity is indirectly employed in the content models of the following elements: -abbreviation_, acronym_, address_, author_, caption_, classifier_, -contact_, copyright_, date_, doctest_block_, emphasis_, generated_, -line_block_, literal_block_, organization_, paragraph_, problematic_, -raw_, reference_, revision_, status_, strong_, -substitution_definition_, substitution_reference_, subtitle_, target_, -term_, title_, version_ +abbreviation_, acronym_, address_, attribution_, author_, caption_, +classifier_, contact_, copyright_, date_, doctest_block_, emphasis_, +generated_, inline_, line_block_, literal_block_, organization_, +paragraph_, problematic_, raw_, reference_, revision_, rubric_, +status_, strong_, subscript_, substitution_definition_, +substitution_reference_, subtitle_, superscript_, target_, term_, +title_, title_reference_, version_ ``%reference.atts;`` -- cgit v1.2.1 From f43900b985a1c3fae98d7a99847250750039b6b4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 3 Jun 2003 02:16:59 +0000 Subject: Added "pull-quote" directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1373 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 49eaca399..93fceb90f 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -499,6 +499,18 @@ Highlights Produces a highlights-class block quote. See Epigraph_ above. +Pull-Quote +========== + +:Directive Type: "pull_quote" +:Doctree Element: block_quote +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Interpreted as the body of the block quote. + +Produces a pull-quote-class block quote. See Epigraph_ above. + + ---------------- Document Parts ---------------- -- cgit v1.2.1 From 6accfecf813ed11c110351c02d98e11b43f57c0a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 5 Jun 2003 15:15:42 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1385 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 9a720eff0..d65750df6 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -31,6 +31,40 @@ Specification`_ for syntax details. .. contents:: +``:emphasis:`` +============== + +:Aliases: None +:DTD Element: emphasis + +Implements emphasis. These are equivalent:: + + *text* + :emphasis:`text` + + +``:literal:`` +============== + +:Aliases: None +:DTD Element: literal + +Implements inline literal text. These are equivalent:: + + ``text`` + :literal:`text` + +Care must be taken with backslash-escapes though. These are *not* +equivalent:: + + ``text \ and \ backslashes`` + :literal:`text \ and \ backslashes` + +The backslashes in the first line are preserved (and do nothing), +whereas the backslashes in the second line escape the following +spaces. + + ``:pep-reference:`` =================== @@ -69,6 +103,36 @@ This is equivalent to:: __ http://www.faqs.org/rfcs/rfc2822.html +``:strong:`` +============ + +:Aliases: None +:DTD Element: strong + +Implements strong emphasis. These are equivalent:: + + **text** + :strong:`text` + + +``:subscript:`` +=============== + +:Aliases: ``:sub:`` +:DTD Element: subscript + +Implements subscripts. + + +``:superscript:`` +================= + +:Aliases: ``:sup:`` +:DTD Element: superscript + +Implements superscripts. + + ``:title-reference:`` ===================== -- cgit v1.2.1 From 4cc798623cc64d7cd12d72105edb830ac7af07e6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 9 Jun 2003 21:26:31 +0000 Subject: clarification of public domain status git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1409 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 1 + docs/ref/rst/introduction.txt | 1 + docs/ref/rst/restructuredtext.txt | 1 + docs/ref/rst/roles.txt | 1 + 4 files changed, 4 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 93fceb90f..0761e21bb 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. .. contents:: diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index 5ff6d2878..13823b5b7 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for inline diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index f4c09c1c9..1ad25ff35 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. .. Note:: diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index d65750df6..a34c4a5ed 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. This document describes the interpreted text roles implemented in the reference reStructuredText parser. -- cgit v1.2.1 From 34e673460e676a67ed552c7c66e2381c6e0c2dbb Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 22 Jun 2003 22:21:28 +0000 Subject: added comments to "unicode" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1494 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 0761e21bb..0dd63e154 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -846,23 +846,27 @@ Unicode Character Codes :Directive Type: "unicode" :Doctree Element: Text -:Directive Arguments: One or more, required (Unicode character codes - & text). +:Directive Arguments: One or more, required (Unicode character codes, + optional text, and comments). :Directive Options: None. :Directive Content: None. The "unicode" directive converts Unicode character codes (numerical values) to characters, and may be used in substitution definitions only. Codes may be decimal numbers, hexadecimal numbers (prefixed by -``0x``, ``x``, ``\x``, ``u``, or ``\u``), or XML-style numbered -character entities (e.g. ``ᨫ``). Codes may be upper- or -lowercase. Spaces are ignored, and any other text remains as-is. +``0x``, ``x``, ``\x``, ``u``, or ``\u``), or XML-style numeric +character entities (e.g. ``ᨫ``). Codes are case-insensitive. + +Text following " .. " is a comment and is ignored. Spaces are +ignored, and any other text remains as-is. Example:: - "|copy|" is the copyright symbol. + Copyright |copy| 2003, |BogusMegaCorp (TM)|. - .. |copy| unicode:: 0xA9 + .. |copy| unicode:: 0xA9 .. copyright sign + .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 + .. with trademark sign Class -- cgit v1.2.1 From ed3436ae71ddcc09dfe7d2be38c01f90934cf486 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 1 Jul 2003 02:23:49 +0000 Subject: added explicit targets of directive names git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1536 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 0dd63e154..5fc316a99 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -45,6 +45,16 @@ type definition. Admonitions ------------- +.. _attention: +.. _caution: +.. _danger: +.. _error: +.. _hint: +.. _important: +.. _note: +.. _tip: +.. _warning: + Specific Admonitions ==================== @@ -99,6 +109,8 @@ bullet list consisting of two list items:: - It includes this bullet list. +.. _admonition: + Generic Admonition ================== @@ -401,6 +413,8 @@ The following option is recognized: class_ directive below. +.. _parsed-literal: + Parsed Literal Block ==================== @@ -503,7 +517,7 @@ Produces a highlights-class block quote. See Epigraph_ above. Pull-Quote ========== -:Directive Type: "pull_quote" +:Directive Type: "pull-quote" :Doctree Element: block_quote :Directive Arguments: None. :Directive Options: None. @@ -516,6 +530,8 @@ Produces a pull-quote-class block quote. See Epigraph_ above. Document Parts ---------------- +.. _contents: + Table of Contents ================= @@ -578,6 +594,9 @@ The following options are recognized: class_ directive below. +.. _sectnum: +.. _section-autonumbering: + Automatic Section Numbering =========================== @@ -612,6 +631,8 @@ The following options are recognized: References ------------ +.. _target-notes: + Target Footnotes ================ @@ -728,6 +749,8 @@ Non-standard element: imagemap. Miscellaneous --------------- +.. _include: + Including an External Document Fragment ======================================= @@ -767,6 +790,8 @@ The following options are recognized: literal block (useful for program listings). +.. _raw: + Raw Data Pass-Through ===================== @@ -812,6 +837,8 @@ The following options are recognized: An Internet URL reference to a raw data file to be included. +.. _replace: + Replacement Text ================ @@ -841,6 +868,8 @@ the "replace" directive:: .. _Python: http://www.python.org/ +.. _unicode: + Unicode Character Codes ======================= -- cgit v1.2.1 From 180fb329f6e70b36a04e3ae54238964eec9adf44 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 11 Jul 2003 02:05:37 +0000 Subject: Allowed true em-dash character as block quote attribution marker. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1584 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 1ad25ff35..46bf3dd16 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1112,10 +1112,10 @@ within the block quote:: -- Sherlock Holmes -If the final block of a block quote begins with "--" (flush left -within the block quote), it is interpreted as an attribution. If the -attribution consists of multiple lines, the left edges of the second -and subsequent lines must align. +If the final block of a block quote begins with "--" or a true em-dash +(flush left within the block quote), it is interpreted as an +attribution. If the attribution consists of multiple lines, the left +edges of the second and subsequent lines must align. Blank lines are required before and after a block quote, but these blank lines are not included as part of the block quote. -- cgit v1.2.1 From 3c4ec123863c437a6357bf69a374872b70a8f227 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 12 Jul 2003 18:59:02 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1587 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 5fc316a99..021ddb6a0 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -883,7 +883,7 @@ Unicode Character Codes The "unicode" directive converts Unicode character codes (numerical values) to characters, and may be used in substitution definitions only. Codes may be decimal numbers, hexadecimal numbers (prefixed by -``0x``, ``x``, ``\x``, ``u``, or ``\u``), or XML-style numeric +``0x``, ``x``, ``\x``, ``U+``, ``u``, or ``\u``), or XML-style numeric character entities (e.g. ``ᨫ``). Codes are case-insensitive. Text following " .. " is a comment and is ignored. Spaces are -- cgit v1.2.1 From a3418f12380f5ca855453fa104445fcb52ed396c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 12 Jul 2003 18:59:30 +0000 Subject: allow "---" for block quote attributions too git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1588 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 46bf3dd16..7a83bdbc8 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1112,8 +1112,8 @@ within the block quote:: -- Sherlock Holmes -If the final block of a block quote begins with "--" or a true em-dash -(flush left within the block quote), it is interpreted as an +If the final block of a block quote begins with "--", "---", or a true +em-dash (flush left within the block quote), it is interpreted as an attribution. If the attribution consists of multiple lines, the left edges of the second and subsequent lines must align. -- cgit v1.2.1 From 5dfbb36b4a867d48619e9dc37600d5900b51bbf5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 15 Jul 2003 00:45:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1590 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 021ddb6a0..e6890e230 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -756,13 +756,15 @@ Including an External Document Fragment :Directive Type: "include" :Doctree Elements: depend on data being included -:Directive Arguments: One, required (path to include file). +:Directive Arguments: One, required. :Directive Options: Possible. :Directive Content: None. The "include" directive reads a reStructuredText-formatted text file and parses it in the current document's context at the point of the -directive. For example:: +directive. The directive argument is the path to the file to be +included, relative to the document containing the directive. For +example:: This first example will be parsed at the document level, and can thus contain any construct, including section headers. -- cgit v1.2.1 From 150390347801881a0179bad8a4930b60856d7029 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 17 Aug 2003 14:14:01 +0000 Subject: link fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1635 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- docs/ref/rst/restructuredtext.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index e6890e230..3eaaa9ef5 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -38,7 +38,7 @@ type definition. .. _Directives: ./reStructuredText.html#directives .. _reStructuredText Markup Specification: ./reStructuredText.html .. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../gpdi.dtd +.. _Docutils Generic DTD: ../docutils.dtd ------------- diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 7a83bdbc8..e0950b3b5 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2642,7 +2642,7 @@ Markup errors are handled according to the specification in `PEP .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _Docutils: http://docutils.sourceforge.net/ .. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../gpdi.dtd +.. _Docutils Generic DTD: ../docutils.dtd .. _transforms: http://docutils.sourceforge.net/docutils/transforms/ .. _Grouch: http://www.mems-exchange.org/software/grouch/ -- cgit v1.2.1 From 04f4937f776a56d8cd8f0b305ddd793af59b99dd Mon Sep 17 00:00:00 2001 From: cben <cben@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 17 Sep 2003 14:45:21 +0000 Subject: - Added some documentation about text-containing vs. compound elements. - Improved images in LaTeX writer: - Fixed inline images (used to always break the paragraph). - Implemented ``align`` and ``scale`` options. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1691 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 7f0c6cd6d..5bd635bb9 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -109,6 +109,8 @@ Structural Subelements ---------------------- Structural subelements are child elements of structural elements. +Simple structuctural subelements (title_, subtitle_) contain text +data; the others are compound and do not directly contain text data. Category members: title_, subtitle_, docinfo_, decoration_, transition_ @@ -118,7 +120,10 @@ Bibliographic Elements `````````````````````` The docinfo_ element is an optional child of document_. It groups -bibliographic elements together. +bibliographic elements together. All bibliographic elements except +authors_ and field_ contain text data. authors_ contains further +bibliographic elements (most notably author_). field_ contains +field_name_ and field_body_ body subelements. Category members: address_, author_, authors_, contact_, copyright_, date_, field_, organization_, revision_, status_, version_ -- cgit v1.2.1 From 65d150aa232b7c22427a03b9a224d01853caff8e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 20 Sep 2003 17:40:33 +0000 Subject: updated option argument (option list) spec git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1699 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index e0950b3b5..125bff591 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1002,7 +1002,14 @@ given, supported by notes about truncation if and when applicable. Options may be followed by an argument placeholder, whose role and syntax should be explained in the description text. Either a space or an equals sign may be used as a delimiter between options and option -argument placeholders. +argument placeholders; short options ("-" or "+" prefix only) may omit +the delimiter. Option arguments may take one of two forms: + +- Begin with a letter ([a-zA-Z]) and subsequently consist of letters, + numbers, underscores and hyphens ([a-zA-Z0-9_-]). +- Begin with an open-angle-bracket (<) and end with a + close-angle-bracket (>); any characters except angle brackets are + allowed internally. Multiple option "synonyms" may be listed, sharing a single description. They must be separated by comma-space. -- cgit v1.2.1 From 995ce3620fdbe36596a3bb3d0f307775cff6554a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 21 Sep 2003 03:12:17 +0000 Subject: fixed unintended reference; text tweaks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1701 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 125bff591..705de4a64 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1005,11 +1005,11 @@ an equals sign may be used as a delimiter between options and option argument placeholders; short options ("-" or "+" prefix only) may omit the delimiter. Option arguments may take one of two forms: -- Begin with a letter ([a-zA-Z]) and subsequently consist of letters, - numbers, underscores and hyphens ([a-zA-Z0-9_-]). -- Begin with an open-angle-bracket (<) and end with a - close-angle-bracket (>); any characters except angle brackets are - allowed internally. +- Begins with a letter (``[a-zA-Z]``) and subsequently consists of + letters, numbers, underscores and hyphens (``[a-zA-Z0-9_-]``). +- Begins with an open-angle-bracket (``<``) and ends with a + close-angle-bracket (``>``); any characters except angle brackets + are allowed internally. Multiple option "synonyms" may be listed, sharing a single description. They must be separated by comma-space. -- cgit v1.2.1 From c722d702ef10e454fbd837aa3b8c1e47eff8a7ff Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 5 Dec 2003 17:57:05 +0000 Subject: added hint git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1760 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index a34c4a5ed..d028405c6 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -124,6 +124,20 @@ Implements strong emphasis. These are equivalent:: Implements subscripts. +.. Tip:: + + Whitespace or punctuation is required around interpreted text, but + often not desired with subscripts & superscripts. + Backslash-escaped whitespace can be used; the whitespace will be + removed from the processed document:: + + H\ :sub:`2`O + E = mc\ :sup:`2` + + See `the reStructuredText spec`__ for further information. + + __ ./reStructuredText.html#character-level-inline-markup + ``:superscript:`` ================= @@ -131,7 +145,7 @@ Implements subscripts. :Aliases: ``:sup:`` :DTD Element: superscript -Implements superscripts. +Implements superscripts. See the tip in `:subscript:`_ above. ``:title-reference:`` -- cgit v1.2.1 From 94021c3e27455b3d8961caf45ae0159e4e41d92c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 5 Dec 2003 19:14:14 +0000 Subject: fixed hint git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1761 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index d028405c6..d3c6ba260 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -131,7 +131,7 @@ Implements subscripts. Backslash-escaped whitespace can be used; the whitespace will be removed from the processed document:: - H\ :sub:`2`O + H\ :sub:`2`\ O E = mc\ :sup:`2` See `the reStructuredText spec`__ for further information. -- cgit v1.2.1 From 52e134d8526146e6b736b0daa9f72e23467556c8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 6 Dec 2003 16:30:09 +0000 Subject: updated from Ueli Schlaepfer's suggestion git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1763 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index d3c6ba260..82c5646e8 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -136,7 +136,19 @@ Implements subscripts. See `the reStructuredText spec`__ for further information. + In such cases, readability of the plain text can be greatly + improved with substitutions:: + + The chemical formula for pure water is |H20|. + + .. |H20| replace:: H\ :sub:`2`\ O + + See `the reStructuredText spec`__ for further information on + `character-level markup`__ and `the substitution mechanism`__. + + __ ./reStructuredText.html __ ./reStructuredText.html#character-level-inline-markup + __ ./reStructuredText.html#substitution-references ``:superscript:`` -- cgit v1.2.1 From 6d0e5cffcf3342e394b3820fb572d1811d5a75f5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 6 Dec 2003 18:32:35 +0000 Subject: fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1764 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 82c5646e8..fb5ddeb89 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -134,14 +134,12 @@ Implements subscripts. H\ :sub:`2`\ O E = mc\ :sup:`2` - See `the reStructuredText spec`__ for further information. - In such cases, readability of the plain text can be greatly improved with substitutions:: - The chemical formula for pure water is |H20|. + The chemical formula for pure water is |H2O|. - .. |H20| replace:: H\ :sub:`2`\ O + .. |H2O| replace:: H\ :sub:`2`\ O See `the reStructuredText spec`__ for further information on `character-level markup`__ and `the substitution mechanism`__. -- cgit v1.2.1 From c5e249ae47c1c7b96367b911b7aa7817ba85c797 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 19 Dec 2003 14:30:13 +0000 Subject: Added inline markup parsing to field lists' field names git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1771 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 19 +++++++++---------- docs/ref/docutils.dtd | 2 +- docs/ref/rst/restructuredtext.txt | 15 ++++++++------- 3 files changed, 18 insertions(+), 18 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 5bd635bb9..f4b96608d 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -2181,22 +2181,21 @@ Pseudo-XML_ fragment from simple parsing:: ``field_name`` ============== -The ``field_name`` element contains text data only. It is analogous -to a database field's name. +The ``field_name`` element contains text; it is analogous to a +database field's name. Details ------- :Category: - `Body Subelements`_ + `Body Subelements`_ (simple) :Parents: Only the field_ element contains ``field_name``. :Children: - ``field_name`` elements have no children. They may contain text - data only. + ``field_name`` elements may contain text data plus `inline elements`_. :Analogues: ``field_name`` has no direct analogues in common DTDs. @@ -2210,7 +2209,7 @@ Content Model .. parsed-literal:: - (#PCDATA) + `%text.model;`_ :Attributes: The ``field_name`` element contains only the `common attributes`_: @@ -4829,10 +4828,10 @@ Entity definition: The ``%text.model;`` parameter entity is directly employed in the content models of the following elements: abbreviation_, acronym_, address_, author_, caption_, classifier_, contact_, copyright_, date_, -doctest_block_, emphasis_, generated_, line_block_, literal_block_, -organization_, paragraph_, problematic_, raw_, reference_, revision_, -status_, strong_, substitution_definition_, substitution_reference_, -subtitle_, target_, term_, title_, version_ +doctest_block_, emphasis_, field_name_, generated_, line_block_, +literal_block_, organization_, paragraph_, problematic_, raw_, +reference_, revision_, status_, strong_, substitution_definition_, +substitution_reference_, subtitle_, target_, term_, title_, version_ diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 06fe4bf55..dc58a9739 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -322,7 +322,7 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT field (field_name, field_body)> <!ATTLIST field %basic.atts;> -<!ELEMENT field_name (#PCDATA)> +<!ELEMENT field_name %text.model;> <!ATTLIST field_name %basic.atts;> <!-- May be empty. --> diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 705de4a64..ff732af1b 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -802,13 +802,14 @@ directives in `reStructuredText Directives`_. Field lists are mappings from field names to field bodies, modeled on RFC822_ headers. A field name is made up of one or more letters, -numbers, whitespace, and punctuation, except colons (":"). Field -names are case-insensitive. The field name, along with a single colon -prefix and suffix, together form the field marker. The field marker -is followed by whitespace and the field body. The field body may -contain multiple body elements, indented relative to the field marker. -The first line after the field name marker determines the indentation -of the field body. For example:: +numbers, whitespace, and punctuation, except colons (":"). Inline +markup is parsed in field names. Field names are case-insensitive +when further processed or transformed. The field name, along with a +single colon prefix and suffix, together form the field marker. The +field marker is followed by whitespace and the field body. The field +body may contain multiple body elements, indented relative to the +field marker. The first line after the field name marker determines +the indentation of the field body. For example:: :Date: 2001-08-16 :Version: 1 -- cgit v1.2.1 From f74494c19b8a9de8a1bb4d6c2acce694b24d802b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 20 Dec 2003 18:48:23 +0000 Subject: Added support for quoted (and unindented) literal blocks. Driven in part by a bribe from Frank Siebenlist (thanks!). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1773 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 77 ++++++++++++++++++++++++++++++++------- 1 file changed, 64 insertions(+), 13 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index ff732af1b..b63979f70 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -124,8 +124,9 @@ Here are examples of `body elements`_: - `Literal blocks`_:: - Literal blocks are indented, and indicated with a double-colon - ("::") at the end of the preceding paragraph (right here -->):: + Literal blocks are either indented or line-prefix-quoted blocks, + and indicated with a double-colon ("::") at the end of the + preceding paragraph (right here -->):: if literal_block: text = 'is left as-is' @@ -1036,12 +1037,13 @@ Literal Blocks Doctree element: literal_block. -A paragraph consisting of two colons ("::") signifies that all -following **indented** text blocks comprise a literal block. No -markup processing is done within a literal block. It is left as-is, -and is typically rendered in a monospaced typeface:: +A paragraph consisting of two colons ("::") signifies that the +following text block(s) comprise a literal block. The literal block +must either be indented or quoted (see below). No markup processing +is done within a literal block. It is left as-is, and is typically +rendered in a monospaced typeface:: - This is a typical paragraph. A literal block follows. + This is a typical paragraph. An indented literal block follows. :: @@ -1087,11 +1089,21 @@ colons after "Paragraph"): Literal block -The minimum leading whitespace will be removed from each line of the -literal block. Other than that, all whitespace (including line -breaks) is preserved. Blank lines are required before and after a -literal block, but these blank lines are not included as part of the -literal block. +All whitespace (including line breaks, but excluding minimum +indentation for indented literal blocks) is preserved. Blank lines +are required before and after a literal block, but these blank lines +are not included as part of the literal block. + + +Indented Literal Blocks +``````````````````````` + +Indented literal blocks are indicated by indentation relative to the +surrounding text (leading whitespace on each line). The minimum +indentation will be removed from each line of an indented literal +block. The literal block need not be contiguous; blank lines are +allowed between sections of indented text. The literal block ends +with the end of the indentation. Syntax diagram:: @@ -1100,10 +1112,49 @@ Syntax diagram:: | (ends with "::") | +------------------------------+ +---------------------------+ - | literal block | + | indented literal block | +---------------------------+ +Quoted Literal Blocks +````````````````````` + +Quoted literal blocks are unindented contiguous blocks of text where +each line begins with the same non-alphanumeric printable 7-bit ASCII +character [#]_. A blank line ends a quoted literal block. The +quoting characters are preserved in the processed document. + +.. [#] + The following are all valid quoting characters:: + + ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ + + Note that these are the same characters as are valid for title + adornment of sections_. + +Possible uses include literate programming in Haskell and email +quoting:: + + John Doe wrote:: + + >> Great idea! + > + > Why didn't I think of that? + + You just did! ;-) + +Syntax diagram:: + + +------------------------------+ + | paragraph | + | (ends with "::") | + +------------------------------+ + +------------------------------+ + | ">" per-line-quoted | + | ">" contiguous literal block | + +------------------------------+ + + Block Quotes ------------ -- cgit v1.2.1 From 1a9d3d2ed89b62a7ed5126355e3f11b70ed1e5c1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 24 Dec 2003 15:05:18 +0000 Subject: Upon reviewing RFC 2396, I see that asterisks are valid URL characters, sometimes actually used. There's a conflict with emphasis, but backslash escapes should overcome that (they didn't). This fixes a bug in the parser that escaped asterisks in URLs weren't recognized. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1778 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index b63979f70..7a6c7bfda 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2682,6 +2682,9 @@ Two forms of URI are recognized: someone@somewhere.com Punctuation at the end of a URI is not considered part of the URI. +Backslashes may be used in URIs to escape markup characters, +specifically asterisks ("*") and underscores ("_") which are vaid URI +characters (see `Escaping Mechanism`_ above). .. [#URI] Uniform Resource Identifier. URIs are a general form of URLs (Uniform Resource Locators). For the syntax of URIs see -- cgit v1.2.1 From 37babfef0811bc5cfeaa92d5ec04d8c68904aafe Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 24 Dec 2003 15:18:55 +0000 Subject: updated URI schemes mapping & links git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1779 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 7a6c7bfda..c8a2047a3 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2651,8 +2651,8 @@ Two forms of URI are recognized: The scheme is the name of the protocol, such as "http", "ftp", "mailto", or "telnet". The scheme consists of an initial letter, followed by letters, numbers, and/or "+", "-", ".". Recognition is - limited to known schemes, per the W3C's `Index of WWW Addressing - Schemes`_. + limited to known schemes, per the `Official IANA Registry of URI + Schemes`_ and the W3C's `Retired Index of WWW Addressing Schemes`_. The scheme-specific part of the resource identifier may be either hierarchical or opaque: @@ -2719,7 +2719,9 @@ Markup errors are handled according to the specification in `PEP .. _doctest module: http://www.python.org/doc/current/lib/module-doctest.html .. _Emacs table mode: http://table.sourceforge.net/ -.. _Index of WWW Addressing Schemes: +.. _Official IANA Registry of URI Schemes: + http://www.iana.org/assignments/uri-schemes +.. _Retired Index of WWW Addressing Schemes: http://www.w3.org/Addressing/schemes.html .. _World Wide Web Consortium: http://www.w3.org/ .. _HTML Techniques for Web Content Accessibility Guidelines: -- cgit v1.2.1 From 4e174f882eb88ad4fd1e41e785a5c21e347e0c53 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 24 Dec 2003 15:51:38 +0000 Subject: Made embedded-URIs' reference text omittable. Idea from Beni Cherniavsky. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1781 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index c8a2047a3..81c886e7a 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2519,6 +2519,14 @@ For example, here is a reference to a title describing a tag:: See `HTML Element: \<a>`_ below. +The reference text may also be omitted, in which case the URI will be +duplicated for use as the reference text. This is useful for relative +URIs where the address or file name is also the desired reference +text:: + + See `<a_named_relative_link>`_ or `<an_anonymous_relative_link>`__ + for details. + .. CAUTION:: This construct offers easy authoring and maintenance of hyperlinks -- cgit v1.2.1 From 04c04b5a28057ee8c6aabad94b77d27ec5c9d924 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 29 Dec 2003 20:07:10 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1782 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 81c886e7a..39e1168d4 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1565,15 +1565,15 @@ The standard Docutils system uses the following symbols for footnote marks [#]_: - asterisk/star ("*") -- dagger (HTML character entity "†") -- double dagger ("‡") -- section mark ("§") -- pilcrow or paragraph mark ("¶") +- dagger (HTML character entity "†", Unicode U+02020) +- double dagger ("‡"/U+02021) +- section mark ("§"/U+000A7) +- pilcrow or paragraph mark ("¶"/U+000B6) - number sign ("#") -- spade suit ("♠") -- heart suit ("♥") -- diamond suit ("♦") -- club suit ("♣") +- spade suit ("♠"/U+02660) +- heart suit ("♥"/U+02665) +- diamond suit ("♦"/U+02666) +- club suit ("♣"/U+02663) .. [#] This list was inspired by the list of symbols for "Note Reference Marks" in The Chicago Manual of Style, 14th edition, @@ -1584,6 +1584,11 @@ marks [#]_: If more than ten symbols are required, the same sequence will be reused, doubled and then tripled, and so on ("**" etc.). +.. Note:: When using auto-symbol footnotes, the choice of output + encoding is important. Many of the symbols used are not encodable + in certain common text encodings such as Latin-1 (ISO 8859-1). The + use of UTF-8 for the output encoding is recommended. + Mixed Manual and Auto-Numbered Footnotes ........................................ -- cgit v1.2.1 From 7e168dceedab63027fa670d76ab933cd8934f4b4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 30 Dec 2003 04:01:40 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1783 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 39e1168d4..27dd7f52f 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1587,7 +1587,12 @@ reused, doubled and then tripled, and so on ("**" etc.). .. Note:: When using auto-symbol footnotes, the choice of output encoding is important. Many of the symbols used are not encodable in certain common text encodings such as Latin-1 (ISO 8859-1). The - use of UTF-8 for the output encoding is recommended. + use of UTF-8 for the output encoding is recommended. An + alternative for HTML and XML output is to use the + "xmlcharrefreplace" `output encoding error handler`__ (available in + Python 2.3 & later). + +__ http://docutils.sf.net/docs/config.html#output-encoding-error-handler Mixed Manual and Auto-Numbered Footnotes -- cgit v1.2.1 From 10a6b744053a86b58f789caa23bfac62c1afa5fb Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 4 Jan 2004 17:35:33 +0000 Subject: Added "target" option to "image" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1791 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 3eaaa9ef5..b794fa42c 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -215,6 +215,11 @@ The following options are recognized: text flow around it. The specific behavior depends upon the browser or rendering software used. +``target`` : text (URI or reference name) + Makes the image into a hyperlink reference ("clickable"). The + option argument may be a URI (relative or absolute), or a + reference name with underscore suffix (e.g. ``name_``). + ``class`` : text Set a "class" attribute value on the image element. See the class_ directive below. -- cgit v1.2.1 From eaab763e93ebde4bba8e04f6bbfad9e570417ea8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 4 Jan 2004 17:39:13 +0000 Subject: support for body-level reference nodes git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1792 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index dc58a9739..7add492f3 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -121,7 +121,7 @@ resolve to either an internal or external reference. | option_list | attention | caution | danger | error | hint | important | note | tip | warning | admonition - | target | substitution_definition | comment | pending + | reference | target | substitution_definition | comment | pending | system_message | raw %additional.body.elements; "> @@ -512,6 +512,7 @@ following caveats: <!ELEMENT literal (#PCDATA)> <!ATTLIST literal %basic.atts;> +<!-- Can also be a body element, when it contains an "image" element. --> <!ELEMENT reference %text.model;> <!ATTLIST reference %basic.atts; -- cgit v1.2.1 From b24dd9aaa77085ba010d3d2aaa2a42dac8f73e16 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Jan 2004 02:35:13 +0000 Subject: Added FilterMessages transform (removes system messages below the verbosity threshold) git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1811 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 4c5fe135a..fa866487c 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -71,7 +71,9 @@ universal.FinalChecks Transformer 840 universal.Messages Transformer 860 -universal.TestMessages DocutilsTestSupport 890 +universal.FilterMessages Transformer 870 + +universal.TestMessages DocutilsTestSupport 880 misc.CallBack n/a 990 ============================== ============================ ======== -- cgit v1.2.1 From 9e5231402a34f7787d0202fdfdd83fa2157c89ec Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Jan 2004 16:11:29 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1819 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index fa866487c..dd1d13ba3 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -61,7 +61,7 @@ parts.SectNum "sectnum" (d/p) 710 parts.Contents "contents" (d/p), 720 peps.Contents (t/p) -peps.PEPZero pep.Headers (t/p) 760 +peps.PEPZero peps.Headers (t/p) 760 components.Filter "meta" (d/p) 780 -- cgit v1.2.1 From e17447558a38a56bdf0fc665dbd1bca765831bb7 Mon Sep 17 00:00:00 2001 From: aahz <aahz@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 21 Mar 2004 15:44:21 +0000 Subject: Update to make sections equivalent to documents, except sections must have title. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1842 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 7add492f3..5087d23d7 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -209,6 +209,11 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT docinfo (%bibliographic.elements;)+> <!ATTLIST docinfo %basic.atts;> +<!-- Container for bibliographic elements. May not be empty. +Eventual replacement for docinfo? --> +<!ELEMENT info (%bibliographic.elements;)+> +<!ATTLIST info %basic.atts;> + <!ELEMENT author %text.model;> <!ATTLIST author %basic.atts;> @@ -262,7 +267,8 @@ http://www.oasis-open.org/html/tm9901.htm). ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> -<!ELEMENT section (title, %structure.model;)> +<!ELEMENT section + (title, subtitle?, info?, decoration?, %structure.model;)> <!ATTLIST section %basic.atts;> <!ELEMENT topic (title?, (%body.elements;)+)> -- cgit v1.2.1 From 82a7c91551ba17af1813fdfe69688c794ee2ce3e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 30 Mar 2004 21:59:00 +0000 Subject: allow additional text with RCS keywords git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1897 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 27dd7f52f..0e47be551 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -928,7 +928,7 @@ Processed, the "status" element's text will become simply "expansion text". The dollar sign delimiters and leading RCS keyword name are removed. -The RCS keyword processing only kicks in when all of these conditions +The RCS keyword processing only kicks in when both of these conditions hold: 1. The field list is in bibliographic context (first non-comment @@ -937,9 +937,6 @@ hold: 2. The field name is a recognized bibliographic field name. -3. The sole contents of the field is an expanded RCS keyword, of the - form "$Keyword: data $". - Option Lists ------------ -- cgit v1.2.1 From 5de4bec88b62acfa5cd0da03753f96b67603799c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Apr 2004 22:50:37 +0000 Subject: added "role" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1959 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 52 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index b794fa42c..67948383d 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -961,6 +961,58 @@ The text above is parsed and transformed into this doctree fragment:: __ ../doctree.html#class +.. role:: + +Custom Interpreted Text Roles +============================= + +:Directive Type: "role" +:Doctree Element: None. +:Directive Arguments: One, required (role name). +:Directive Options: Possible. +:Directive Content: None. + +The "role" directive dynamically creates a custom interpreted text +role and registers it with the parser. This means that after +declaring a role like this:: + + .. role:: custom + +the document may use the "custom" role:: + + An example of using :custom:`interpreted text` + +This will be parsed into the following document tree fragment:: + + <paragraph> + An example of using + <inline class="custom"> + interpreted text + +The role must be declared in a document before it can be used. + +The ":class:" option can be used to set a "class" attribute that is +different from the role name. For example:: + + .. role:: custom + :class: special + + :custom:`interpreted text` + +This is the parsed result:: + + <paragraph> + <inline class="special"> + interpreted text + +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the ``inline`` elements produced + when the custom interpreted text role is used. See the class_ + directive above. + + Restructuredtext-Test-Directive =============================== -- cgit v1.2.1 From 5ce1011f520060770e231a3924fd7017a1d20f82 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 18 Apr 2004 00:28:38 +0000 Subject: oops git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1962 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 67948383d..4388fbe71 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -961,7 +961,7 @@ The text above is parsed and transformed into this doctree fragment:: __ ../doctree.html#class -.. role:: +.. _role: Custom Interpreted Text Roles ============================= -- cgit v1.2.1 From fa486395e0412ae207135b7b9b1eceabbe2803e7 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 19 Apr 2004 01:40:58 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1972 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 4388fbe71..6dad0bfa4 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1009,7 +1009,9 @@ The following option is recognized: ``class`` : text Set a "class" attribute value on the ``inline`` elements produced - when the custom interpreted text role is used. See the class_ + when the custom interpreted text role is used. If no directive + options are specified, a "class" option with the directive + argument (role name) as the value is implied. See the class_ directive above. -- cgit v1.2.1 From 0303d5d2084a675b6a49932bfd39a5f93491fb3d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 20 Apr 2004 23:53:43 +0000 Subject: improvements git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1973 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index fb5ddeb89..78cace8b5 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -193,7 +193,8 @@ processing:: ``:title-reference:`` is the default interpreted text role in the standard reStructuredText parser. This means that no explicit role is required. Applications of reStructuredText may designate a different -default role, in which case the explicit role must be used. +default role, in which case the explicit ``:title-reference:`` role +must be used to obtain a ``title_reference`` element. .. _pseudo-XML: ../doctree.html#pseudo-xml -- cgit v1.2.1 From 132652882ac11a8ffb1f8a3981753cbf7b4232d0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 21 Apr 2004 01:09:39 +0000 Subject: improvements git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1974 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 0e47be551..356220634 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1850,8 +1850,9 @@ Directives Doctree elements: depend on the directive. Directives are an extension mechanism for reStructuredText, a way of -adding support for new constructs without adding new syntax. All -standard directives (those implemented and registered in the reference +adding support for new constructs without adding new primary syntax +(directives may support additional syntax locally). All standard +directives (those implemented and registered in the reference reStructuredText parser) are described in the `reStructuredText Directives`_ document, and are always available. Any other directives are domain-specific, and may require special action to make them @@ -1885,10 +1886,10 @@ these reasons: .. Danger: modify at your own risk! - If an implementation of reStructuredText does not recognize a - directive (i.e., the directive-handler is not installed), the entire - directive block (including the directive itself) will be treated as - a literal block, and a level-3 (error) system message generated. - Thus "::" is a natural choice. + directive (i.e., the directive-handler is not installed), a level-3 + (error) system message is generated, and the entire directive block + (including the directive itself) will be included as a literal + block. Thus "::" is a natural choice. The directive block is consists of any text on the first line of the directive after the directive marker, and any subsequent indented -- cgit v1.2.1 From 79d178d4cc3c7ea624cd16b8e78f7127520bf4d8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Apr 2004 14:01:39 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1987 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 356220634..8227432ad 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1881,7 +1881,9 @@ words (alphanumerics plus internal hyphens, underscores, and periods; no whitespace). Two colons are used after the directive type for these reasons: -- To avoid clashes with common comment text like:: +- Two colons are distinctive, and unlikely to be used in common text. + +- Two colons avoids clashes with common comment text like:: .. Danger: modify at your own risk! -- cgit v1.2.1 From 2e594eab0b980f2357c83ab560bc07c0d5779117 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 27 Apr 2004 19:53:19 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2002 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 62 +++++++++++++++++++++++++++++++++------------ docs/ref/rst/roles.txt | 58 +++++++++++++++++++++++++++++++++++++++--- 2 files changed, 101 insertions(+), 19 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 6dad0bfa4..f21b9afcc 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -33,12 +33,14 @@ Descriptions below list "doctree elements" (document tree element names; XML DTD generic identifiers) corresponding to individual directives. For details on the hierarchy of elements, please see `The Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document -type definition. +type definition. For directive implementation details, see `Creating +reStructuredText Directives`_. -.. _Directives: ./reStructuredText.html#directives -.. _reStructuredText Markup Specification: ./reStructuredText.html +.. _Directives: reStructuredText.html#directives +.. _reStructuredText Markup Specification: reStructuredText.html .. _The Docutils Document Tree: ../doctree.html .. _Docutils Generic DTD: ../docutils.dtd +.. _Creating reStructuredText Directives: ../howto/rst-directives.html ------------- @@ -967,10 +969,11 @@ Custom Interpreted Text Roles ============================= :Directive Type: "role" -:Doctree Element: None. -:Directive Arguments: One, required (role name). -:Directive Options: Possible. -:Directive Content: None. +:Doctree Element: None; affects subsequent parsing. +:Directive Arguments: Two; one required (role name), one optional + (base role name, in parentheses). +:Directive Options: Possible (depends on base role). +:Directive Content: depends on base role. The "role" directive dynamically creates a custom interpreted text role and registers it with the parser. This means that after @@ -978,7 +981,7 @@ declaring a role like this:: .. role:: custom -the document may use the "custom" role:: +the document may use the new "custom" role:: An example of using :custom:`interpreted text` @@ -991,8 +994,26 @@ This will be parsed into the following document tree fragment:: The role must be declared in a document before it can be used. -The ":class:" option can be used to set a "class" attribute that is -different from the role name. For example:: +The new role may be based on an existing role, specified as a second +argument in parentheses (whitespace optional):: + + .. role:: custom(emphasis) + + :custom:`text` + +The parsed result is as follows:: + + <paragraph> + <emphasis class="custom"> + text + +If no base role is explicitly specified, a generic custom role is +automatically used. Subsequent interpreted text will produce an +"inline" element with a "class" attribute, as in the first example +above. + +With most roles, the ":class:" option can be used to set a "class" +attribute that is different from the role name. For example:: .. role:: custom :class: special @@ -1005,14 +1026,23 @@ This is the parsed result:: <inline class="special"> interpreted text -The following option is recognized: +.. _role class: + +The following option is recognized by the "role" directive for most +base roles: ``class`` : text - Set a "class" attribute value on the ``inline`` elements produced - when the custom interpreted text role is used. If no directive - options are specified, a "class" option with the directive - argument (role name) as the value is implied. See the class_ - directive above. + Set a "class" attribute value on the element produced (``inline``, + or element associated with a base class) when the custom + interpreted text role is used. If no directive options are + specified, a "class" option with the directive argument (role + name) as the value is implied. See the class_ directive above. + +Specific roles may support other options and/or directive content. +See the `reStructuredText Interpreted Text Roles`_ document for +details. + +.. _reStructuredText Interpreted Text Roles: interpreted.html Restructuredtext-Test-Directive diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 78cace8b5..d93a2bf9d 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -23,20 +23,51 @@ is used if no explicit ``:role:`` prefix or suffix is given. The "default default role" is `:title-reference:`_. See the `Interpreted Text`_ section in the `reStructuredText Markup -Specification`_ for syntax details. +Specification`_ for syntax details. For details on the hierarchy of +elements, please see `The Docutils Document Tree`_ and the `Docutils +Generic DTD`_ XML document type definition. For interpreted text role +implementation details, see `Creating reStructuredText Interpreted +Text Roles`_. -.. _Interpreted Text: ./reStructuredText.html#interpreted-text -.. _reStructuredText Markup Specification: ./reStructuredText.html +.. _"role" directive: directives.html#role +.. _Interpreted Text: reStructuredText.html#interpreted-text +.. _reStructuredText Markup Specification: reStructuredText.html +.. _The Docutils Document Tree: ../doctree.html +.. _Docutils Generic DTD: ../docutils.dtd +.. _Creating reStructuredText Interpreted Text Roles: ../howto/rst-roles.html .. contents:: +--------------- + Customization +--------------- + +Custom interpreted text roles may be defined in a document with the +`"role" directive`_. Customization details are listed with each role. + +.. _class: + +The ``class`` option is recognized by the "role" directive for most +interpreted text roles. A description__ is provided by `"role" +directive`_ documentation. + +__ directives.html#role-class + + +--------------------------------- + Standard Interpreted Text Roles +--------------------------------- + ``:emphasis:`` ============== :Aliases: None :DTD Element: emphasis +:Customization: + :Options: class_. + :Content: None. Implements emphasis. These are equivalent:: @@ -49,6 +80,9 @@ Implements emphasis. These are equivalent:: :Aliases: None :DTD Element: literal +:Customization: + :Options: class_. + :Content: None. Implements inline literal text. These are equivalent:: @@ -71,6 +105,9 @@ spaces. :Aliases: ``:PEP:`` :DTD Element: reference +:Customization: + :Options: class_. + :Content: None. The ``:pep-reference:`` role is used to create an HTTP reference to a PEP (Python Enhancement Proposal). The ``:PEP:`` alias is usually @@ -90,6 +127,9 @@ This is equivalent to:: :Aliases: ``:RFC:`` :DTD Element: reference +:Customization: + :Options: class_. + :Content: None. The ``:rfc-reference:`` role is used to create an HTTP reference to an RFC (Internet Request for Comments). The ``:RFC:`` alias is usually @@ -109,6 +149,9 @@ This is equivalent to:: :Aliases: None :DTD Element: strong +:Customization: + :Options: class_. + :Content: None. Implements strong emphasis. These are equivalent:: @@ -121,6 +164,9 @@ Implements strong emphasis. These are equivalent:: :Aliases: ``:sub:`` :DTD Element: subscript +:Customization: + :Options: class_. + :Content: None. Implements subscripts. @@ -154,6 +200,9 @@ Implements subscripts. :Aliases: ``:sup:`` :DTD Element: superscript +:Customization: + :Options: class_. + :Content: None. Implements superscripts. See the tip in `:subscript:`_ above. @@ -163,6 +212,9 @@ Implements superscripts. See the tip in `:subscript:`_ above. :Aliases: ``:title:``, ``:t:``. :DTD Element: title_reference +:Customization: + :Options: class_. + :Content: None. The ``:title-reference:`` role is used to describe the titles of books, periodicals, and other materials. It is the equivalent of the -- cgit v1.2.1 From 634c665bb1f1ec6c26974a3f3ed23868ec49f6f4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 4 May 2004 00:58:28 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2024 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 8227432ad..52d30033d 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1703,8 +1703,8 @@ indirect. .. _archive: .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/ - An inline form of internal hyperlink target is available; see - `Inline Internal Targets`_. + An inline form of internal hyperlink target is available; see + `Inline Internal Targets`_. 2. _`External hyperlink targets` have an absolute or relative URI or email address in their link blocks. For example, take the -- cgit v1.2.1 From 6bd8903fccd5d0950e8d3b130d08884e1c6d3a6c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 7 May 2004 02:04:34 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2032 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index f21b9afcc..cbd70a0ae 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -205,7 +205,8 @@ The following options are recognized: ``scale`` : integer The uniform scaling factor of the image, a percentage (but no "%" - symbol is required or allowed). "100" means full-size. + symbol is required or allowed). "100" means full-size. PIL_ + [#PIL]_ may be required. ``align`` : "top", "middle", "bottom", "left", "center", or "right" The alignment of the image, equivalent to the HTML ``<img>`` tag's @@ -272,9 +273,9 @@ options are recognized: ``figwidth`` : integer or "image" The width of the figure in pixels, to limit the horizontal space used. A special value of "image" is allowed, in which case the - included image's actual width is used (requires PIL_ [#]_). If the - image file is not found or the required software is unavailable, - this option is ignored. + included image's actual width is used (requires PIL_ [#PIL]_). If + the image file is not found or the required software is + unavailable, this option is ignored. Sets the "width" attribute of the "figure" doctree element. @@ -300,7 +301,7 @@ options are recognized: Set a "class" attribute value on the figure element. See the class_ directive below. -.. [#] `Python Imaging Library`_. +.. [#PIL] `Python Imaging Library`_. .. _PIL: .. _Python Imaging Library: http://www.pythonware.com/products/pil/ -- cgit v1.2.1 From efc28aa7196aa0b8a4e6305b44f99cd383453e13 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 7 May 2004 02:09:47 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2033 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index cbd70a0ae..f5dedbbd7 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -205,7 +205,7 @@ The following options are recognized: ``scale`` : integer The uniform scaling factor of the image, a percentage (but no "%" - symbol is required or allowed). "100" means full-size. PIL_ + symbol is required or allowed). "100" means full-size. PIL [#PIL]_ may be required. ``align`` : "top", "middle", "bottom", "left", "center", or "right" @@ -273,7 +273,7 @@ options are recognized: ``figwidth`` : integer or "image" The width of the figure in pixels, to limit the horizontal space used. A special value of "image" is allowed, in which case the - included image's actual width is used (requires PIL_ [#PIL]_). If + included image's actual width is used (requires PIL [#PIL]_). If the image file is not found or the required software is unavailable, this option is ignored. @@ -303,7 +303,6 @@ options are recognized: .. [#PIL] `Python Imaging Library`_. -.. _PIL: .. _Python Imaging Library: http://www.pythonware.com/products/pil/ -- cgit v1.2.1 From 50235a374afca458e319256c9bfe8c466dfc567c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 7 May 2004 16:25:23 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2046 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index f5dedbbd7..cc2657b1b 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -196,17 +196,24 @@ The following options are recognized: for visually impaired users. ``height`` : integer - The height of the image in pixels, used to reserve space or scale - the image vertically. + The desired height of the image in pixels, used to reserve space + or scale the image vertically. When the "scale" option is also + specified, they are combined. For example, a height of 200 and a + scale of 50 is equivalent to a height of 100 with no scale. ``width`` : integer The width of the image in pixels, used to reserve space or scale - the image horizontally. + the image horizontally. As with "height" above, when the "scale" + option is also specified, they are combined. ``scale`` : integer The uniform scaling factor of the image, a percentage (but no "%" - symbol is required or allowed). "100" means full-size. PIL - [#PIL]_ may be required. + symbol is required or allowed). "100" means full-size, and is + equivalent to omitting a "scale" option. + + If no "height" or "width" options are specified, PIL [#PIL]_ may + be used to determine them, if PIL is installed and the image file + is available. ``align`` : "top", "middle", "bottom", "left", "center", or "right" The alignment of the image, equivalent to the HTML ``<img>`` tag's @@ -988,7 +995,7 @@ the document may use the new "custom" role:: This will be parsed into the following document tree fragment:: <paragraph> - An example of using + An example of using <inline class="custom"> interpreted text -- cgit v1.2.1 From d6f10b154951bef4e580c46ad7a624252a1e3268 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 9 May 2004 13:45:44 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2062 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index f4b96608d..f72f8f140 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -2302,6 +2302,10 @@ setting has been supplied:: ``generated`` ============= +Docutils wraps ``generated`` elements around text that is inserted +(generated) by Docutils; i.e., text that was not in the document, like +section numbers inserted by the "sectnum" directive. + `To be completed`_. -- cgit v1.2.1 From 562fdc222a9cd9c5ec3949081abaa95cf55b8afa Mon Sep 17 00:00:00 2001 From: cben <cben@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 15 May 2004 23:16:23 +0000 Subject: Emphasized the DocTitle transfrom in docs, as it's a very FAQ. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2101 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 52d30033d..b018c5f5a 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -443,8 +443,9 @@ Specifically, there is no way to indicate a document title and subtitle explicitly in reStructuredText. Instead, a lone top-level section title (see Sections_ below) can be treated as the document title. Similarly, a lone second-level section title immediately after -the "document title" can become the document subtitle. See the -`DocTitle transform`_ for details. +the "document title" can become the document subtitle. The rest of +the sections are than lifted up a level or two. See the `DocTitle +transform`_ for details. Sections -- cgit v1.2.1 From 743c1f012b8e7326184e92846d33e41b743ee68a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 16 May 2004 00:44:13 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2104 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index b018c5f5a..57b9df995 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -444,7 +444,7 @@ subtitle explicitly in reStructuredText. Instead, a lone top-level section title (see Sections_ below) can be treated as the document title. Similarly, a lone second-level section title immediately after the "document title" can become the document subtitle. The rest of -the sections are than lifted up a level or two. See the `DocTitle +the sections are then lifted up a level or two. See the `DocTitle transform`_ for details. -- cgit v1.2.1 From 20e99ef35863b0e027fcfd29265ce7a1c2a515a4 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 29 May 2004 21:31:27 +0000 Subject: fixed invalid example git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2135 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index cc2657b1b..9f0f11952 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -836,7 +836,7 @@ output stream:: .. raw:: latex - \documentclass[twocolumn]{article} + \setlength{\parindent}{0pt} Raw data can also be read from an external file, specified in a directive option. In this case, the content block must be empty. For -- cgit v1.2.1 From e865d212ffa1684207616d71ce7c5a9abd5e6684 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 30 May 2004 18:55:49 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2143 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 9f0f11952..4d72e4c24 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -443,9 +443,14 @@ constructs a literal block where the text is parsed for inline markup. It is equivalent to a `line block`_ with different rendering: typically in a typewriter/monospaced typeface, like an ordinary literal block. Parsed literal blocks are useful for adding hyperlinks -to code examples. However, care must be taken with the text, because -inline markup is recognized; there is no protection from parsing. -Backslash-escapes may be necessary in places. +to code examples. + +However, care must be taken with the text, because inline markup is +recognized and there is no protection from parsing. Backslash-escapes +may be necessary to prevent unintended parsing. And because the +markup characters are removed by the parser, care must also be taken +with vertical alignment. Parsed "ASCII art" is tricky, and extra +whitespace may be necessary. For example, all the element names in this content model are links:: -- cgit v1.2.1 From 0556d5c6b7da0ea8fc9c59bd0004b115ec689355 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 1 Jun 2004 21:25:34 +0000 Subject: added "table" directive docs git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2162 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 4d72e4c24..b75f52e51 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -545,6 +545,34 @@ Pull-Quote Produces a pull-quote-class block quote. See Epigraph_ above. +Table +===== + +:Directive Type: "table" +:Doctree Element: table +:Directive Arguments: 1, optional (table title). +:Directive Options: Possible. +:Directive Content: A normal reStructuredText table. + +The "table" directive is used to create a titled table, to associate a +title with a table:: + + .. table:: Truth table for "not" + + ===== ===== + A not A + ===== ===== + False True + True False + ===== ===== + +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the table element. See the + class_ directive below. + + ---------------- Document Parts ---------------- -- cgit v1.2.1 From 5d6ae98dbb5bdaeaf2e679f63d792fadea522a60 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 16:29:18 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2190 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index f72f8f140..fb8661789 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -44,8 +44,8 @@ ReStructuredText Primer`_. For complete technical details, see the .. _Introducing the Extensible Markup Language (XML): http://xml.coverpages.org/xmlIntro.html .. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _A ReStructuredText Primer: ../docs/rst/quickstart.html -.. _reStructuredText Markup Specification: rst/reStructuredText.html +.. _A ReStructuredText Primer: ../user/rst/quickstart.html +.. _reStructuredText Markup Specification: rst/restructuredtext.html ------------------- -- cgit v1.2.1 From 0890f4ef7aaedd7fbbcf1c97f8fd9e537e5c02b5 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 16:49:04 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2193 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index fb8661789..4be13e81d 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -4041,8 +4041,8 @@ immediately adjacent. See `Doctree Representation of Transitions`__ in `A Record of reStructuredText Syntax Alternatives`__. -__ rst/alternatives.txt#doctree-representation-of-transitions -__ rst/alternatives.txt +__ ../dev/rst/alternatives.txt#doctree-representation-of-transitions +__ ../dev/rst/alternatives.txt Details -- cgit v1.2.1 From 05aabf41e9ed2e35a6996f1e66b8f8ced70b2def Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 17:07:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2195 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 4be13e81d..5959849e4 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1581,7 +1581,7 @@ Details complete details, please see `RCS Keywords`_ in the `reStructuredText Markup Specification`_. - .. _RCS Keywords: rst/reStructuredText.html#rcs-keywords + .. _RCS Keywords: rst/restructuredtext.html#rcs-keywords Content Model @@ -4041,8 +4041,8 @@ immediately adjacent. See `Doctree Representation of Transitions`__ in `A Record of reStructuredText Syntax Alternatives`__. -__ ../dev/rst/alternatives.txt#doctree-representation-of-transitions -__ ../dev/rst/alternatives.txt +__ ../dev/rst/alternatives.html#doctree-representation-of-transitions +__ ../dev/rst/alternatives.html Details -- cgit v1.2.1 From b98a8f5204104fe344e6c262031812f66ae09756 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 17:36:35 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2198 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index b75f52e51..b9ea19ccd 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -36,11 +36,12 @@ Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document type definition. For directive implementation details, see `Creating reStructuredText Directives`_. -.. _Directives: reStructuredText.html#directives -.. _reStructuredText Markup Specification: reStructuredText.html +.. _Directives: restructuredtext.html#directives +.. _reStructuredText Markup Specification: restructuredtext.html .. _The Docutils Document Tree: ../doctree.html .. _Docutils Generic DTD: ../docutils.dtd -.. _Creating reStructuredText Directives: ../howto/rst-directives.html +.. _Creating reStructuredText Directives: + ../../howto/rst-directives.html ------------- @@ -1082,7 +1083,7 @@ Specific roles may support other options and/or directive content. See the `reStructuredText Interpreted Text Roles`_ document for details. -.. _reStructuredText Interpreted Text Roles: interpreted.html +.. _reStructuredText Interpreted Text Roles: roles.html Restructuredtext-Test-Directive -- cgit v1.2.1 From ac0e496a22d643632293773e7cadf4a924eecdcf Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 17:47:43 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2199 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/introduction.txt | 19 +++++++++---------- docs/ref/rst/roles.txt | 7 ++++--- 2 files changed, 13 insertions(+), 13 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index 13823b5b7..2b64399a5 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -34,10 +34,10 @@ http://docutils.sourceforge.net/rst.html. http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage .. _Setext: http://docutils.sourceforge.net/mirror/setext.html .. _Docutils: http://docutils.sourceforge.net/ -.. _A ReStructuredText Primer: ../../docs/rst/quickstart.html -.. _Quick reStructuredText: ../../docs/rst/quickref.html -.. _reStructuredText Markup Specification: reStructuredText.html -.. _Problems with StructuredText: problems.html +.. _A ReStructuredText Primer: ../../user/rst/quickstart.html +.. _Quick reStructuredText: ../../user/rst/quickref.html +.. _reStructuredText Markup Specification: restructuredtext.html +.. _Problems with StructuredText: ../../dev/rst/problems.html Goals @@ -281,8 +281,8 @@ followed. - `PEP 257: Docstring Conventions`__ Current working versions of the PEPs can be found in - http://docutils.sourceforge.net/spec/, and official versions can be - found in the `master PEP repository`_. + http://docutils.sourceforge.net/docs/peps/, and official versions + can be found in the `master PEP repository`_. __ http://mail.python.org/pipermail/doc-sig/2001-June/001855.html __ http://mail.python.org/pipermail/doc-sig/2001-June/001856.html @@ -296,10 +296,9 @@ followed. .. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ .. _StructuredTextNG: http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG -.. _project history file: http://docutils.sourceforge.net/HISTORY.html -.. _PEP 287: http://docutils.sourceforge.net/spec/pep-0287.html -.. _Docstring Processing System framework: - http://docutils.sourceforge.net/spec/pep-0256.html +.. _project history file: ../../../HISTORY.html +.. _PEP 287: ../../peps/pep-0287.html +.. _Docstring Processing System framework: ../../peps/pep-0256.html .. _comp.lang.python: news:comp.lang.python .. _Python-dev: http://mail.python.org/pipermail/python-dev/ .. _Docstring Processing System: http://docstring.sourceforge.net/ diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index d93a2bf9d..f619aae03 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -30,11 +30,12 @@ implementation details, see `Creating reStructuredText Interpreted Text Roles`_. .. _"role" directive: directives.html#role -.. _Interpreted Text: reStructuredText.html#interpreted-text -.. _reStructuredText Markup Specification: reStructuredText.html +.. _Interpreted Text: restructuredtext.html#interpreted-text +.. _reStructuredText Markup Specification: restructuredtext.html .. _The Docutils Document Tree: ../doctree.html .. _Docutils Generic DTD: ../docutils.dtd -.. _Creating reStructuredText Interpreted Text Roles: ../howto/rst-roles.html +.. _Creating reStructuredText Interpreted Text Roles: + ../../howto/rst-roles.html .. contents:: -- cgit v1.2.1 From b447165077e564a25c8d788a45000fd0b5e5ef27 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 17:52:31 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2200 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index f619aae03..4aa6b0337 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -191,9 +191,9 @@ Implements subscripts. See `the reStructuredText spec`__ for further information on `character-level markup`__ and `the substitution mechanism`__. - __ ./reStructuredText.html - __ ./reStructuredText.html#character-level-inline-markup - __ ./reStructuredText.html#substitution-references + __ restructuredtext.html + __ restructuredtext.html#character-level-inline-markup + __ restructuredtext.html#substitution-references ``:superscript:`` -- cgit v1.2.1 From c0b62760b263f06be663e126c42768c038a53a5a Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 19:01:31 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2203 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index dd1d13ba3..f5c045bb7 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -15,7 +15,7 @@ For background about transforms and the Transformer object, see `PEP 258`_. -.. _PEP 258: pep-0258.html#transformer +.. _PEP 258: ../peps/pep-0258.html#transformer Transforms Listed in Priority Order -- cgit v1.2.1 From d7920f44434f714f389c5a0c8ceb689179fa93aa Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 19:16:08 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2205 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 57b9df995..4a3740197 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -14,8 +14,8 @@ reStructuredText, please read `A ReStructuredText Primer`_ and the `Quick reStructuredText`_ user reference first. -.. _A ReStructuredText Primer: ../../docs/rst/quickstart.html -.. _Quick reStructuredText: ../../docs/rst/quickref.html +.. _A ReStructuredText Primer: ../../user/rst/quickstart.html +.. _Quick reStructuredText: ../../user/rst/quickref.html reStructuredText_ is plaintext that uses simple and intuitive @@ -2734,7 +2734,7 @@ Markup errors are handled according to the specification in `PEP .. _getopt.py: http://www.python.org/doc/current/lib/module-getopt.html .. _GNU libc getopt_long(): - http://www.gnu.org/manual/glibc-2.2.3/html_node/libc_516.html + http://www.gnu.org/software/libc/manual/html_node/Getopt-Long-Options.html .. _doctest module: http://www.python.org/doc/current/lib/module-doctest.html .. _Emacs table mode: http://table.sourceforge.net/ @@ -2746,11 +2746,11 @@ Markup errors are handled according to the specification in `PEP .. _HTML Techniques for Web Content Accessibility Guidelines: http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text .. _reStructuredText Directives: directives.html -.. _reStructuredText Interpreted Text Roles: interpreted.html +.. _reStructuredText Interpreted Text Roles: roles.html .. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt .. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt .. _Zope: http://www.zope.com/ -.. _PEP 258: http://docutils.sourceforge.net/spec/pep-0258.txt +.. _PEP 258: http://docutils.sourceforge.net/docs/peps/pep-0258.txt .. -- cgit v1.2.1 From 0b3190bf8e104cbba89ef3ed8b0863fc127e6eac Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 4 Jun 2004 21:40:07 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2217 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 4a3740197..a8d11753e 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1590,7 +1590,7 @@ reused, doubled and then tripled, and so on ("**" etc.). "xmlcharrefreplace" `output encoding error handler`__ (available in Python 2.3 & later). -__ http://docutils.sf.net/docs/config.html#output-encoding-error-handler +__ ../../user/config.html#output-encoding-error-handler Mixed Manual and Auto-Numbered Footnotes @@ -2750,7 +2750,7 @@ Markup errors are handled according to the specification in `PEP .. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt .. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt .. _Zope: http://www.zope.com/ -.. _PEP 258: http://docutils.sourceforge.net/docs/peps/pep-0258.txt +.. _PEP 258: ../../peps/pep-0258.html .. -- cgit v1.2.1 From 6c18a0548558d3eefb532ef613a49533328dd357 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 5 Jun 2004 19:32:15 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2223 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 5087d23d7..e4a1c27aa 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -12,7 +12,7 @@ More information about this DTD (document type definition) and the Docutils project can be found at http://docutils.sourceforge.net/. The latest version of this DTD is available from -http://docutils.sourceforge.net/spec/docutils.dtd. +http://docutils.sourceforge.net/docs/ref/docutils.dtd. The formal public identifier for this DTD is:: -- cgit v1.2.1 From d2efa0442ee4ca7ecc5b6e68d209434eae946f74 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 18 Jun 2004 21:36:55 +0000 Subject: added "csv-table" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2308 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 110 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 109 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index b9ea19ccd..58344966a 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -2,7 +2,7 @@ reStructuredText Directives ============================= :Author: David Goodger -:Contact: goodger@users.sourceforge.net +:Contact: goodger@python.org :Revision: $Revision$ :Date: $Date$ :Copyright: This document has been placed in the public domain. @@ -546,6 +546,17 @@ Pull-Quote Produces a pull-quote-class block quote. See Epigraph_ above. +-------- + Tables +-------- + +Formal tables need more structure than the reStructuredText syntax +supplies. Tables may be given titles with the table_ directive. +Sometimes reStructuredText tables are inconvenient to write, or table +data in a standard format is readily available. The csvtable_ +directive supports CSV data. + + Table ===== @@ -574,6 +585,103 @@ The following option is recognized: class_ directive below. +.. _csvtable: + +CSV Table +========= + +:Directive Type: "csvtable" +:Doctree Element: table +:Directive Arguments: 1, optional (table title). +:Directive Options: Possible. +:Directive Content: A CSV (comma-separated values) table. + +The "csvtable" directive is used to create a table from CSV +(comma-separated values) data. CSV is a common data format generated +by spreadsheet applications and commercial databases. The data may be +internal (an integral part of the document) or external (a separate +file). + +Example:: + + .. csvtable:: Frozen Delights! + :headers: "Treat", "Quantity", "Description" + :widths: 15, 10, 30 + + "Albatross", 2.99, "On a stick!" + "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be + crunchy, now would it?" + "Gannet Ripple", 1.99, "On a stick!" + +Block markup and inline markup within cells is supported. Line ends +are recognized within cells. + +Working Limitations:: + +* Whitespace delimiters are supported only for external CSV files. + +* There is no support for checking that the number of columns in each + row is the same. However, this directive supports CSV generators + that do not insert "empty" entries at the end of short rows, by + automatically adding empty entries. + + .. Add "strict" option to verify input? + +* Due to limitations of the CSV parser, this directive is not Unicode + compatible. It may also have problems with ASCII NUL characters. + Accordingly, CSV tables should be ASCII-printable safe. + + .. Test with Unicode; see if that's really so. "encoding" option? + +The following options are recognized: + +``class`` : text + Set a "class" attribute value on the table element. See the + class_ directive below. + +``widths`` : integer [, integer...] + A comma-separated list of relative column widths. The default is + equal-width columns (100%/#columns). + +``header-rows`` : integer + The number of rows of CSV data to use in the table header. + Defaults to 0. + +``header`` : CSV data + Supplemental data for the table header, added independently of and + before any ``header-rows`` from the main CSV data. Must use the + same CSV format as the main CSV data. + +``file`` | ``url`` : path + Path or URL to CSV file. + +``delim`` : char | "tab" | "space" + A one-character string used to separate fields. Defaults to ``,`` + (comma). May be specified as a Unicode code point; see the + unicode_ directive for syntax details. + +``quote`` : char + A one-character string used to quote elements containing the + delimiter or which start with the quote character. Defaults to + ``"`` (quote). May be specified as a Unicode code point; see the + unicode_ directive for syntax details. + +``keepspace`` : flag + Treat whitespace immediately following the delimiter as + significant. The default is to ignore such whitespace. + +``escape`` : char + A one-character string used to escape the delimiter or quote + characters. May be specified as a Unicode code point; see the + unicode_ directive for syntax details. Used when the delimiter is + used in an unquoted field, or when quote characters are used + within a field. The default is to double-up the character, + e.g. "He said, ""Hi!""" + + .. Add another possible value, "double", to explicitly indicate + the default case? + + ---------------- Document Parts ---------------- -- cgit v1.2.1 From 977fd8f4c35fd7315020049f72d11a6a79759a70 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 18 Jun 2004 21:50:50 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2310 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 58344966a..0e12c0b5b 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -616,7 +616,7 @@ Example:: Block markup and inline markup within cells is supported. Line ends are recognized within cells. -Working Limitations:: +Working limitations: * Whitespace delimiters are supported only for external CSV files. -- cgit v1.2.1 From d667bc26fbe5faf6ce0bfd50beadd93fe1b5602d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 19 Jun 2004 22:54:20 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2315 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 0e12c0b5b..2fdc4ba6e 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -553,7 +553,7 @@ Produces a pull-quote-class block quote. See Epigraph_ above. Formal tables need more structure than the reStructuredText syntax supplies. Tables may be given titles with the table_ directive. Sometimes reStructuredText tables are inconvenient to write, or table -data in a standard format is readily available. The csvtable_ +data in a standard format is readily available. The csv-table_ directive supports CSV data. @@ -566,6 +566,8 @@ Table :Directive Options: Possible. :Directive Content: A normal reStructuredText table. +(New in Docutils 0.3.1) + The "table" directive is used to create a titled table, to associate a title with a table:: @@ -585,18 +587,28 @@ The following option is recognized: class_ directive below. -.. _csvtable: +.. _csv-table: CSV Table ========= -:Directive Type: "csvtable" +:Directive Type: "csv-table" :Doctree Element: table :Directive Arguments: 1, optional (table title). :Directive Options: Possible. :Directive Content: A CSV (comma-separated values) table. -The "csvtable" directive is used to create a table from CSV +.. Warning:: + + The "csv-table" directive requires the ``csv.py`` module of the + Python standard library, which was added in Python 2.3. It will + not work with earlier versions of Python. Using the "csv-table" + directive in a document will make the document **incompatible** + with systems using Python 2.1 or 2.2. + +(New in Docutils 0.3.4) + +The "csv-table" directive is used to create a table from CSV (comma-separated values) data. CSV is a common data format generated by spreadsheet applications and commercial databases. The data may be internal (an integral part of the document) or external (a separate @@ -604,7 +616,7 @@ file). Example:: - .. csvtable:: Frozen Delights! + .. csv-table:: Frozen Delights! :headers: "Treat", "Quantity", "Description" :widths: 15, 10, 30 @@ -1124,6 +1136,8 @@ Custom Interpreted Text Roles :Directive Options: Possible (depends on base role). :Directive Content: depends on base role. +(New in Docutils 0.3.2) + The "role" directive dynamically creates a custom interpreted text role and registers it with the parser. This means that after declaring a role like this:: -- cgit v1.2.1 From daf7c5148f8704e5a90018fcc02d3c5297253436 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 28 Jun 2004 19:24:55 +0000 Subject: updated uri recognition git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2410 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index a8d11753e..7f72a1b7f 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2700,7 +2700,8 @@ Two forms of URI are recognized: someone@somewhere.com -Punctuation at the end of a URI is not considered part of the URI. +Punctuation at the end of a URI is not considered part of the URI, +unless the URI is terminated by a closing angle bracket (">"). Backslashes may be used in URIs to escape markup characters, specifically asterisks ("*") and underscores ("_") which are vaid URI characters (see `Escaping Mechanism`_ above). -- cgit v1.2.1 From 253d5324a1754ddda972807b0e2ff6303c3dbef4 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 Jul 2004 18:35:09 +0000 Subject: xmlcharrefreplace backport git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2448 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 7f72a1b7f..a9d2b4afa 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1587,8 +1587,7 @@ reused, doubled and then tripled, and so on ("**" etc.). in certain common text encodings such as Latin-1 (ISO 8859-1). The use of UTF-8 for the output encoding is recommended. An alternative for HTML and XML output is to use the - "xmlcharrefreplace" `output encoding error handler`__ (available in - Python 2.3 & later). + "xmlcharrefreplace" `output encoding error handler`__. __ ../../user/config.html#output-encoding-error-handler -- cgit v1.2.1 From 1c206de44a70d86e24a631acd3ac118cdd2ed4f6 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 26 Jul 2004 23:11:15 +0000 Subject: clarified unicode directive documentation git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2461 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 2fdc4ba6e..70591cc15 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1052,14 +1052,33 @@ Unicode Character Codes The "unicode" directive converts Unicode character codes (numerical values) to characters, and may be used in substitution definitions -only. Codes may be decimal numbers, hexadecimal numbers (prefixed by -``0x``, ``x``, ``\x``, ``U+``, ``u``, or ``\u``), or XML-style numeric -character entities (e.g. ``ᨫ``). Codes are case-insensitive. +only. -Text following " .. " is a comment and is ignored. Spaces are -ignored, and any other text remains as-is. +The arguments, separated by spaces, can be: -Example:: +* **character codes** as + + - decimal numbers or + + - hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``, + ``u``, or ``\u`` or as XML-style hexadecimal character entities, + e.g. ``ᨫ`` + +* **text**, which is used as-is. + +Text following " .. " is a comment and is ignored. The spaces between +the arguments are ignored and thus do not appear in the output. +Hexadecimal codes are case-insensitive. + +For example, the following text:: + + Copyright |copy| 2003, |BogusMegaCorp (TM)|. + + .. |copy| unicode:: 0xA9 .. copyright sign + .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 + .. with trademark sign + +results in: Copyright |copy| 2003, |BogusMegaCorp (TM)|. -- cgit v1.2.1 From 14d88a0e6bc1921b02952fc27b847121ea9ff2b1 Mon Sep 17 00:00:00 2001 From: lele <lele@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 20 Aug 2004 08:00:43 +0000 Subject: The directive now accepts a prefix option, a string that will be prepended to the generated section enumeration, and a start value, an integer used as the starting value for auto-numbering the sections. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2533 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 70591cc15..beb02f9d7 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -794,7 +794,17 @@ The following options are recognized: The number of section levels that are numbered by this directive. The default is unlimited depth. - +``prefix`` : string + A string that will precede the automatically generated numbering. + It usually is, but not needs to, something like "3.2", that will + produce "3.2.1", "3.2.2", "3.2.2.1", and so on. + It defaults to nothing. + +``start`` : integer + The number that will be used for the first section. Combined with + ``prefix``, this may be used to force the right numbering for + document splitted over several sources. The default is 1. + ------------ References ------------ -- cgit v1.2.1 From 96cef63ca0e73f97052a3286d8480b7ea870313e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 23 Aug 2004 17:35:50 +0000 Subject: added "suffix" option to "sectnum" directive; require separating punctuation git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2539 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index beb02f9d7..905a51acf 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -795,16 +795,23 @@ The following options are recognized: The default is unlimited depth. ``prefix`` : string - A string that will precede the automatically generated numbering. - It usually is, but not needs to, something like "3.2", that will - produce "3.2.1", "3.2.2", "3.2.2.1", and so on. - It defaults to nothing. - + An arbitrary string that is prefixed to the automatically + generated section numbers. It may be something like "3.2.", which + will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that + any separating punctuation (in the example, a period, ".") must be + explicitly provided. The default is no prefix. + +``suffix`` : string + An arbitrary string that is appended to the automatically + generated section numbers. The default is no suffix. + ``start`` : integer - The number that will be used for the first section. Combined with - ``prefix``, this may be used to force the right numbering for - document splitted over several sources. The default is 1. - + The value that will be used for the first section number. + Combined with ``prefix``, this may be used to force the right + numbering for a document split over several source files. The + default is 1. + + ------------ References ------------ -- cgit v1.2.1 From ace27f44c42828eebaed0a7d2b9e532cff048f4f Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 25 Aug 2004 20:08:32 +0000 Subject: fixed csv-table documentation git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2543 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 905a51acf..3a9b311c4 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -617,7 +617,7 @@ file). Example:: .. csv-table:: Frozen Delights! - :headers: "Treat", "Quantity", "Description" + :header: "Treat", "Quantity", "Description" :widths: 15, 10, 30 "Albatross", 2.99, "On a stick!" -- cgit v1.2.1 From f3aa787d95ca9355050f76b4a849610bbeeace5c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 8 Sep 2004 19:49:33 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2562 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 5959849e4..494edc9df 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -157,7 +157,7 @@ warning_ Simple Body Elements -------------------- -Simple body elements directly are empty or contain text data. Those +Simple body elements are empty or directly contain text data. Those that contain text data may also contain inline elements. Such elements therefore have a "mixed content model". -- cgit v1.2.1 From e4a24412d613ad05d37269456420b4afd9233eb8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 12 Sep 2004 00:26:50 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2582 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 3a9b311c4..830b63132 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -505,7 +505,12 @@ Epigraph :Directive Options: None. :Directive Content: Interpreted as the body of the block quote. -Produces an epigraph-class block quote. For example, this input:: +An epigraph is an apposite (suitable, apt, or pertinent) short +inscription, often a quotation or poem, at the beginning of a document +or section. + +The "epigraph" directive produces an "epigraph"-class block quote. +For example, this input:: .. epigraph:: @@ -531,7 +536,11 @@ Highlights :Directive Options: None. :Directive Content: Interpreted as the body of the block quote. -Produces a highlights-class block quote. See Epigraph_ above. +Highlights summarize the main points of a document or section, often +consisting of a list. + +The "highlights" directive produces a "highlights"-class block quote. +See Epigraph_ above for an analogous example. Pull-Quote @@ -543,7 +552,12 @@ Pull-Quote :Directive Options: None. :Directive Content: Interpreted as the body of the block quote. -Produces a pull-quote-class block quote. See Epigraph_ above. +A pull-quote is a small selection of text "pulled out and quoted", +typically in a larger typeface. Pull-quotes are used to attract +attention, especially in long articles. + +The "pull-quote" directive produces a "pull-quote"-class block quote. +See Epigraph_ above for an analogous example. -------- @@ -667,6 +681,10 @@ The following options are recognized: ``file`` | ``url`` : path Path or URL to CSV file. +``encoding`` : name of text encoding + The text encoding of the external CSV data (file or URL). + Defaults to the document's encoding (if specified). + ``delim`` : char | "tab" | "space" A one-character string used to separate fields. Defaults to ``,`` (comma). May be specified as a Unicode code point; see the @@ -976,6 +994,10 @@ The following options are recognized: The entire included text is inserted into the document as a single literal block (useful for program listings). +``encoding`` : name of text encoding + The text encoding of the external data file. Defaults to the + document's encoding (if specified). + .. _raw: @@ -1020,9 +1042,14 @@ The following options are recognized: ``file`` : string The local filesystem path of a raw data file to be included. + ``url`` : string An Internet URL reference to a raw data file to be included. +``encoding`` : name of text encoding + The text encoding of the external raw data (file or URL). + Defaults to the document's encoding (if specified). + .. _replace: -- cgit v1.2.1 From d302014fd7d76cefe4ecffa383e0620df7b77716 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 5 Oct 2004 01:21:41 +0000 Subject: Changed structure of the ``line_block`` element; added ``line``. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2688 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index e4a1c27aa..ff75b03d7 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -369,10 +369,11 @@ or " ") or the text between option arguments (typically either "," or %basic.atts; %fixedspace.att;> -<!ELEMENT line_block %text.model;> -<!ATTLIST line_block - %basic.atts; - %fixedspace.att;> +<!ELEMENT line_block ((line | line_block)+)> +<!ATTLIST line_block %basic.atts;> + +<!ELEMENT line %text.model;> +<!ATTLIST line %basic.atts;> <!ELEMENT block_quote ((%body.elements;)+, attribution?)> <!ATTLIST block_quote %basic.atts;> -- cgit v1.2.1 From d6c6e58281cf11508860db0126fa6af6d4a2bc37 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 5 Oct 2004 01:21:54 +0000 Subject: Marked "line-block" as deprecated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2690 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 830b63132..685c6c446 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -394,16 +394,23 @@ The following options are recognized: Line Block ========== +.. admonition:: Deprecated + + The "line-block" directive is deprecated. Use the `line block + syntax`_ instead. + + .. _line block syntax: restructuredtext.html#line-blocks + :Directive Type: "line-block" :Doctree Element: line_block :Directive Arguments: None. :Directive Options: Possible. :Directive Content: Becomes the body of the line block. -The "line-block" directive constructs an element where whitespace -(including linebreaks) is significant and inline markup is supported. -It is equivalent to a `parsed literal block`_ with different -rendering: typically in an ordinary serif typeface instead of a +The "line-block" directive constructs an element where line breaks and +initial indentation is significant and inline markup is supported. It +is equivalent to a `parsed literal block`_ with different rendering: +typically in an ordinary serif typeface instead of a typewriter/monospaced face, and not automatically indented. (Have the line-block directive begin a block quote to get an indented line block.) Line blocks are useful for address blocks and verse (poetry, -- cgit v1.2.1 From dafc96d688fd9f836310f6084ee41bbb8311cc13 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 5 Oct 2004 01:22:01 +0000 Subject: Added syntax for line blocks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2691 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 51 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index a9d2b4afa..5b05f952d 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1153,6 +1153,57 @@ Syntax diagram:: +------------------------------+ +Line Blocks +----------- + +Doctree elements: line_block, line. + +Line blocks are useful for address blocks, verse (poetry, song +lyrics), and unadorned lists, where the structure of lines is +significant. Line blocks are groups of lines beginning with vertical +bar ("|") prefixes. Each vertical bar prefix indicates a new line, so +line breaks are preserved. Initial indents are also significant, +resulting in a nested structure. Inline markup is supported. +Continuation lines are wrapped portions of long lines; they begin with +a space in place of the vertical bar. The left edge of a continuation +line must be indented, but need not be aligned with the left edge of +the text above it. A line block ends with a blank line. + +This example illustrates continuation lines:: + + | Lend us a couple of bob till Thursday. + | I'm absolutely skint. + | But I'm expecting a postal order and I can pay you back + as soon as it comes. + | Love, Ewan. + +This example illustrates the nesting of line blocks, indicated by the +initial indentation of new lines:: + + Take it away, Eric the Orchestra Leader! + + | A one, two, a one two three four + | + | Half a bee, philosophically, + | must, *ipso facto*, half not be. + | But half the bee has got to be, + | *vis a vis* its entity. D'you see? + | + | But can a bee be said to be + | or not to be an entire bee, + | when half the bee is not a bee, + | due to some ancient injury? + | + | Singing... + +Syntax diagram:: + + +------+-----------------------+ + | "| " | line | + +------| continuation line | + +-----------------------+ + + Block Quotes ------------ -- cgit v1.2.1 From 198d5c5a45884775674de0dd52aeae523128ad7b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 5 Oct 2004 01:27:41 +0000 Subject: new in 0.3.5 git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2700 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 5b05f952d..f8c7787f4 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1156,7 +1156,7 @@ Syntax diagram:: Line Blocks ----------- -Doctree elements: line_block, line. +Doctree elements: line_block, line. New in Docutils 0.3.5. Line blocks are useful for address blocks, verse (poetry, song lyrics), and unadorned lists, where the structure of lines is -- cgit v1.2.1 From 213315b799f5fe8f0e18afc129d89e45204f5317 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 19 Oct 2004 22:40:53 +0000 Subject: minor cleanup git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2719 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index ff75b03d7..4a8c15cf1 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -209,7 +209,7 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT docinfo (%bibliographic.elements;)+> <!ATTLIST docinfo %basic.atts;> -<!-- Container for bibliographic elements. May not be empty. +<!-- Container for bibliographic elements. May not be empty. Eventual replacement for docinfo? --> <!ELEMENT info (%bibliographic.elements;)+> <!ATTLIST info %basic.atts;> @@ -217,7 +217,7 @@ Eventual replacement for docinfo? --> <!ELEMENT author %text.model;> <!ATTLIST author %basic.atts;> -<!ELEMENT authors ((author, organization?, address?, contact?)+)> +<!ELEMENT authors (author, organization?, address?, contact?)+> <!ATTLIST authors %basic.atts;> <!ELEMENT organization %text.model;> @@ -257,7 +257,7 @@ Eventual replacement for docinfo? --> <!ELEMENT header (%body.elements;)+> <!ATTLIST header %basic.atts;> - + <!ELEMENT footer (%body.elements;)+> <!ATTLIST footer %basic.atts;> @@ -267,7 +267,7 @@ Eventual replacement for docinfo? --> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> -<!ELEMENT section +<!ELEMENT section (title, subtitle?, info?, decoration?, %structure.model;)> <!ATTLIST section %basic.atts;> @@ -369,7 +369,7 @@ or " ") or the text between option arguments (typically either "," or %basic.atts; %fixedspace.att;> -<!ELEMENT line_block ((line | line_block)+)> +<!ELEMENT line_block (line | line_block)+> <!ATTLIST line_block %basic.atts;> <!ELEMENT line %text.model;> -- cgit v1.2.1 From 50ecea709bc5fe58c4f9085b4f6fa545e6927d25 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 19 Oct 2004 22:42:19 +0000 Subject: minor cleanup git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2720 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 4a8c15cf1..a9338d03a 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -115,7 +115,8 @@ resolve to either an internal or external reference. <!ENTITY % additional.body.elements ""> <!ENTITY % body.elements - " paragraph | literal_block | doctest_block | line_block | block_quote + " paragraph | compound | literal_block | doctest_block + | line_block | block_quote | table | figure | image | footnote | citation | rubric | bullet_list | enumerated_list | definition_list | field_list | option_list @@ -289,6 +290,9 @@ Eventual replacement for docinfo? --> <!ELEMENT paragraph %text.model;> <!ATTLIST paragraph %basic.atts;> +<!ELEMENT compound (%body.elements;)+> +<!ATTLIST compound %basic.atts;> + <!ELEMENT bullet_list (list_item+)> <!ATTLIST bullet_list %basic.atts; -- cgit v1.2.1 From 1b6b9da73c02f1784c85d5e2bd69147abfe6d03c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 19 Oct 2004 22:45:32 +0000 Subject: oops; revert 1.30 git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2721 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index a9338d03a..4a8c15cf1 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -115,8 +115,7 @@ resolve to either an internal or external reference. <!ENTITY % additional.body.elements ""> <!ENTITY % body.elements - " paragraph | compound | literal_block | doctest_block - | line_block | block_quote + " paragraph | literal_block | doctest_block | line_block | block_quote | table | figure | image | footnote | citation | rubric | bullet_list | enumerated_list | definition_list | field_list | option_list @@ -290,9 +289,6 @@ Eventual replacement for docinfo? --> <!ELEMENT paragraph %text.model;> <!ATTLIST paragraph %basic.atts;> -<!ELEMENT compound (%body.elements;)+> -<!ATTLIST compound %basic.atts;> - <!ELEMENT bullet_list (list_item+)> <!ATTLIST bullet_list %basic.atts; -- cgit v1.2.1 From 4c33f7f3d0c6c99f4ffd3ebf86f96f509805bdcc Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 19 Oct 2004 22:46:07 +0000 Subject: added "compound" element git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2722 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 4a8c15cf1..a9338d03a 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -115,7 +115,8 @@ resolve to either an internal or external reference. <!ENTITY % additional.body.elements ""> <!ENTITY % body.elements - " paragraph | literal_block | doctest_block | line_block | block_quote + " paragraph | compound | literal_block | doctest_block + | line_block | block_quote | table | figure | image | footnote | citation | rubric | bullet_list | enumerated_list | definition_list | field_list | option_list @@ -289,6 +290,9 @@ Eventual replacement for docinfo? --> <!ELEMENT paragraph %text.model;> <!ATTLIST paragraph %basic.atts;> +<!ELEMENT compound (%body.elements;)+> +<!ATTLIST compound %basic.atts;> + <!ELEMENT bullet_list (list_item+)> <!ATTLIST bullet_list %basic.atts; -- cgit v1.2.1 From 69b8abd9c0622b034d97f1b860314544d101554b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 20 Oct 2004 14:07:12 +0000 Subject: added "compound" directive docs git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2735 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 50 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 685c6c446..9c54d7d43 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -567,6 +567,56 @@ The "pull-quote" directive produces a "pull-quote"-class block quote. See Epigraph_ above for an analogous example. +.. _compound: + +Compound Paragraph +================== + +:Directive Type: "compound" +:Doctree Element: compound +:Directive Arguments: None. +:Directive Options: Possible. +:Directive Content: Interpreted as body elements. + +(New in Docutils 0.3.6) + +The "compound" directive is used to create a compound paragraph, which +is a single logical paragraph containing multiple physical body +elements such as simple paragraphs, literal blocks, tables, lists, +etc., instead of directly containing text and inline elements. For +example:: + + .. compound:: + + The 'rm' command is very dangerous. If you are logged + in as root and enter these commands :: + + cd / + rm -rf * + + you will erase the entire contents of your file system. + +In the example above, a literal block is "embedded" within a sentence +that begins in one physical paragraph and ends in another. A compound +paragraph + +Compound paragraphs are typically rendered as multiple distinct text +blocks, with the possibility of variations to emphasize their logical +unity: + +* If paragraphs are rendered with a first-line indent, only the first + physical paragraph of a compound paragraph should have that indent + -- second and further physical paragraphs should omit the indents; +* vertical spacing between physical elements may be reduced; +* and so on. + +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the compound element. See the + class_ directive below. + + -------- Tables -------- -- cgit v1.2.1 From 4ffd31813cec1cbfc7b713b258cf0c0aa527c7c8 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 20 Oct 2004 16:22:04 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2739 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 9c54d7d43..07571f11e 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -589,7 +589,7 @@ example:: .. compound:: The 'rm' command is very dangerous. If you are logged - in as root and enter these commands :: + in as root and enter these commands:: cd / rm -rf * @@ -597,8 +597,7 @@ example:: you will erase the entire contents of your file system. In the example above, a literal block is "embedded" within a sentence -that begins in one physical paragraph and ends in another. A compound -paragraph +that begins in one physical paragraph and ends in another. Compound paragraphs are typically rendered as multiple distinct text blocks, with the possibility of variations to emphasize their logical -- cgit v1.2.1 From 7d9d0adc58d9bdd341d3aed623e2717f9da9d46e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 21 Oct 2004 03:34:22 +0000 Subject: reworked text; this one is not a typo (no colon desired) git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2753 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 07571f11e..e0328d94c 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -589,7 +589,7 @@ example:: .. compound:: The 'rm' command is very dangerous. If you are logged - in as root and enter these commands:: + in as root and enter :: cd / rm -rf * -- cgit v1.2.1 From b88302881a584c7dc5382b1b9188fb73392fd4f1 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 30 Oct 2004 14:23:32 +0000 Subject: updated DTD to allow transitions between sections git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2777 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index a9338d03a..faaf3f6de 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -141,10 +141,11 @@ resolve to either an internal or external reference. ================================================================== --> <!ENTITY % structure.model - " ( ( (%body.elements; | topic | sidebar)+, - (transition, (%body.elements; | topic | sidebar)+ )*, - (%section.elements;)* ) - | (%section.elements;)+ ) "> + " ( ( (%body.elements; | topic | sidebar)+, + (transition, (%body.elements; | topic | sidebar)+ )*, + ( (%section.elements;), (transition?, (%section.elements;) )* ) ) + | ( (%section.elements;), (transition?, (%section.elements;) )* ) +) "> <!ENTITY % text.model " (#PCDATA | %inline.elements;)* "> @@ -182,7 +183,9 @@ http://www.oasis-open.org/html/tm9901.htm). <!-- Optional elements may be generated by internal processing. --> <!ELEMENT document - ((title, subtitle?)?, docinfo?, decoration?, %structure.model;)> + ((title, subtitle?)?, + ((docinfo, decoration?, transition?) | decoration?), + %structure.model;)> <!ATTLIST document %basic.atts;> <!-- -- cgit v1.2.1 From b9c1c9c56d4ae9d46d4430dc9897eb88261b3426 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 30 Oct 2004 14:26:27 +0000 Subject: updated transition entry to allow transitions between sections git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2778 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 494edc9df..df0f87836 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -4035,8 +4035,8 @@ The ``transition`` element is commonly seen in novels and short fiction, as a gap spanning one or more lines, with or without a type ornament such as a row of asterisks. Transitions separate other body elements, dividing a section into untitled divisions. A transition -may not begin or end a section or document, nor may two transitions be -immediately adjacent. +may not begin or end a document, it may not begin a section, nor may +two transitions be immediately adjacent. See `Doctree Representation of Transitions`__ in `A Record of reStructuredText Syntax Alternatives`__. -- cgit v1.2.1 From 7aeaf16a20b59ea5f41ae499c6c71bc8895bda66 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 31 Oct 2004 02:48:02 +0000 Subject: bugfix: show that a section element is *not* required (reported by Jason Diamond) git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2785 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index faaf3f6de..de4a20428 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -143,7 +143,7 @@ resolve to either an internal or external reference. <!ENTITY % structure.model " ( ( (%body.elements; | topic | sidebar)+, (transition, (%body.elements; | topic | sidebar)+ )*, - ( (%section.elements;), (transition?, (%section.elements;) )* ) ) + ( (%section.elements;), (transition?, (%section.elements;) )* )? ) | ( (%section.elements;), (transition?, (%section.elements;) )* ) ) "> -- cgit v1.2.1 From 03248e5ee900dac994a614cc7ce48675da9ff409 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 31 Oct 2004 16:32:14 +0000 Subject: removed line break git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2786 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index de4a20428..e4b3969c4 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -144,8 +144,7 @@ resolve to either an internal or external reference. " ( ( (%body.elements; | topic | sidebar)+, (transition, (%body.elements; | topic | sidebar)+ )*, ( (%section.elements;), (transition?, (%section.elements;) )* )? ) - | ( (%section.elements;), (transition?, (%section.elements;) )* ) -) "> + | ( (%section.elements;), (transition?, (%section.elements;) )* ) ) "> <!ENTITY % text.model " (#PCDATA | %inline.elements;)* "> -- cgit v1.2.1 From 1c8a3342764f052f45c613f8a3ec44b373fd790d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 31 Oct 2004 16:32:56 +0000 Subject: clarified transition description; updated %structure.model; git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2787 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index df0f87836..5a5154fe7 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -4033,14 +4033,19 @@ Pseudo-XML_ fragment from simple parsing:: The ``transition`` element is commonly seen in novels and short fiction, as a gap spanning one or more lines, with or without a type -ornament such as a row of asterisks. Transitions separate other body -elements, dividing a section into untitled divisions. A transition -may not begin or end a document, it may not begin a section, nor may +ornament such as a row of asterisks. Transitions separate body +elements and sections, dividing a section into untitled divisions. A +transition may not begin or end a section [#]_ or document, nor may two transitions be immediately adjacent. See `Doctree Representation of Transitions`__ in `A Record of reStructuredText Syntax Alternatives`__. +.. [#] In reStructuredText markup, a transition may appear to fall at + the end of a section immediately before another section. A + transform recognizes this case and moves the transition so it + separates the sections. + __ ../dev/rst/alternatives.html#doctree-representation-of-transitions __ ../dev/rst/alternatives.html @@ -4800,18 +4805,19 @@ Entity definition: ( ( (`%body.elements;`_ | topic_ | sidebar_)+, (transition_, (`%body.elements;`_ | topic_ | sidebar_)+ )*, - (`%section.elements;`_)* ) - | (`%section.elements;`_)+ ) + ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? ) + | ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* ) ) "> Each document_ or section_ contains either: - multiple body elements, topics, and/or sidebars, optionally interspersed with transitions (but transitions cannot occur at the beginning or end, nor may there be two transitions in a row), - followed by zero or more sections; or + followed by zero or more sections optionally interspersed with + transitions; or -- one or more sections (whose contents are recursively the same as this - model). +- one or more sections (whose contents are recursively the same as + this model) optionally interspersed with transitions. The `%structure.model;`_ parameter entity is directly employed in the content models of the document_ and section_ elements. -- cgit v1.2.1 From 24d4065f5785182b80be6777df2788a67d247742 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 31 Oct 2004 17:49:42 +0000 Subject: fixed error: name and dupname are CDATA, e.g. name="this is a test" git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2788 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index e4b3969c4..6970b19b7 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -51,8 +51,8 @@ Attributes shared by all elements in this DTD: --> <!ENTITY % basic.atts " id ID #IMPLIED - name NMTOKENS #IMPLIED - dupname NMTOKENS #IMPLIED + name CDATA #IMPLIED + dupname CDATA #IMPLIED source CDATA #IMPLIED class NMTOKENS #IMPLIED %additional.basic.atts; "> -- cgit v1.2.1 From 8ba1d9d714d6bfe722332deeeaa279ac6cc11eb1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 2 Nov 2004 22:14:08 +0000 Subject: Added "ltrim" and "rtrim" attributes to ``substitution_definition`` element. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2794 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 6970b19b7..5d858b2a8 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -447,7 +447,10 @@ or " ") or the text between option arguments (typically either "," or %anonymous.att;> <!ELEMENT substitution_definition %text.model;> -<!ATTLIST substitution_definition %basic.atts;> +<!ATTLIST substitution_definition + %basic.atts; + ltrim %yesorno; #IMPLIED + rtrim %yesorno; #IMPLIED> <!ELEMENT comment (#PCDATA)> <!ATTLIST comment -- cgit v1.2.1 From b3e9a23e50a601b58933870569c83a8aff859c5e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 2 Nov 2004 22:14:14 +0000 Subject: Added "trim", "ltrim", and "rtrim" options to "unicode" directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2795 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index e0328d94c..60058ac27 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1147,7 +1147,7 @@ Unicode Character Codes :Doctree Element: Text :Directive Arguments: One or more, required (Unicode character codes, optional text, and comments). -:Directive Options: None. +:Directive Options: Possible. :Directive Content: None. The "unicode" directive converts Unicode character codes (numerical @@ -1175,6 +1175,7 @@ For example, the following text:: Copyright |copy| 2003, |BogusMegaCorp (TM)|. .. |copy| unicode:: 0xA9 .. copyright sign + :ltrim: .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 .. with trademark sign @@ -1183,9 +1184,22 @@ results in: Copyright |copy| 2003, |BogusMegaCorp (TM)|. .. |copy| unicode:: 0xA9 .. copyright sign + :ltrim: .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 .. with trademark sign +The following options are recognized: + +``ltrim`` : flag + Whitespace to the left of the substitution reference is removed. + +``rtrim`` : flag + Whitespace to the right of the substitution reference is removed. + +``trim`` : flag + Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides + of the substitution reference is removed. + Class ===== -- cgit v1.2.1 From b7ca1d367a9b0c8fbb13e5e9434586a0a025752b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 2 Nov 2004 22:25:37 +0000 Subject: improved example git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2798 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 60058ac27..727327cd3 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1172,21 +1172,25 @@ Hexadecimal codes are case-insensitive. For example, the following text:: - Copyright |copy| 2003, |BogusMegaCorp (TM)|. + Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| + all rights reserved. .. |copy| unicode:: 0xA9 .. copyright sign - :ltrim: .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 .. with trademark sign + .. |---| unicode:: U+02014 .. em dash + :trim: results in: - Copyright |copy| 2003, |BogusMegaCorp (TM)|. + Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| + all rights reserved. .. |copy| unicode:: 0xA9 .. copyright sign - :ltrim: .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 .. with trademark sign + .. |---| unicode:: U+02014 .. em dash + :trim: The following options are recognized: -- cgit v1.2.1 From a6a2dd50bbaaea7412ef021329d7b3b518636583 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 3 Nov 2004 14:31:26 +0000 Subject: Enabled multiple format names for "raw" directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2799 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 2 +- docs/ref/rst/directives.txt | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 5d858b2a8..86f4e0357 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -500,7 +500,7 @@ Table elements: table, tgroup, colspec, thead, tbody, row, entry. <!ATTLIST raw %basic.atts; %fixedspace.att; - format NMTOKEN #IMPLIED> + format NMTOKENS #IMPLIED> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 727327cd3..a58c82bbc 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1062,16 +1062,16 @@ Raw Data Pass-Through :Directive Type: "raw" :Doctree Element: raw -:Directive Arguments: One, required (output format type). +:Directive Arguments: One or more, required (output format types). :Directive Options: Possible. :Directive Content: Stored verbatim, uninterpreted. None (empty) if a "file" or "url" option given. 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 first argument. The interpretation of the raw data is up -to the Writer. A Writer may ignore any raw output not matching its -format. +passed untouched to the Writer. The names of the output formats are +given in the directive arguments. The interpretation of the raw data +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:: -- cgit v1.2.1 From d6c369f56f8d5fcfcacd54c03aa3c50557593b3d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 3 Nov 2004 20:10:39 +0000 Subject: Enabled multiple classifiers in ``definition_list_item`` elements. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2800 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 86f4e0357..71636c152 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -316,7 +316,7 @@ Eventual replacement for docinfo? --> <!ELEMENT definition_list (definition_list_item+)> <!ATTLIST definition_list %basic.atts;> -<!ELEMENT definition_list_item (term, classifier?, definition)> +<!ELEMENT definition_list_item (term, classifier*, definition)> <!ATTLIST definition_list_item %basic.atts;> <!ELEMENT term %text.model;> -- cgit v1.2.1 From 09367b914711e1c22a65e1e82dc421c4d45a5b85 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 3 Nov 2004 20:10:50 +0000 Subject: Definition list items may have multiple classifiers. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2801 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index f8c7787f4..a5cd99745 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -740,10 +740,10 @@ Definition Lists Doctree elements: definition_list, definition_list_item, term, classifier, definition. -Each definition list item contains a term, an optional classifier, and -a definition. A term is a simple one-line word or phrase. An -optional classifier may follow the term on the same line, after an -inline " : " (space, colon, space). A definition is a block indented +Each definition list item contains a term, optional classifiers, and a +definition. A term is a simple one-line word or phrase. Optional +classifiers may follow the term on the same line, each after an inline +" : " (space, colon, space). A definition is a block indented relative to the term, and may contain multiple paragraphs and other body elements. There may be no blank line between a term line and a definition block (this distinguishes definition lists from `block @@ -761,7 +761,10 @@ last definition list item, but are optional in-between. For example:: term 3 : classifier Definition 3. -Inline markup is parsed in the term line before the term/classifier + term 4 : classifier one : classifier two + Definition 4. + +Inline markup is parsed in the term line before the classifier delimiter (" : ") is recognized. The delimiter will only be recognized if it appears outside of any inline markup. @@ -780,12 +783,12 @@ A definition list may be used in various ways, including: Syntax diagram:: - +---------------------------+ - | term [ " : " classifier ] | - +--+------------------------+--+ - | definition | - | (body elements)+ | - +---------------------------+ + +----------------------------+ + | term [ " : " classifier ]* | + +--+-------------------------+--+ + | definition | + | (body elements)+ | + +----------------------------+ Field Lists -- cgit v1.2.1 From 4bc20118dae38fa68bc2fbfaa6f59698e1393ee3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 6 Nov 2004 17:13:44 +0000 Subject: "Class" directive now allows multiple class names. Added "Rationale for Class Attribute Value Conversion". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2809 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 51 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 43 insertions(+), 8 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index a58c82bbc..49ce3e97e 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1210,17 +1210,19 @@ Class :Directive Type: "class" :Doctree Element: pending -:Directive Arguments: One, required (class name / attribute value). +:Directive Arguments: One or more, required (class names / attribute + values). :Directive Options: None. :Directive Content: None. The "class" directive sets a "class" attribute value on the first immediately following non-comment element [#]_. For details of the "class" attribute, see `its entry`__ in `The Docutils Document Tree`_. -The "class" attribute value is converted to lowercase and all -non-alphanumeric characters are converted to hyphens in order to match -this regular expression: ``[a-z](-?[a-z0-9]+)*``. See the docstring -from ``docutils.nodes.make_id`` for the rationale. +The directive argument consists of one or more space-separated class +names, which are converted to lowercase and all non-alphanumeric +characters are converted to hyphens. (For the rationale, see below.) + +__ ../doctree.html#class Examples:: @@ -1228,7 +1230,7 @@ Examples:: This is a "special" paragraph. - .. class:: exceptional + .. class:: exceptional remarkable An Exceptional Section ====================== @@ -1239,7 +1241,7 @@ The text above is parsed and transformed into this doctree fragment:: <paragraph class="special"> This is a "special" paragraph. - <section class="exceptional"> + <section class="exceptional remarkable"> <title> An Exceptional Section <paragraph> @@ -1258,7 +1260,40 @@ The text above is parsed and transformed into this doctree fragment:: the block quote text would be interpreted as the "class" directive's content, and the parser would complain. -__ ../doctree.html#class +.. topic:: Rationale for Class Attribute Value Conversion + + Docutils identifiers are converted to conform to the regular + expression ``[a-z](-?[a-z0-9]+)*``. For CSS compatibility, + identifiers (the "class" and "id" attributes) should have no + underscores, colons, or periods. Hyphens may be used. + + - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens: + + ID and NAME tokens must begin with a letter ([A-Za-z]) and + may be followed by any number of letters, digits ([0-9]), + hyphens ("-"), underscores ("_"), colons (":"), and periods + ("."). + + - However the `CSS1 spec`_ defines identifiers based on the "name" + token, a tighter interpretation ("flex" tokenizer notation + below; "latin1" and "escape" 8-bit characters have been replaced + with entities):: + + unicode \\[0-9a-f]{1,4} + latin1 [¡-ÿ] + escape {unicode}|\\[ -~¡-ÿ] + nmchar [-a-z0-9]|{latin1}|{escape} + name {nmchar}+ + + The CSS1 "nmchar" rule does not include underscores ("_"), colons + (":"), or periods ("."), therefore "class" and "id" attributes + should not contain these characters. They should be replaced with + hyphens ("-"). Combined with HTML's requirements (the first + character must be a letter; no "unicode", "latin1", or "escape" + characters), this results in the ``[a-z](-?[a-z0-9]+)*`` pattern. + + .. _HTML 4.01 spec: http://www.w3.org/TR/html401 + .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1 .. _role: -- cgit v1.2.1 From ef518f2f9721f4e329b5d46b02ba81875c57702f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 6 Nov 2004 19:51:17 +0000 Subject: Added warning about "raw" overuse/abuse git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2813 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 49ce3e97e..0684f0d73 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1067,6 +1067,19 @@ Raw Data Pass-Through :Directive Content: Stored verbatim, uninterpreted. None (empty) if a "file" or "url" option given. +.. WARNING:: + + The "raw" directive is a stop-gap measure allowing the author to + bypass reStructuredText's markup. It is a "power-user" feature + that should not be overused or abused. The use of "raw" ties + documents to specific output formats and makes them less portable. + + If you often need to use the "raw" directive or a "raw"-derived + interpreted text role, that is a sign either of overuse/abuse or + that functionality may be missing from reStructuredText. Please + describe your situation in email to + docutils-users@lists.sourceforge.net. + The "raw" directive indicates non-reStructuredText data that is to be passed untouched to the Writer. The names of the output formats are given in the directive arguments. The interpretation of the raw data @@ -1303,7 +1316,7 @@ Custom Interpreted Text Roles :Directive Type: "role" :Doctree Element: None; affects subsequent parsing. -:Directive Arguments: Two; one required (role name), one optional +:Directive Arguments: Two; one required (new role name), one optional (base role name, in parentheses). :Directive Options: Possible (depends on base role). :Directive Content: depends on base role. -- cgit v1.2.1 From d74ca66c1c0d32c7447bfcd10c3c02ad9ea40123 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 6 Nov 2004 19:51:39 +0000 Subject: Added "raw" role git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2814 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 66 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 4aa6b0337..76bb87a19 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -50,16 +50,16 @@ Custom interpreted text roles may be defined in a document with the .. _class: -The ``class`` option is recognized by the "role" directive for most -interpreted text roles. A description__ is provided by `"role" +A ``class`` option is recognized by the "role" directive for most +interpreted text roles. A description__ is provided in the `"role" directive`_ documentation. __ directives.html#role-class ---------------------------------- - Standard Interpreted Text Roles ---------------------------------- +---------------- + Standard Roles +---------------- ``:emphasis:`` ============== @@ -251,3 +251,59 @@ must be used to obtain a ``title_reference`` element. .. _pseudo-XML: ../doctree.html#pseudo-xml + + +------------------- + Specialized Roles +------------------- + +``raw`` +======= + +:Aliases: None +:DTD Element: raw +:Customization: + :Options: class_, format + :Content: None + +.. WARNING:: + + The "raw" role is a stop-gap measure allowing the author to bypass + reStructuredText's markup. It is a "power-user" feature that + should not be overused or abused. The use of "raw" ties documents + to specific output formats and makes them less portable. + + If you often need to use "raw"-derived interpreted text roles or + the "raw" directive, that is a sign either of overuse/abuse or that + functionality may be missing from reStructuredText. Please + describe your situation in email to + docutils-users@lists.sourceforge.net. + +The "raw" role indicates non-reStructuredText data that is to be +passed untouched to the Writer. It is the inline equivalent of the +`"raw" directive`_; see its documentation for details on the +semantics. + +.. _"raw" directive: directives.html#raw + +The "raw" role cannot be used directly. The `"role" directive`_ must +first be used to build custom roles based on the "raw" role. One or +more formats (Writer names) must be provided in a "format" option. + +For example, the following creates an HTML-specific "html" role:: + + .. role:: html(raw) + :format: html + +This role can now be used directly to pass data untouched to the HTML +Writer. For example:: + + If there just *has* to have a line break here, + :html:`<br />` + it can be accomplished with a "raw"-derived role. + But the line block syntax should be considered first. + +In addition to "class_", the following option is recognized: + +``format`` : text + One or more space-separated output format names (Writer names). -- cgit v1.2.1 From 2297960e073dc03efdbe8a55ff3fa0cb3bed5297 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 6 Nov 2004 20:06:37 +0000 Subject: clarified hack nature of "raw" a bit git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2820 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 76bb87a19..9327f1359 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -292,14 +292,14 @@ more formats (Writer names) must be provided in a "format" option. For example, the following creates an HTML-specific "html" role:: - .. role:: html(raw) + .. role:: raw-html(raw) :format: html This role can now be used directly to pass data untouched to the HTML Writer. For example:: If there just *has* to have a line break here, - :html:`<br />` + :raw-html:`<br />` it can be accomplished with a "raw"-derived role. But the line block syntax should be considered first. -- cgit v1.2.1 From 023826bace870713f61f613309b01e056b2c7fa0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 6 Nov 2004 20:21:40 +0000 Subject: further clarification of hack nature of "raw" git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2821 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 9327f1359..562a6c8b0 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -290,7 +290,7 @@ The "raw" role cannot be used directly. The `"role" directive`_ must first be used to build custom roles based on the "raw" role. One or more formats (Writer names) must be provided in a "format" option. -For example, the following creates an HTML-specific "html" role:: +For example, the following creates an HTML-specific "raw-html" role:: .. role:: raw-html(raw) :format: html @@ -303,6 +303,10 @@ Writer. For example:: it can be accomplished with a "raw"-derived role. But the line block syntax should be considered first. +.. Tip:: Roles based on "raw" should clearly indicate their origin, so + they are not mistaken for reStructuredText markup. Using a "raw-" + prefix for role names is recommended. + In addition to "class_", the following option is recognized: ``format`` : text -- cgit v1.2.1 From 10de3f2fff5c4d7d745cdd3240d9c59a1ea25b1c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 6 Nov 2004 20:49:55 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2822 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 562a6c8b0..a911cf469 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -298,7 +298,7 @@ For example, the following creates an HTML-specific "raw-html" role:: This role can now be used directly to pass data untouched to the HTML Writer. For example:: - If there just *has* to have a line break here, + If there just *has* to be a line break here, :raw-html:`<br />` it can be accomplished with a "raw"-derived role. But the line block syntax should be considered first. -- cgit v1.2.1 From 5981748846d68dda006e8e553353e4569b7c3899 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 8 Nov 2004 17:22:33 +0000 Subject: updated doctree to match real behavior: list_items may be empty git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2833 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 2 +- docs/ref/docutils.dtd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 5a5154fe7..34784a2ed 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -2650,7 +2650,7 @@ Content Model .. parsed-literal:: - (`%body.elements;`_)+ + (`%body.elements;`_)* :Attributes: The ``list_item`` element contains only the `common attributes`_: diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 71636c152..6d0e947b3 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -310,7 +310,7 @@ Eventual replacement for docinfo? --> suffix CDATA #IMPLIED start %number; #IMPLIED> -<!ELEMENT list_item (%body.elements;)+> +<!ELEMENT list_item (%body.elements;)*> <!ATTLIST list_item %basic.atts;> <!ELEMENT definition_list (definition_list_item+)> -- cgit v1.2.1 From a33879a926ba9d3beffcc35e5f8c45cb62e85ce4 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 26 Nov 2004 09:27:55 +0000 Subject: allow empty sections and documents git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2870 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 20 ++++++++------------ docs/ref/docutils.dtd | 2 +- 2 files changed, 9 insertions(+), 13 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 34784a2ed..fc8e9ae3a 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -4806,18 +4806,14 @@ Entity definition: ( ( (`%body.elements;`_ | topic_ | sidebar_)+, (transition_, (`%body.elements;`_ | topic_ | sidebar_)+ )*, ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? ) - | ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* ) ) "> - -Each document_ or section_ contains either: - -- multiple body elements, topics, and/or sidebars, optionally - interspersed with transitions (but transitions cannot occur at the - beginning or end, nor may there be two transitions in a row), - followed by zero or more sections optionally interspersed with - transitions; or - -- one or more sections (whose contents are recursively the same as - this model) optionally interspersed with transitions. + | ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* ) )? "> + +Each document_ or section_ contains zero or more body elements, +topics, and/or sidebars, optionally interspersed with transitions (but +transitions cannot occur at the beginning or end, nor may there be two +transitions in a row), followed by zero or more sections (whose +contents are recursively the same as this model) optionally +interspersed with transitions. The `%structure.model;`_ parameter entity is directly employed in the content models of the document_ and section_ elements. diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 6d0e947b3..3d3ae4956 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -144,7 +144,7 @@ resolve to either an internal or external reference. " ( ( (%body.elements; | topic | sidebar)+, (transition, (%body.elements; | topic | sidebar)+ )*, ( (%section.elements;), (transition?, (%section.elements;) )* )? ) - | ( (%section.elements;), (transition?, (%section.elements;) )* ) ) "> + | ( (%section.elements;), (transition?, (%section.elements;) )* ) )? "> <!ENTITY % text.model " (#PCDATA | %inline.elements;)* "> -- cgit v1.2.1 From c27c1ce9f7115bf7b69580be3b3d873ecc06afe1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 26 Nov 2004 15:42:37 +0000 Subject: simplified structure model and clarified restrictions on transitions git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2872 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 29 ++++++++++++++++++++--------- docs/ref/docutils.dtd | 7 +++---- 2 files changed, 23 insertions(+), 13 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index fc8e9ae3a..43ce91d33 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -4803,17 +4803,28 @@ Entity definition: .. parsed-literal:: - ( ( (`%body.elements;`_ | topic_ | sidebar_)+, - (transition_, (`%body.elements;`_ | topic_ | sidebar_)+ )*, - ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? ) - | ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* ) )? "> + ( ( (`%body.elements;`_ | topic_ | sidebar_)+, transition_? )*, + ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? ) Each document_ or section_ contains zero or more body elements, -topics, and/or sidebars, optionally interspersed with transitions (but -transitions cannot occur at the beginning or end, nor may there be two -transitions in a row), followed by zero or more sections (whose -contents are recursively the same as this model) optionally -interspersed with transitions. +topics, and/or sidebars, optionally interspersed with single +transitions, followed by zero or more sections (whose contents are +recursively the same as this model) optionally interspersed with +transitions. + +The following restrictions are imposed by this model: + +* Transitions must be separated by other elements (body elements, + sections, etc.). In other words, a transition may not be + immediately adjacent to another transition. + +* A transition may not occur at the beginning of a document or + section. + +An additional restriction, which cannot be expressed in the language +of DTDs, is imposed by software: + +* A transition may not occur at the end of a document or section. The `%structure.model;`_ parameter entity is directly employed in the content models of the document_ and section_ elements. diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 3d3ae4956..a18eae36b 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -140,11 +140,10 @@ resolve to either an internal or external reference. <!-- Element Content Models ================================================================== --> +<!-- The structure model may not end with a transition. --> <!ENTITY % structure.model - " ( ( (%body.elements; | topic | sidebar)+, - (transition, (%body.elements; | topic | sidebar)+ )*, - ( (%section.elements;), (transition?, (%section.elements;) )* )? ) - | ( (%section.elements;), (transition?, (%section.elements;) )* ) )? "> + " ( ( (%body.elements; | topic | sidebar)+, transition? )*, + ( (%section.elements;), (transition?, (%section.elements;) )* )? )"> <!ENTITY % text.model " (#PCDATA | %inline.elements;)* "> -- cgit v1.2.1 From 661282ce7201379c56ead73b874cf5213ca8d16f Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 23 Dec 2004 17:42:28 +0000 Subject: updated text about "Address" field, because the line block directive will be gone soon git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2892 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index a5cd99745..a7841ac63 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -896,9 +896,8 @@ single name is interpreted as an "Author". If a single name contains a comma, end it with a semicolon to disambiguate: ":Authors: Doe, Jane;". -The "Address" field is for a multi-line surface mailing address. A -specialized form of line block`_ (see `reStructuredText Directives`_), -newlines and whitespace will be preserved. +The "Address" field is for a multi-line surface mailing address. +Newlines and whitespace will be preserved. The "Dedication" and "Abstract" fields may contain arbitrary body elements. Only one of each is allowed. They become topic elements -- cgit v1.2.1 From dd317b4e446e8c3666bf6e30e13ebf3a39e168f3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 11 Feb 2005 15:49:20 +0000 Subject: Added "list-table" directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2963 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 59 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 57 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 0684f0d73..bd7c921e1 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -722,8 +722,8 @@ The following options are recognized: class_ directive below. ``widths`` : integer [, integer...] - A comma-separated list of relative column widths. The default is - equal-width columns (100%/#columns). + A comma- or space-separated list of relative column widths. The + default is equal-width columns (100%/#columns). ``header-rows`` : integer The number of rows of CSV data to use in the table header. @@ -768,6 +768,61 @@ The following options are recognized: the default case? +.. _list-table: + +List Table +========== + +:Directive Type: "list-table" +:Doctree Element: table +:Directive Arguments: 1, optional (table title). +:Directive Options: Possible. +:Directive Content: A uniform two-level bullet list. + +(New in Docutils 0.3.8. This is an initial implementation; `further +ideas`__ may be implemented in the future.) + +__ http://docutils.sf.net/docs/dev/rst/alternatives.html#list-driven-tables + +The "list-table" directive is used to create a table from data in a +uniform two-level bullet list. "Uniform" means that each sublist +(second-level list) must contain the same number of list items. + +Example:: + + .. list-table:: Frozen Delights! + :widths: 15 10 30 + :header-rows: 1 + + * - Treat + - Quantity + - Description + * - Albatross + - 2.99 + - On a stick! + * - Crunchy Frog + - 1.49 + - If we took the bones out, it wouldn\'t be + crunchy, now would it? + * - Gannet Ripple + - 1.99 + - On a stick! + +The following options are recognized: + +``class`` : text + Set a "class" attribute value on the table element. See the + class_ directive below. + +``widths`` : integer [integer...] + A comma- or space-separated list of relative column widths. The + default is equal-width columns (100%/#columns). + +``header-rows`` : integer + The number of rows of list data to use in the table header. + Defaults to 0. + + ---------------- Document Parts ---------------- -- cgit v1.2.1 From 26be35634ec3071982211cfe13e1c0b48d3aeb5f Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 5 Mar 2005 16:52:14 +0000 Subject: relocate internal targets only in front of sections, doctitles and subtitles git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3008 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index f5c045bb7..db4d3c426 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -28,6 +28,8 @@ misc.class "class" (d/p) 210 references.Substitutions standalone (r), pep (r) 220 +references.SectionTargets standalone (r), pep (r) 260 + frontmatter.DocTitle standalone (r) 320 frontmatter.DocInfo standalone (r) 340 -- cgit v1.2.1 From 0a938a279683da492acd6512d0af6fa636c5a51c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 15 Mar 2005 00:37:51 +0000 Subject: differentiate between paths and URIs git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3046 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index a7841ac63..e8109bc28 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1782,8 +1782,9 @@ indirect. 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 concatenated. - The following external hyperlink targets are equivalent:: + are concatenated. Any whitespace is removed (whitespace is + permitted to allow for line wrapping). The following external + hyperlink targets are equivalent:: .. _one-liner: http://docutils.sourceforge.net/rst.html -- cgit v1.2.1 From 7443f869361b418b846f773b53d47543ca1c980b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 21 Mar 2005 22:05:23 +0000 Subject: added security warnings for "raw" & "include" git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3074 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index bd7c921e1..752c82c51 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1074,6 +1074,13 @@ Including an External Document Fragment :Directive Options: Possible. :Directive Content: None. +.. WARNING:: + + The "include" directive represents a potential security hole. It + can be disabled with the "file_insertion_enabled_" runtime setting. + + .. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled + The "include" directive reads a reStructuredText-formatted text file and parses it in the current document's context at the point of the directive. The directive argument is the path to the file to be @@ -1124,6 +1131,14 @@ Raw Data Pass-Through .. WARNING:: + The "raw" directive represents a potential security hole. It can + be disabled with the "raw_enabled_" or "file_insertion_enabled_" + runtime settings. + + .. _raw_enabled: ../../user/config.html#raw-enabled + +.. Caution:: + The "raw" directive is a stop-gap measure allowing the author to bypass reStructuredText's markup. It is a "power-user" feature that should not be overused or abused. The use of "raw" ties -- cgit v1.2.1 From b559771f98c67ca07b71c41dd947c2be6df75fee Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 22 Mar 2005 19:18:06 +0000 Subject: added csv-table directive support for the file_insertion_enabled setting git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3083 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 752c82c51..1b0ff108d 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -668,7 +668,13 @@ CSV Table :Directive Options: Possible. :Directive Content: A CSV (comma-separated values) table. -.. Warning:: +.. WARNING:: + + The "csv-table" directive's ":file:" and ":url:" options represent + a potential security holes. They can be disabled with the + "file_insertion_enabled_" runtime setting. + +.. Note:: The "csv-table" directive requires the ``csv.py`` module of the Python standard library, which was added in Python 2.3. It will @@ -734,8 +740,11 @@ The following options are recognized: before any ``header-rows`` from the main CSV data. Must use the same CSV format as the main CSV data. -``file`` | ``url`` : path - Path or URL to CSV file. +``file`` : string (newlines removed) + The local filesystem path to a CSV data file. + +``url`` : string (whitespace removed) + An Internet URL reference to a CSV data file. ``encoding`` : name of text encoding The text encoding of the external CSV data (file or URL). @@ -1179,10 +1188,10 @@ example:: The following options are recognized: -``file`` : string +``file`` : string (newlines removed) The local filesystem path of a raw data file to be included. -``url`` : string +``url`` : string (whitespace removed) An Internet URL reference to a raw data file to be included. ``encoding`` : name of text encoding -- cgit v1.2.1 From e31cbf8e64a41aae36cbaeed1d285ad942f703dd Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 24 Mar 2005 16:36:09 +0000 Subject: cover tricky indentation edge cases git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3111 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index e8109bc28..4a98a45f9 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1484,10 +1484,17 @@ An explicit markup block is a text block: - which ends before an unindented line. Explicit markup blocks are analogous to bullet list items, with ".." -as the bullet. The text immediately after the explicit markup start -determines the indentation of the block body. Blank lines are -required between explicit markup blocks and other elements, but are -optional between explicit markup blocks where unambiguous. +as the bullet. The text on the lines immediately after the explicit +markup start determines the indentation of the block body. The +maximum common indentation is always removed from the second and +subsequent lines of the block body. Therefore if the first construct +fits in one line, and the indentation of the first and second +constructs should differ, the first construct should not begin on the +same line as the explicit markup start. + +Blank lines are required between explicit markup blocks and other +elements, but are optional between explicit markup blocks where +unambiguous. The explicit markup syntax is used for footnotes, citations, hyperlink targets, directives, substitution definitions, and comments. @@ -1512,13 +1519,16 @@ be: - a single "*" (denoting `auto-symbol footnotes`_). -If the first body element within a footnote is a simple paragraph, it -may begin on the same line as the footnote label. Other elements must -begin on a new line, consistently indented (by at least 3 spaces) and -left-aligned. +The footnote content (body elements) must be consistently indented (by +at least 3 spaces) and left-aligned. The first body element within a +footnote may often begin on the same line as the footnote label. +However, if the first element fits on one line and the indentation of +the remaining elements differ, the first element must begin on the +line after the footnote label. Otherwise, the difference in +indentation will not be detected. Footnotes may occur anywhere in the document, not only at the end. -Where or how they appear in the processed output depends on the +Where and how they appear in the processed output depends on the processing system. Here is a manually numbered footnote:: -- cgit v1.2.1 From 7d76b140ee974b59e35f1f044949dc032630e15f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 25 Mar 2005 03:02:32 +0000 Subject: added auto-enumerated list items git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3113 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 4a98a45f9..4ed975144 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -670,6 +670,11 @@ The following enumeration sequences are recognized: - uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999). - lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999). +In addition, the auto-enumerator, "#", may be used to automatically +enumerate a list. Auto-enumerated lists may begin with explicit +enumeration, which sets the sequence. Fully auto-enumerated lists use +arabic numerals and begin with 1. + The following formatting types are recognized: - suffixed with a period: "1.", "A.", "a.", "I.", "i.". -- cgit v1.2.1 From 9dbc2adead008935245a396eab10bb7bcb11b226 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 26 Mar 2005 16:21:28 +0000 Subject: merged rev. 3094:3101 and 3102:HEAD from branches/multiple-ids to trunk git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3129 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 44 ++++++++++++++++++++++---------------------- docs/ref/transforms.txt | 4 +--- 2 files changed, 23 insertions(+), 25 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 43ce91d33..dc19bdff3 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -264,7 +264,7 @@ following subsections: - Real XML:: <document> - <section id="a-title" name="a title"> + <section ids="a-title" names="a title"> <title>A Title A paragraph.
@@ -273,7 +273,7 @@ following subsections: - Pseudo-XML:: -
+
A Title <paragraph> @@ -359,7 +359,7 @@ reStructuredText_ source:: Complete pseudo-XML_ result after parsing and applying transforms:: - <document id="document-title" name="document title"> + <document ids="document-title" names="document title"> <title> Document Title <docinfo> @@ -559,7 +559,7 @@ reStructuredText_ source:: Complete pseudo-XML_ result after parsing and applying transforms:: - <document id="document-title" name="document title"> + <document ids="document-title" names="document title"> <title> Document Title <docinfo> @@ -625,7 +625,7 @@ reStructuredText_ source:: Complete pseudo-XML_ result after parsing and applying transforms:: - <document id="document-title" name="document title"> + <document ids="document-title" names="document title"> <title> Document Title <docinfo> @@ -1016,7 +1016,7 @@ reStructuredText_ source:: Complete pseudo-XML_ result after parsing and applying transforms:: - <document id="document-title" name="document title"> + <document ids="document-title" names="document title"> <title> Document Title <docinfo> @@ -1082,7 +1082,7 @@ reStructuredText_ source:: Complete pseudo-XML_ result after parsing and applying transforms:: - <document id="document-title" name="document title"> + <document ids="document-title" names="document title"> <title> Document Title <docinfo> @@ -1210,7 +1210,7 @@ reStructuredText_ source:: Complete pseudo-XML_ result after parsing and applying transforms:: - <document id="document-title" name="document title"> + <document ids="document-title" names="document title"> <title> Document Title <docinfo> @@ -1617,7 +1617,7 @@ into a ``docinfo`` element and its children by a transform. Source:: Complete pseudo-XML_ result after parsing and applying transforms:: - <document id="docinfo-example" name="docinfo example"> + <document ids="docinfo-example" names="docinfo example"> <title> Docinfo Example <docinfo> @@ -1794,7 +1794,7 @@ reStructuredText_ source:: Complete pseudo-XML_ result from simple parsing:: <document> - <section id="a-title" name="a title"> + <section ids="a-title" names="a title"> <title> A Title <paragraph> @@ -1803,7 +1803,7 @@ Complete pseudo-XML_ result from simple parsing:: After applying transforms, the section title is promoted to become the document title:: - <document id="a-title" name="a title"> + <document ids="a-title" names="a title"> <title> A Title <paragraph> @@ -3221,7 +3221,7 @@ reStructuredText_ source:: Complete pseudo-XML_ result after parsing and applying transforms:: - <document id="document-title" name="document title"> + <document ids="document-title" names="document title"> <title> Document Title <docinfo> @@ -3371,7 +3371,7 @@ reStructuredText_ source:: Complete pseudo-XML_ result after parsing and applying transforms:: - <document id="document-title" name="document title"> + <document ids="document-title" names="document title"> <title> Document Title <docinfo> @@ -3479,22 +3479,22 @@ reStructuredText_ source:: Complete pseudo-XML_ result after parsing:: <document> - <section id="title-1" name="title 1"> + <section ids="title-1" names="title 1"> <title> Title 1 <paragraph> Paragraph 1. - <section id="title-2" name="title 2"> + <section ids="title-2" names="title 2"> <title> Title 2 <paragraph> Paragraph 2. - <section id="title-3" name="title 3"> + <section ids="title-3" names="title 3"> <title> Title 3 <paragraph> Paragraph 3. - <section id="title-4" name="title 4"> + <section ids="title-4" names="title 4"> <title> Title 4 <paragraph> @@ -3638,7 +3638,7 @@ reStructuredText_ source:: Complete pseudo-XML_ result after parsing and applying transforms:: - <document id="document-title" name="document title"> + <document ids="document-title" names="document title"> <title> Document Title <docinfo> @@ -3728,10 +3728,10 @@ reStructuredText_ source:: Complete pseudo-XML_ result after parsing and applying transforms:: - <document id="title" name="title"> + <document ids="title" names="title"> <title> Title - <subtitle id="subtitle" name="subtitle"> + <subtitle ids="subtitle" names="subtitle"> Subtitle <paragraph> A paragraph. @@ -3946,7 +3946,7 @@ reStructuredText_ source:: Pseudo-XML_ fragment from simple parsing:: - <section id="a-title" name="a title"> + <section ids="a-title" names="a title"> <title> A Title <paragraph> @@ -4170,7 +4170,7 @@ reStructuredText_ source:: Complete pseudo-XML_ result after parsing and applying transforms:: - <document id="document-title" name="document title"> + <document ids="document-title" names="document title"> <title> Document Title <docinfo> diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index db4d3c426..9e4687a72 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -28,7 +28,7 @@ misc.class "class" (d/p) 210 references.Substitutions standalone (r), pep (r) 220 -references.SectionTargets standalone (r), pep (r) 260 +references.PropagateTargets standalone (r), pep (r) 260 frontmatter.DocTitle standalone (r) 320 @@ -38,8 +38,6 @@ peps.Headers pep (r) 360 peps.Contents pep (r) 380 -references.ChainedTargets standalone (r), pep (r) 420 - references.AnonymousHyperlinks standalone (r), pep (r) 440 references.IndirectHyperlinks standalone (r), pep (r) 460 -- cgit v1.2.1 From bf160723971d1fd68ad8db3466fbd1676c3988a7 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 30 Mar 2005 19:20:35 +0000 Subject: removed "list-table" target which was redundant and caused the TOC link to point to #id4 instead of #list-table git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3148 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 1b0ff108d..ff5862680 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -777,8 +777,6 @@ The following options are recognized: the default case? -.. _list-table: - List Table ========== -- cgit v1.2.1 From dc3284ca85006e72f0e3b2c4ffbe078aa9148f76 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 5 Apr 2005 02:55:06 +0000 Subject: added "stub-columns" options to "csv-table" and "list-table" directives, plus support, docs, and tests git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3165 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 4 +++- docs/ref/rst/directives.txt | 8 ++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index a18eae36b..d9a76ce2e 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -166,7 +166,9 @@ http://www.oasis-open.org/html/tm9901.htm). <!ENTITY % tbl.tgroup.att " %basic.atts; "> <!ENTITY % tbl.thead.att " %basic.atts; "> <!ENTITY % tbl.tbody.att " %basic.atts; "> -<!ENTITY % tbl.colspec.att " %basic.atts; "> +<!ENTITY % tbl.colspec.att + " %basic.atts; + stub %yesorno; #IMPLIED "> <!ENTITY % tbl.row.att " %basic.atts; "> <!ENTITY % tbl.entry.mdl " (%body.elements;)* "> <!ENTITY % tbl.entry.att diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index ff5862680..8be376eb6 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -735,6 +735,10 @@ The following options are recognized: The number of rows of CSV data to use in the table header. Defaults to 0. +``stub-columns`` : integer + The number of table columns to use as stubs (row titles, on the + left). Defaults to 0. + ``header`` : CSV data Supplemental data for the table header, added independently of and before any ``header-rows`` from the main CSV data. Must use the @@ -829,6 +833,10 @@ The following options are recognized: The number of rows of list data to use in the table header. Defaults to 0. +``stub-columns`` : integer + The number of table columns to use as stubs (row titles, on the + left). Defaults to 0. + ---------------- Document Parts -- cgit v1.2.1 From d6ab28097870eadae43ea8975d984a27a2ee0379 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 5 Apr 2005 03:29:10 +0000 Subject: fixed mistaken indentation git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3168 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 8be376eb6..3de9832db 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -486,6 +486,8 @@ Rubric :Directive Options: Possible. :Directive Content: None. +.. + rubric n. 1. a title, heading, or the like, in a manuscript, book, statute, etc., written or printed in red or otherwise distinguished from the rest of the text. ... -- cgit v1.2.1 From 260212205f6acb893a305d3575d76f493a68b724 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 5 Apr 2005 21:04:04 +0000 Subject: removed unnecessary backslash git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3173 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 3de9832db..d0f6cd453 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -815,7 +815,7 @@ Example:: - On a stick! * - Crunchy Frog - 1.49 - - If we took the bones out, it wouldn\'t be + - If we took the bones out, it wouldn't be crunchy, now would it? * - Gannet Ripple - 1.99 -- cgit v1.2.1 From 5b2787e17e9dc54537136f376fc2a499a7b90b66 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 5 Apr 2005 21:52:48 +0000 Subject: added links for image and meta directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3174 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 4ed975144..c32e48db6 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -807,7 +807,7 @@ processing. They may also be used for two-column table-like structures resembling database records (label & data pairs). Applications of reStructuredText may recognize field names and transform fields or field bodies in certain contexts. For examples, -see `Bibliographic Fields`_ below, or the "image" and "meta" +see `Bibliographic Fields`_ below, or the "image_" and "meta_" directives in `reStructuredText Directives`_. Field lists are mappings from field names to field bodies, modeled on @@ -2814,6 +2814,8 @@ Markup errors are handled according to the specification in `PEP .. _World Wide Web Consortium: http://www.w3.org/ .. _HTML Techniques for Web Content Accessibility Guidelines: http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text +.. _image: directives.html#image +.. _meta: directives.html#meta .. _reStructuredText Directives: directives.html .. _reStructuredText Interpreted Text Roles: roles.html .. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt -- cgit v1.2.1 From 0e2d41b9ac2cd4c2fd17ece211048d9727685af6 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 5 Apr 2005 21:59:20 +0000 Subject: added some more links git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3175 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index c32e48db6..57362c5db 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1927,17 +1927,17 @@ Directives`_ document, and are always available. Any other directives are domain-specific, and may require special action to make them available when processing the document. -For example, here's how an image may be placed:: +For example, here's how an image_ may be placed:: .. image:: mylogo.jpeg -A figure (a graphic with a caption) may placed like this:: +A figure_ (a graphic with a caption) may placed like this:: .. figure:: larch.png The larch. -An admonition (note, caution, etc.) contains other body elements:: +An admonition_ (note, caution, etc.) contains other body elements:: .. note:: This is a paragraph @@ -2028,7 +2028,7 @@ Substitution definitions are indicated by an explicit markup start vertical bar, whitespace, and the definition block. Substitution text may not begin or end with whitespace. A substitution definition block contains an embedded inline-compatible directive (without the leading -".. "), such as an image. For example:: +".. "), such as an image_. For example:: The |biohazard| symbol must be used on containers used to dispose of medical waste. @@ -2133,7 +2133,7 @@ Images .. |-><-| image:: discord.png .. _POEE: http://www.poee.org/ - The "image" directive has been implemented. + The "image_" directive has been implemented. Styles [#]_ Substitution references may be used to associate inline text with @@ -2816,6 +2816,8 @@ Markup errors are handled according to the specification in `PEP http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text .. _image: directives.html#image .. _meta: directives.html#meta +.. _figure: directives.html#figure +.. _admonition: directives.html#admonitions .. _reStructuredText Directives: directives.html .. _reStructuredText Interpreted Text Roles: roles.html .. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt -- cgit v1.2.1 From dcc80f043243f34d0373a3150bacfff20b3212ae Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 7 Apr 2005 19:36:11 +0000 Subject: added "header" & "footer" directives, tests, docs, support, and some tweaks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3184 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 71 ++++++++++++++++++++++++++++----------------- docs/ref/docutils.dtd | 7 +++-- docs/ref/rst/directives.txt | 41 +++++++++++++++++++++++--- 3 files changed, 86 insertions(+), 33 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index dc19bdff3..912789239 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -62,7 +62,7 @@ one-to-many relationships; sections may contain (sub)sections, tables contain further body elements, etc. :: +--------------------------------------------------------------------+ - | document [may begin with a title, subtitle, docinfo, decoration] | + | document [may begin with a title, subtitle, decoration, docinfo] | | +--------------------------------------+ | | sections [each begins with a title] | +-----------------------------+-------------------------+------------+ @@ -112,7 +112,7 @@ Structural subelements are child elements of structural elements. Simple structuctural subelements (title_, subtitle_) contain text data; the others are compound and do not directly contain text data. -Category members: title_, subtitle_, docinfo_, decoration_, +Category members: title_, subtitle_, decoration_, docinfo_, transition_ @@ -146,7 +146,7 @@ body elements. There are two subcategories of body elements: simple and compound. Category members: admonition_, attention_, block_quote_, bullet_list_, -caution_, citation_, comment_, danger_, definition_list_, +caution_, citation_, comment_, compound_, danger_, definition_list_, doctest_block_, enumerated_list_, error_, field_list_, figure_, footnote_, hint_, image_, important_, line_block_, literal_block_, note_, option_list_, paragraph_, pending_, raw_, rubric_, @@ -173,9 +173,10 @@ Compound body elements contain local substructure (body subelements) and further body elements. They do not directly contain text data. Category members: admonition_, attention_, block_quote_, bullet_list_, -caution_, citation_, danger_, definition_list_, enumerated_list_, -error_, field_list_, figure_, footnote_, hint_, important_, note_, -option_list_, system_message_, table_, tip_, warning_ +caution_, citation_, compound_, danger_, definition_list_, +enumerated_list_, error_, field_list_, figure_, footnote_, hint_, +important_, note_, option_list_, system_message_, table_, tip_, +warning_ Body Subelements @@ -959,6 +960,12 @@ Pseudo-XML_ fragment from simple parsing:: `To be completed`_. +``compound`` +============ + +`To be completed`_. + + ``contact`` =========== @@ -1251,6 +1258,7 @@ Details :Processing: See the individual `decorative elements`_. + Content Model ------------- @@ -1758,20 +1766,21 @@ Content Model .. parsed-literal:: - ((title_, - subtitle_?)?, - docinfo_?, - decoration_?, - `%structure.model;`_) + ( (title_, subtitle_?)?, + decoration_?, + (docinfo_, transition_?)?, + `%structure.model;`_ ) Depending on the source of the data and the stage of processing, the "document" may not initially contain a "title". A document title is not directly representable in reStructuredText_. Instead, a lone top-level section may have its title promoted to become the document title_, and similarly for a lone second-level (sub)section's title to -become the document subtitle_. The "docinfo_" may be transformed from -an initial field_list_, and "decoration_" is usually constructed -programmatically. +become the document subtitle_. + +The contents of "decoration_" may be specified in a document, +constructed programmatically, or both. The "docinfo_" may be +transformed from an initial field_list_. See the `%structure.model;`_ parameter entity for details of the body of a ``document``. @@ -2314,7 +2323,7 @@ section numbers inserted by the "sectnum" directive. The ``header`` element is a container element whose contents are meant to appear at the top of a web page, or at the top of every printed -page. Docutils does not yet make use of the ``header`` element. +page. Details @@ -2350,7 +2359,17 @@ Content Model Examples -------- -None. +reStructuredText source fragment:: + + .. header:: This space for rent. + +Pseudo-XML_ fragment from simple parsing:: + + <document> + <decoration> + <header> + <paragraph> + This space for rent. ``hint`` @@ -4611,14 +4630,14 @@ Entity definition: .. parsed-literal:: - paragraph_ | literal_block_ | doctest_block_ | line_block_ - | block_quote_ | table_ | figure_ | image_ | footnote_ | citation_ - | rubric_ + paragraph_ | compound_ | literal_block_ | doctest_block_ + | line_block_ | block_quote_ + | table_ | figure_ | image_ | footnote_ | citation_ | rubric_ | bullet_list_ | enumerated_list_ | definition_list_ | field_list_ | option_list_ - | attention_ | caution_ | danger_ | error_ | hint_ | important_ - | note_ | tip_ | warning_ | admonition_ - | target_ | substitution_definition_ | comment_ | pending_ + | attention_ | caution_ | danger_ | error_ | hint_ | important_ | note_ + | tip_ | warning_ | admonition_ + | reference_ | target_ | substitution_definition_ | comment_ | pending_ | system_message_ | raw_ %additional.body.elements; @@ -4627,10 +4646,10 @@ wrapper DTDs to extend ``%body.elements;``. The ``%body.elements;`` parameter entity is directly employed in the content models of the following elements: admonition_, attention_, -block_quote_, caution_, citation_, danger_, definition_, description_, -entry_, error_, field_body_, footer_, footnote_, header_, hint_, -important_, legend_, list_item_, note_, sidebar_, system_message_, -tip_, topic_, warning_ +block_quote_, caution_, citation_, compound_, danger_, definition_, +description_, entry_, error_, field_body_, footer_, footnote_, +header_, hint_, important_, legend_, list_item_, note_, sidebar_, +system_message_, tip_, topic_, warning_ Via `%structure.model;`_, the ``%body.elements;`` parameter entity is indirectly employed in the content models of the document_ and diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index d9a76ce2e..0c0a55003 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -183,9 +183,10 @@ http://www.oasis-open.org/html/tm9901.htm). <!-- Optional elements may be generated by internal processing. --> <!ELEMENT document - ((title, subtitle?)?, - ((docinfo, decoration?, transition?) | decoration?), - %structure.model;)> + ( (title, subtitle?)?, + decoration?, + (docinfo, transition?)?, + %structure.model; )> <!ATTLIST document %basic.atts;> <!-- diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index d0f6cd453..5af9987e7 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -464,11 +464,10 @@ For example, all the element names in this content model are links:: .. parsed-literal:: - ((title_, - subtitle_?)?, - docinfo_?, + ( (title_, subtitle_?)?, decoration_?, - `%structure.model;`_) + (docinfo_, transition_?)?, + `%structure.model;`_ ) The following option is recognized: @@ -958,6 +957,40 @@ The following options are recognized: default is 1. +.. _header: +.. _footer: + +Document Header & Footer +======================== + +:Directive Types: "header" and "footer" +:Doctree Elements: decoration, header, footer +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Interpreted as body elements. + +(New in Docutils 0.3.8) + +The "header" and "footer" directives create document decorations, +useful for page navigation, notes, time/datestamp, etc. For example:: + + .. header:: This space for rent. + +This will add a paragraph to the document header, which will appear at +the top of the generated web page or at the top of every printed page. + +These directives may be used multiple times, cumulatively. There is +currently support for only one header and footer. + +In addition to the use of these directives to populate header and +footer content, content may also be added automatically by the +processing system. For example, if certain runtime settings are +enabled, the document footer is populated with processing information +such as a datestamp, a link to `the Docutils website`_, etc. + +.. _the Docutils website: http://docutils.sourceforge.net + + ------------ References ------------ -- cgit v1.2.1 From 7e297f36f3c1d3ebf5f26a60dcec7613efa63ba5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 8 Apr 2005 18:42:33 +0000 Subject: moved implementation description out of the docs into the code; whitespace git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3193 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 5af9987e7..5e07ba449 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -854,21 +854,15 @@ Table of Contents :Directive Options: Possible. :Directive Content: None. -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 options 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:: +The "contents" directive generates a table of contents (TOC). Here's +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:: +An explicit title may be specified:: .. contents:: Table of Contents -- cgit v1.2.1 From a65d49465f32f45cc8152ccfdd0ee4d26c398353 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 9 Apr 2005 01:32:29 +0000 Subject: allow topics within sidebars; no topics within body elements git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3199 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 9 +++++---- docs/ref/docutils.dtd | 2 +- docs/ref/rst/directives.txt | 10 +++++++--- 3 files changed, 13 insertions(+), 8 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 912789239..b5458017b 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -3550,7 +3550,7 @@ Details :Children: ``sidebar`` elements begin with a title_ and an optional subtitle_ - and contain `body elements`_. + and contain `body elements`_ and topic_ elements. :Analogues: ``sidebar`` is analogous to the DocBook "sidebar" element. @@ -3568,7 +3568,7 @@ Content Model .. parsed-literal:: (title_, subtitle_?, - (`%body.elements;`_)+) + (`%body.elements;`_ | topic_)+) :Attributes: The ``sidebar`` element contains only the `common attributes`_: @@ -3985,7 +3985,7 @@ The ``topic`` element is a nonrecursive section_-like construct which may occur at the top level of a section_ wherever a body element (list, table, etc.) is allowed. In other words, ``topic`` elements cannot nest inside body elements, so you can't have a ``topic`` inside -a ``table`` or a ``list``, or inside another ``topic`` (or sidebar_). +a ``table`` or a ``list``, or inside another ``topic``. Details @@ -3995,7 +3995,8 @@ Details `Structural Elements`_ :Parents: - The following elements may contain ``topic``: document_, section_ + The following elements may contain ``topic``: document_, section_, + sidebar_ :Children: ``topic`` elements begin with a title_ and may contain `body diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 0c0a55003..357703f04 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -279,7 +279,7 @@ Eventual replacement for docinfo? --> <!ELEMENT topic (title?, (%body.elements;)+)> <!ATTLIST topic %basic.atts;> -<!ELEMENT sidebar (title, subtitle?, (%body.elements;)+)> +<!ELEMENT sidebar (title, subtitle?, (%body.elements; | topic)+)> <!ATTLIST sidebar %basic.atts;> <!ELEMENT transition EMPTY> diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 5e07ba449..859d32487 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -331,7 +331,7 @@ A topic is like a block quote with a title, or a self-contained section with no subsections. Use the "topic" directive to indicate a self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or transition may occur. Body -elements (including topics) may not contain nested topics. +elements and topics may not contain nested topics. The directive's sole argument is interpreted as the topic title; the next line must be blank. All subsequent lines make up the topic body, @@ -854,8 +854,12 @@ Table of Contents :Directive Options: Possible. :Directive Content: None. -The "contents" directive generates a table of contents (TOC). Here's -the directive in its simplest form:: +The "contents" directive generates a table of contents (TOC) in a +topic_. Topics, and therefore tables of contents, may occur anywhere +a section or transition may occur. Body elements and topics may not +contain tables of contents. + +Here's the directive in its simplest form:: .. contents:: -- cgit v1.2.1 From 0d09d08b1b3bb856aaff320d99fc93faa3d50fa4 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 9 Apr 2005 21:13:28 +0000 Subject: added note about misuse of header and footer directives git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3200 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 859d32487..737cbe97a 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -980,6 +980,20 @@ the top of the generated web page or at the top of every printed page. These directives may be used multiple times, cumulatively. There is currently support for only one header and footer. +.. note:: + + While it is possible to use the "header" and "footer" directives to + create navigational elements for web pages, you should be aware + that Docutils is meant to be used for *document* processing, and + that a navigation bar is not typically part of a document. + + Thus, you may soon find Docutils' abilities to be insufficient for + these purposes. At that time, you should consider using a + templating system (like ht2html_) rather than the "header" and + "footer" directives. + + .. _ht2html: http://ht2html.sourceforge.net/ + In addition to the use of these directives to populate header and footer content, content may also be added automatically by the processing system. For example, if certain runtime settings are -- cgit v1.2.1 From bd559044426b3f80dd1e7cc9b2d3a25c61bb952f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 21 Apr 2005 14:52:41 +0000 Subject: "image" directive: added checks for valid values of "align" option, depending on context. "figure" directive: added specialized "align" option and attribute on "figure" element. Added HTML support for ``align`` attribute on ``figure`` elements. Updated docs & tests. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3231 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 8 ++++++++ docs/ref/rst/directives.txt | 5 +++++ 2 files changed, 13 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 357703f04..f3a7d37ca 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -97,6 +97,12 @@ resolve to either an internal or external reference. <!ENTITY % fixedspace.att " xml:space (default | preserve) #FIXED 'preserve' "> +<!ENTITY % align-h.att + " align (left | center | right) #IMPLIED "> + +<!ENTITY % align-hv.att + " align (top | middle | bottom | left | center | right) #IMPLIED "> + <!-- Element OR-Lists ============================================================= --> @@ -465,12 +471,14 @@ or " ") or the text between option arguments (typically either "," or <!ELEMENT figure (image, ((caption, legend?) | legend)) > <!ATTLIST figure %basic.atts; + %align-h.att; width %number; #IMPLIED> <!-- Also an inline element. --> <!ELEMENT image EMPTY> <!ATTLIST image %basic.atts; + %align-hv.att; uri CDATA #REQUIRED alt CDATA #IMPLIED height %number; #IMPLIED diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 737cbe97a..f888ef556 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -309,6 +309,11 @@ options are recognized: Set a "class" attribute value on the figure element. See the class_ directive below. +``align`` : "left", "center", or "right" + The horizontal alignment of the figure, allowing the image to + float and have the text flow around it. The specific behavior + depends upon the browser or rendering software used. + .. [#PIL] `Python Imaging Library`_. .. _Python Imaging Library: http://www.pythonware.com/products/pil/ -- cgit v1.2.1 From df9f154b022a494b353fb6df0bbc04dc374d9ae5 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 21 Apr 2005 19:02:28 +0000 Subject: added note about using "compound" as a block-level container git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3238 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index f888ef556..130f0d154 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -605,6 +605,16 @@ example:: In the example above, a literal block is "embedded" within a sentence that begins in one physical paragraph and ends in another. +.. note:: + + The "compound" directive is *not* a generic block-level container + like HTML's ``<div>`` element. Do not use it only to group a + sequence of elements, or you may get unexpected results. + + If you happen to need a generic block-level container, please + describe your use-case in an email to + docutils-users@lists.sourceforge.net. + Compound paragraphs are typically rendered as multiple distinct text blocks, with the possibility of variations to emphasize their logical unity: -- cgit v1.2.1 From 873ff59a77fea8390df56adc5aec025a3d766584 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 24 Apr 2005 03:01:33 +0000 Subject: updated footer descriptions git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3248 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index b5458017b..2ae37b9f5 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1233,9 +1233,7 @@ context. The ``decoration`` element is a container for header_ and footer_ elements and potential future extensions. These elements are used for -page navigation, notes, time/datestamp, etc. Currently only the -footer_ element is implemented, populated with processing information -(datestamp, a link to Docutils_, etc.). +notes, time/datestamp, processing information, etc. Details @@ -2242,8 +2240,9 @@ See the examples for the field_list_ and docinfo_ elements. The ``footer`` element is a container element whose contents are meant to appear at the bottom of a web page, or repeated at the bottom of -every printed page. Currently the ``footer`` element may contain -processing information (datestamp, a link to Docutils_, etc.). +every printed page. The ``footer`` element may contain processing +information (datestamp, a link to Docutils_, etc.) as well as custom +content. Details -- cgit v1.2.1 From df05185ff0a8c586230c827b46a1cf43544c65fa Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 2 May 2005 03:59:11 +0000 Subject: added ``line`` element; corrected ``line_block`` details git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3282 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 163 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 114 insertions(+), 49 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 2ae37b9f5..f432ed1f6 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -161,9 +161,8 @@ Simple body elements are empty or directly contain text data. Those that contain text data may also contain inline elements. Such elements therefore have a "mixed content model". -Category members: comment_, doctest_block_, image_, line_block_, -literal_block_, paragraph_, pending_, raw_, rubric_, -substitution_definition_, target_ +Category members: comment_, doctest_block_, image_, literal_block_, +paragraph_, pending_, raw_, rubric_, substitution_definition_, target_ Compound Body Elements @@ -175,8 +174,8 @@ and further body elements. They do not directly contain text data. Category members: admonition_, attention_, block_quote_, bullet_list_, caution_, citation_, compound_, danger_, definition_list_, enumerated_list_, error_, field_list_, figure_, footnote_, hint_, -important_, note_, option_list_, system_message_, table_, tip_, -warning_ +important_, line_block, note_, option_list_, system_message_, table_, +tip_, warning_ Body Subelements @@ -190,7 +189,8 @@ always occur within specific parent elements, never at the body element level (beside paragraphs, etc.). Category members (simple): attribution_, caption_, classifier_, -colspec_, field_name_, label_, option_argument_, option_string_, term_ +colspec_, field_name_, label_, line_, option_argument_, +option_string_, term_ Category members (compound): definition_, definition_list_item_, description_, entry_, field_, field_body_, legend_, list_item_, @@ -305,7 +305,8 @@ its writing. The ``address`` element holds the surface mailing address information for the author (individual or group) of the document, or a third-party contact address. Its structure is identical to that of the -line_block_ element: whitespace is significant, especially newlines. +literal_block_ element: whitespace is significant, especially +newlines. Details @@ -324,9 +325,9 @@ Details ``address`` is analogous to the DocBook "address" element. :Processing: - As with the line_block_ element, newlines and other whitespace is - significant and must be preserved. However, a monospaced typeface - need not be used. + As with the literal_block_ element, newlines and other whitespace + is significant and must be preserved. However, a monospaced + typeface need not be used. See also docinfo_. @@ -2538,21 +2539,67 @@ Pseudo-XML_ fragment from simple parsing:: `To be completed`_. +``line`` +======== + +The ``line`` element contains a single line of text, part of a +`line_block`_. + + +Details +------- + +:Category: + `Body Subelements`_ (simple) + +:Parents: + Only the `line_block`_ element contains ``line``. + +:Children: + ``line`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``line`` has no direct analogues in common DTDs. It can be + emulated with primitives or type effects. + +:Processing: + See `line_block`_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``line`` element contains the `common attributes`_ (id_, + name_, dupname_, source_, and class_), plus `xml:space`_. + + +Examples +-------- + +See `line_block`_. + + ``line_block`` ============== -The ``line_block`` element contains a block of text where line breaks -and whitespace are significant and must be preserved. ``line_block`` -elements are commonly used for verse and addresses. See `line_block`_ -for an alternative useful for program listings and interactive -computer sessions. +The ``line_block`` element contains a sequence of lines and nested +line blocks. Line breaks (implied between elements) and leading +whitespace (indicated by nesting) is significant and must be +preserved. ``line_block`` elements are commonly used for verse and +addresses. See `literal_block`_ for an alternative useful for program +listings and interactive computer sessions. Details ------- :Category: - `Simple Body Elements`_ + `Compound Body Elements`_ :Parents: All elements employing the `%body.elements;`_ or @@ -2560,8 +2607,8 @@ Details may contain ``line_block``. :Children: - ``line_block`` elements may contain text data plus `inline - elements`_. + ``line_block`` elements may contain line_ elements and nested + ``line_block`` elements. :Analogues: ``line_block`` is analogous to the DocBook "literallayout" element @@ -2570,7 +2617,7 @@ Details :Processing: Unline ``literal_block``, ``line_block`` elements are typically - rendered in an ordinary text typeface. It is crucial that all + rendered in an ordinary text typeface. It is crucial that leading whitespace and line breaks are preserved in the rendered form. @@ -2579,7 +2626,7 @@ Content Model .. parsed-literal:: - `%text.model;`_ + (line_ | line_block_)+ :Attributes: The ``line_block`` element contains the `common attributes`_ (id_, @@ -2599,40 +2646,58 @@ Example source:: Take it away, Eric the Orchestra Leader! - .. line-block:: - - A one, two, a one two three four - - Half a bee, philosophically, - must, *ipso facto*, half not be. - But half the bee has got to be, - *vis a vis* its entity. D'you see? - - But can a bee be said to be - or not to be an entire bee, - when half the bee is not a bee, - due to some ancient injury? - - Singing... + | A one, two, a one two three four + | + | Half a bee, philosophically, + | must, *ipso facto*, half not be. + | But half the bee has got to be, + | *vis a vis* its entity. D'you see? + | + | But can a bee be said to be + | or not to be an entire bee, + | when half the bee is not a bee, + | due to some ancient injury? + | + | Singing... Pseudo-XML_ fragment from simple parsing:: <paragraph> Take it away, Eric the Orchestra Leader! - <line_block xml:space="preserve"> - A one, two, a one two three four - - Half a bee, philosophically, - must, <emphasis>ipso facto</emphasis>, half not be. - But half the bee has got to be, - <emphasis>vis a vis</emphasis>its entity. D'you see? - - But can a bee be said to be - or not to be an entire bee, - when half the bee is not a bee, - due to some ancient injury? - - Singing... + <line_block> + <line> + A one, two, a one two three four + <line> + <line> + Half a bee, philosophically, + <line_block> + <line> + must, + <emphasis> + ipso facto + , half not be. + <line> + But half the bee has got to be, + <line_block> + <line> + <emphasis> + vis a vis + its entity. D'you see? + <line> + <line> + But can a bee be said to be + <line_block> + <line> + or not to be an entire bee, + <line_block> + <line> + when half the bee is not a bee, + <line_block> + <line> + due to some ancient injury? + <line> + <line> + Singing... ``list_item`` -- cgit v1.2.1 From 55cd5272b6cec7dc3cc9eae6bd8076dd0df064ab Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 9 May 2005 15:49:37 +0000 Subject: Added "border" option to "image" directive (& attribute to doctree element); updated docs & tests. Closes Feature Request 1193389. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3322 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 1 + docs/ref/rst/directives.txt | 6 ++++++ 2 files changed, 7 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index f3a7d37ca..455a8ae3a 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -481,6 +481,7 @@ or " ") or the text between option arguments (typically either "," or %align-hv.att; uri CDATA #REQUIRED alt CDATA #IMPLIED + border %number; #IMPLIED height %number; #IMPLIED width %number; #IMPLIED scale %number; #IMPLIED> diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 130f0d154..1ca51f28f 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -226,6 +226,12 @@ The following options are recognized: text flow around it. The specific behavior depends upon the browser or rendering software used. +``border`` : integer + The width of the image border, in pixels. For images that are + also hyperlink references (see the ``target`` option, below), + browsers often draw a border by default. Set ``:border: 0`` to + disable this default. + ``target`` : text (URI or reference name) Makes the image into a hyperlink reference ("clickable"). The option argument may be a URI (relative or absolute), or a -- cgit v1.2.1 From 9ed38a53f7de2eed5ed8ba98afb3e2ee28f2f75d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 14 May 2005 16:14:44 +0000 Subject: reverting revision 3322: addition of ":border:" option to "image" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3340 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 1 - docs/ref/rst/directives.txt | 6 ------ 2 files changed, 7 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 455a8ae3a..f3a7d37ca 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -481,7 +481,6 @@ or " ") or the text between option arguments (typically either "," or %align-hv.att; uri CDATA #REQUIRED alt CDATA #IMPLIED - border %number; #IMPLIED height %number; #IMPLIED width %number; #IMPLIED scale %number; #IMPLIED> diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 1ca51f28f..130f0d154 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -226,12 +226,6 @@ The following options are recognized: text flow around it. The specific behavior depends upon the browser or rendering software used. -``border`` : integer - The width of the image border, in pixels. For images that are - also hyperlink references (see the ``target`` option, below), - browsers often draw a border by default. Set ``:border: 0`` to - disable this default. - ``target`` : text (URI or reference name) Makes the image into a hyperlink reference ("clickable"). The option argument may be a URI (relative or absolute), or a -- cgit v1.2.1 From 4ae722d597317382b222737ecf0b898b224dddcd Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 18 May 2005 22:27:52 +0000 Subject: added SectSubTitle transform git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3351 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 9e4687a72..079bedaaa 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -34,6 +34,8 @@ frontmatter.DocTitle standalone (r) 320 frontmatter.DocInfo standalone (r) 340 +frontmatter.SectSubTitle standalone (r) 350 + peps.Headers pep (r) 360 peps.Contents pep (r) 380 -- cgit v1.2.1 From b7b2f9f3ecf1b3877314db63d09242dfe71b41fc Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 28 May 2005 00:30:02 +0000 Subject: replaced references to the mailing lists with references to the new "mailing-lists" document git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3396 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 10 ++++++---- docs/ref/rst/roles.txt | 6 ++++-- 2 files changed, 10 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 130f0d154..603b89b98 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -612,8 +612,10 @@ that begins in one physical paragraph and ends in another. sequence of elements, or you may get unexpected results. If you happen to need a generic block-level container, please - describe your use-case in an email to - docutils-users@lists.sourceforge.net. + describe your use-case in an email to the Docutils-users_ mailing + list. + + .. _Docutils-users: ../../user/mailing-lists.html#docutils-users Compound paragraphs are typically rendered as multiple distinct text blocks, with the possibility of variations to emphasize their logical @@ -1224,8 +1226,8 @@ Raw Data Pass-Through If you often need to use the "raw" directive or a "raw"-derived interpreted text role, that is a sign either of overuse/abuse or that functionality may be missing from reStructuredText. Please - describe your situation in email to - docutils-users@lists.sourceforge.net. + describe your situation in an email to the Docutils-users_ mailing + list. The "raw" directive indicates non-reStructuredText data that is to be passed untouched to the Writer. The names of the output formats are diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index a911cf469..1cb2e540b 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -276,8 +276,10 @@ must be used to obtain a ``title_reference`` element. If you often need to use "raw"-derived interpreted text roles or the "raw" directive, that is a sign either of overuse/abuse or that functionality may be missing from reStructuredText. Please - describe your situation in email to - docutils-users@lists.sourceforge.net. + describe your situation in an email to the Docutils-users_ mailing + list. + + .. _Docutils-users: ../../user/mailing-lists.html#docutils-user The "raw" role indicates non-reStructuredText data that is to be passed untouched to the Writer. It is the inline equivalent of the -- cgit v1.2.1 From 5095d1c0d6811a2180da6528e929347c10fc123e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 3 Jun 2005 23:52:18 +0000 Subject: added clarification git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3426 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 57362c5db..6d21934b4 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2213,6 +2213,8 @@ Replacement text __ http://developer.java.sun.com/developer/earlyAccess/ j2eecas/ + The "replace_" directive has been implemented. + Comments ```````` @@ -2815,6 +2817,7 @@ Markup errors are handled according to the specification in `PEP .. _HTML Techniques for Web Content Accessibility Guidelines: http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text .. _image: directives.html#image +.. _replace: directives.html#replace .. _meta: directives.html#meta .. _figure: directives.html#figure .. _admonition: directives.html#admonitions -- cgit v1.2.1 From c1312b37ba8887cf092065cb09f3d09ee034ac31 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 4 Jun 2005 04:01:58 +0000 Subject: added "default-role" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3427 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 603b89b98..d336a48dd 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1542,6 +1542,49 @@ details. .. _reStructuredText Interpreted Text Roles: roles.html +.. _default-role: + +Setting the Default Interpreted Text Role +========================================= + +:Directive Type: "default-role" +:Doctree Element: None; affects subsequent parsing. +:Directive Arguments: One, optional (new default role name). +:Directive Options: None. +:Directive Content: None. + +(New in Docutils 0.3.8) + +The "default-role" directive sets the default interpreted text role, +the role that is used for interpreted text without an explicit role. +For example, after setting the default role like this:: + + .. default-role:: subscript + +any subsequent use of implicit-role interpreted text in the document +will use the "subscript" role:: + + An example of a `default` role. + +This will be parsed into the following document tree fragment:: + + <paragraph> + An example of a + <subscript> + default + role. + +Custom roles may be used (see the "role_" directive above), but it +must have been declared in a document before it can be set as the +default role. See the `reStructuredText Interpreted Text Roles`_ +document for details of built-in roles. + +The directive may be used without an argument to restore the initial +default interpreted text role, which is application-dependent. The +initial default interpreted text role of the standard reStructuredText +parser is "title-reference". + + Restructuredtext-Test-Directive =============================== -- cgit v1.2.1 From 8190158763b3afc33a14d0674e7364fc2d2d26f6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 4 Jun 2005 04:08:25 +0000 Subject: updated & corrected docs git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3428 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index d336a48dd..dde952b7d 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1553,7 +1553,7 @@ Setting the Default Interpreted Text Role :Directive Options: None. :Directive Content: None. -(New in Docutils 0.3.8) +(New in Docutils 0.3.10) The "default-role" directive sets the default interpreted text role, the role that is used for interpreted text without an explicit role. -- cgit v1.2.1 From 61075e34557635f6facec931b31da5ec3b04243c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 9 Jun 2005 17:32:17 +0000 Subject: added "title" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3455 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index dde952b7d..a0102f9e1 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -634,6 +634,21 @@ The following option is recognized: class_ directive below. +Title +===== + +:Directive Type: "title" +:Doctree Element: None. +:Directive Arguments: 1, required (the title text). +:Directive Options: None. +:Directive Content: None. + +The "title" directive specifies the document title as metadata, which +does not become part of the document body. It overrides a +document-supplied title. For example, in HTML output the metadata +document title appears in the title bar of the browser window. + + -------- Tables -------- -- cgit v1.2.1 From d37a0a8fed7d6df884502b52da032379c5ff067b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 12 Jun 2005 04:20:01 +0000 Subject: removed redundancy with "encoding" option description git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3469 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index a0102f9e1..6ea521ac1 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1197,9 +1197,6 @@ example:: If an included document fragment contains section structure, the title adornments must match those of the master document. -The text encoding of the master input source is used for included -files. - The following options are recognized: ``literal`` : flag (empty) -- cgit v1.2.1 From ad8ed1d2dabfec3f3f0ab51f03355adc25cdb77d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 12 Jun 2005 05:00:49 +0000 Subject: updated location git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3471 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 6ea521ac1..bdcf3ac1f 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -634,21 +634,6 @@ The following option is recognized: class_ directive below. -Title -===== - -:Directive Type: "title" -:Doctree Element: None. -:Directive Arguments: 1, required (the title text). -:Directive Options: None. -:Directive Content: None. - -The "title" directive specifies the document title as metadata, which -does not become part of the document body. It overrides a -document-supplied title. For example, in HTML output the metadata -document title appears in the title bar of the browser window. - - -------- Tables -------- @@ -1597,6 +1582,23 @@ initial default interpreted text role of the standard reStructuredText parser is "title-reference". +.. _title: + +Metadata Document Title +======================= + +:Directive Type: "title" +:Doctree Element: None. +:Directive Arguments: 1, required (the title text). +:Directive Options: None. +:Directive Content: None. + +The "title" directive specifies the document title as metadata, which +does not become part of the document body. It overrides a +document-supplied title. For example, in HTML output the metadata +document title appears in the title bar of the browser window. + + Restructuredtext-Test-Directive =============================== -- cgit v1.2.1 From 3b7a7200860068db23463a6a4246c19814012ee9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 12 Jun 2005 16:40:14 +0000 Subject: Added standard data file syntax to the "include" directive. Added docutils/parsers/rst/include/ directory; contains the standard data files, with character entity substitution definition sets as initial contents. Added docs/ref/rst/substitutions.txt: "reStructuredText Standard Substitution Definition Sets". Updated docs, tests, & setup.py. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3472 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 16 ++++- docs/ref/rst/substitutions.txt | 134 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 149 insertions(+), 1 deletion(-) create mode 100644 docs/ref/rst/substitutions.txt (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index bdcf3ac1f..cf5c20361 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1149,7 +1149,7 @@ Including an External Document Fragment :Directive Type: "include" :Doctree Elements: depend on data being included -:Directive Arguments: One, required. +:Directive Arguments: One, required (path to the file to include). :Directive Options: Possible. :Directive Content: None. @@ -1182,6 +1182,20 @@ example:: If an included document fragment contains section structure, the title adornments must match those of the master document. +Standard data files intended for inclusion in reStructuredText +documents are distributed with the Docutils source code, located in +the "docutils" package in the ``docutils/parsers/rst/include`` +directory. To access these files, use the special syntax for standard +"include" data files, angle brackets around the file name:: + + .. include:: <isonum.txt> + +The current set of standard "include" data files consists of sets of +substitution definitions. See `reStructuredText Standard Substitution +Definition Sets`__ for details of the available standard data files. + +__ substitutions.html + The following options are recognized: ``literal`` : flag (empty) diff --git a/docs/ref/rst/substitutions.txt b/docs/ref/rst/substitutions.txt new file mode 100644 index 000000000..3ddb71123 --- /dev/null +++ b/docs/ref/rst/substitutions.txt @@ -0,0 +1,134 @@ +======================================================== + reStructuredText Standard Substitution Definition Sets +======================================================== +:Author: David Goodger +:Contact: goodger@python.org +:Revision: $Revision$ +:Date: $Date$ +:Copyright: This document has been placed in the public domain. + +.. contents:: + + +The data files described below contain sets of reStructuredText +`substitution definitions`__. They can be included in documents using +the `"include" directive's`__ special syntax for standard data files, +angle brackets around the file name:: + + .. include:: <filename.txt> + +__ restructuredtext.html#substitution-definitions +__ directives.html#include + +The definitions can then be used in documents using `substitution +references`__. For example, the copyright symbol is defined in +``isonum.txt`` as "copy":: + + .. include:: <isonum.txt> + + Copyright |copy| 2003 by John Q. Public, all rights reserved. + +__ restructuredtext.html#substitution-references + +Individual definitions can also be copied from these data files and +pasted into documents. This has two advantages: it removes +dependencies, and it saves processing of unused definitions. However, +multiple substitution definitions add clutter to the document. + +Substitution references require separation from the surrounding text +with whitespace or punctuation. To use a substitution without +intervening whitespace, you can use the disappearing-whitespace escape +sequence, backslash-space:: + + .. include:: isonum.txt + + Copyright |copy| 2003, BogusMegaCorp\ |trade|. + +Custom definitions may use the `"unicode" directive`__. Whitespace is +ignored and removed, effectively sqeezing together the text:: + + .. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN + .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 + .. with trademark sign + + Copyright |copy| 2003, |BogusMegaCorp (TM)|. + +__ directives.html#unicode + +In addition, the "ltrim", "rtrim", and "trim" options may be used with +the "unicode" directive to automatically trim spaces from the left, +right, or both sides (respectively) of substitution references:: + + .. |---| unicode:: U+02014 .. em dash + :trim: + +The individual data files are stored with the Docutils source code in +the "docutils" package, in the ``docutils/parsers/rst/include`` +directory. + + +Character Entity Sets +===================== + +The following files contain substitution definitions corresponding to +XML character entity sets, from the following standards: ISO 8879 & +ISO 9573-13 (combined), MathML, and XHTML1. They were generated by +the ``tools/unicode2rstsubs.py`` program from the input file +unicode.xml__, which is maintained as part of the MathML 2 +Recommentation XML source. + +__ http://www.w3.org/2003/entities/xml/ + +================== ================================================== +Entity Set File Description +================== ================================================== +isoamsa.txt Added Mathematical Symbols: Arrows +isoamsb.txt Added Mathematical Symbols: Binary Operators +isoamsc.txt Added Mathematical Symbols: Delimiters +isoamsn.txt Added Mathematical Symbols: Negated Relations +isoamso.txt Added Mathematical Symbols: Ordinary +isoamsr.txt Added Mathematical Symbols: Relations +isobox.txt Box and Line Drawing +isocyr1.txt Russian Cyrillic +isocyr2.txt Non-Russian Cyrillic +isodia.txt Diacritical Marks +isogrk1.txt Greek Letters +isogrk2.txt Monotoniko Greek +isogrk3.txt Greek Symbols +isogrk4.txt [1]_ Alternative Greek Symbols +isolat1.txt Added Latin 1 +isolat2.txt Added Latin 2 +isomfrk.txt [1]_ Mathematical Fraktur +isomopf.txt [1]_ Mathematical Openface (Double-struck) +isomscr.txt [1]_ Mathematical Script +isonum.txt Numeric and Special Graphic +isopub.txt Publishing +isotech.txt General Technical +mmlalias.txt MathML aliases for entities from other sets +mmlextra.txt [1]_ Extra names added by MathML +xhtml4-lat1.txt XHTML Latin 1 +xhtml4-special.txt XHTML Special Characters +xhtml4-symbol.txt XHTML Mathematical, Greek and Symbolic Characters +================== ================================================== + +.. [1] There are ``*-wide.txt`` variants for each of these character + entity set files, containing characters outside of the Unicode + basic multilingual plane or BMP (wide-Unicode; code points greater + than U+FFFF). Most pre-built Python distributions are "narrow" and + do not support wide-Unicode characters. Python *can* be built with + wide-Unicode support though; consult the Python build instructions + for details. + +For example, the copyright symbol is defined as the XML character +entity ``©``. The equivalent reStructuredText substitution +reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is +``|copy|``. + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: -- cgit v1.2.1 From 530bfbe824e80b0996edf5961ccf63d93f542afd Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 12 Jun 2005 16:44:50 +0000 Subject: correction git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3473 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/substitutions.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/substitutions.txt b/docs/ref/rst/substitutions.txt index 3ddb71123..d4ff17a42 100644 --- a/docs/ref/rst/substitutions.txt +++ b/docs/ref/rst/substitutions.txt @@ -80,7 +80,7 @@ Recommentation XML source. __ http://www.w3.org/2003/entities/xml/ ================== ================================================== -Entity Set File Description +Entity Set File Description ================== ================================================== isoamsa.txt Added Mathematical Symbols: Arrows isoamsb.txt Added Mathematical Symbols: Binary Operators -- cgit v1.2.1 From 04f2424447e9de96e74c65e24d68fab32bfa33e3 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 16 Jun 2005 22:03:08 +0000 Subject: added support for units in image widths and heights; I called a number combined with a unit (e.g. 5em) a "measure"; I am not entirely sure if that's the right term, though git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3497 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 7 +++++-- docs/ref/rst/directives.txt | 8 ++++++++ docs/ref/rst/restructuredtext.txt | 40 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 53 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index f3a7d37ca..fd47b6c91 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -39,6 +39,9 @@ by wrapper DTDs. <!-- Emphasize that the attribute value must be a number. --> <!ENTITY % number "NMTOKEN"> +<!-- A number which may be immediately followed by a unit. --> +<!ENTITY % measure "NMTOKEN"> + <!ENTITY % additional.basic.atts ""> <!-- Attributes shared by all elements in this DTD: @@ -481,8 +484,8 @@ or " ") or the text between option arguments (typically either "," or %align-hv.att; uri CDATA #REQUIRED alt CDATA #IMPLIED - height %number; #IMPLIED - width %number; #IMPLIED + height %measure; #IMPLIED + width %measure; #IMPLIED scale %number; #IMPLIED> <!ELEMENT caption %text.model;> diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index cf5c20361..2235c428f 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -202,11 +202,19 @@ The following options are recognized: specified, they are combined. For example, a height of 200 and a scale of 50 is equivalent to a height of 100 with no scale. + It is also possible to specify a `length value`_. + ``width`` : integer The width of the image in pixels, used to reserve space or scale the image horizontally. As with "height" above, when the "scale" option is also specified, they are combined. + It is also possible to specify a length_ or `percentage value`_. + + .. _length: + .. _length value: restructuredtext.html#length-units + .. _percentage value: restructuredtext.html#percentage-units + ``scale`` : integer The uniform scaling factor of the image, a percentage (but no "%" symbol is required or allowed). "100" means full-size, and is diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 6d21934b4..0823cc8eb 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2781,6 +2781,46 @@ characters (see `Escaping Mechanism`_ above). RFC2396_ and RFC2732_. +Units +===== + +All measures consist of a positive floating point number in standard +(non-scientific) notation and a unit, possibly separated by one or +more spaces. + +Units are only supported where explicitly mentioned in the reference +manuals. + + +Length Units +------------ + +The following length units are supported by the reStructuredText +parser: + +* em (ems, the height of the element's font) +* ex (x-height, the height of the letter "x") +* px (pixels, relative to the canvas resolution) +* in (inches; 1in=2.54cm) +* cm (centimeters; 1cm=10mm) +* mm (millimeters) +* pt (points; 1pt=1/72in) +* pc (picas; 1pc=12pt) + +(List and explanations taken from +http://www.htmlhelp.com/reference/css/units.html#length.) + +The following are all valid length values: "1.5em", "20 mm", ".5in". + + +Percentage Units +---------------- + +Percentage values have a percent sign ("%") as unit. Percentage +values are relative to other values, depending on the context in which +they occur. + + ---------------- Error Handling ---------------- -- cgit v1.2.1 From 1ff93dd94d3e3b0d398f88a6cfa3ece4558ef8ad Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 16 Jun 2005 22:07:31 +0000 Subject: documented what image widths as percentage are relative to git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3499 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 2235c428f..73614b043 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -209,7 +209,8 @@ The following options are recognized: the image horizontally. As with "height" above, when the "scale" option is also specified, they are combined. - It is also possible to specify a length_ or `percentage value`_. + It is also possible to specify a length_ or `percentage value`_ + (which is relative to the current line width). .. _length: .. _length value: restructuredtext.html#length-units -- cgit v1.2.1 From d1368a7bed991b9a20a12b51373ccf974c23cad0 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 17 Jun 2005 14:19:17 +0000 Subject: added link to default-role directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3504 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 1cb2e540b..b396af2eb 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -1,6 +1,7 @@ ========================================= reStructuredText Interpreted Text Roles ========================================= + :Author: David Goodger :Contact: goodger@users.sourceforge.net :Revision: $Revision$ @@ -20,7 +21,8 @@ with colons. For example:: A default role may be defined by applications of reStructuredText; it is used if no explicit ``:role:`` prefix or suffix is given. The -"default default role" is `:title-reference:`_. +"default default role" is `:title-reference:`_. It can be changed +using the default-role_ directive. See the `Interpreted Text`_ section in the `reStructuredText Markup Specification`_ for syntax details. For details on the hierarchy of @@ -30,6 +32,7 @@ implementation details, see `Creating reStructuredText Interpreted Text Roles`_. .. _"role" directive: directives.html#role +.. _default-role: directives.html#default-role .. _Interpreted Text: restructuredtext.html#interpreted-text .. _reStructuredText Markup Specification: restructuredtext.html .. _The Docutils Document Tree: ../doctree.html -- cgit v1.2.1 From 7fcc4af21966bb94d513017d40c68cc8335640f7 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 17 Jun 2005 15:20:28 +0000 Subject: added "New in Docutils 3.4.10" for units git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3506 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 8 +++++--- docs/ref/rst/restructuredtext.txt | 2 ++ 2 files changed, 7 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 73614b043..73c0b39ca 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -202,15 +202,17 @@ The following options are recognized: specified, they are combined. For example, a height of 200 and a scale of 50 is equivalent to a height of 100 with no scale. - It is also possible to specify a `length value`_. + New in Docutils 3.4.10: It is also possible to specify a `length + value`_. ``width`` : integer The width of the image in pixels, used to reserve space or scale the image horizontally. As with "height" above, when the "scale" option is also specified, they are combined. - It is also possible to specify a length_ or `percentage value`_ - (which is relative to the current line width). + New in Docutils 3.4.10: It is also possible to specify a length_ + or `percentage value`_ (which is relative to the current line + width). .. _length: .. _length value: restructuredtext.html#length-units diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 0823cc8eb..2282beac2 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2784,6 +2784,8 @@ characters (see `Escaping Mechanism`_ above). Units ===== +(New in Docutils 3.4.10.) + All measures consist of a positive floating point number in standard (non-scientific) notation and a unit, possibly separated by one or more spaces. -- cgit v1.2.1 From fb247a2c98d8fffdca2a6ede5235f1b9e28a27ae Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 28 Jun 2005 13:49:10 +0000 Subject: Added ``_stylesheet_required`` internal setting, docutils.transforms.html.StylesheetCheck transform, docs, tests, and support. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3617 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 079bedaaa..7bdcee1de 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -40,6 +40,8 @@ peps.Headers pep (r) 360 peps.Contents pep (r) 380 +html.StylesheetCheck html4css1 (w) 420 + references.AnonymousHyperlinks standalone (r), pep (r) 440 references.IndirectHyperlinks standalone (r), pep (r) 460 @@ -83,6 +85,7 @@ misc.CallBack n/a 990 Key: * (r): Reader +* (w): Writer * (d): Directive * (t): Transform * (/p): Via a "pending" node -- cgit v1.2.1 From 8d2b940d5d23fd968831db94e5fb7208cd27268b Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 29 Jun 2005 12:09:04 +0000 Subject: added "title" attribute to document tree reference git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3622 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 21 +++++++++++++++++++-- docs/ref/docutils.dtd | 4 +++- 2 files changed, 22 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index f432ed1f6..68bfb408f 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1785,8 +1785,11 @@ See the `%structure.model;`_ parameter entity for details of the body of a ``document``. :Attributes: - The ``document`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + The ``document`` element contains the `common attributes`_ (id_, + name_, dupname_, source_, and class_), plus an optional title__ + attribute which stores the document title metadata. + + __ `title (attribute)`_ Examples @@ -3975,6 +3978,8 @@ Pseudo-XML_ fragment from simple parsing:: 15% if the service is good. +.. _title: + ``title`` ========= @@ -4577,6 +4582,18 @@ whitespace. The attribute value should not be set in a document instance. +.. _title (attribute): + +``title`` +========= + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``title`` attribute stores the title metadata of a document. This +title is typically not part of the rendered document. It may for +example be used in HTML's ``title`` element. + + ---------------------------- Parameter Entity Reference ---------------------------- diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index fd47b6c91..f6628684a 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -196,7 +196,9 @@ http://www.oasis-open.org/html/tm9901.htm). decoration?, (docinfo, transition?)?, %structure.model; )> -<!ATTLIST document %basic.atts;> +<!ATTLIST document + %basic.atts; + title CDATA #IMPLIED> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.1 From 2703f7c25b10c10f59db93e0776cb81c1d181bca Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 5 Jul 2005 20:29:55 +0000 Subject: moved transition transform logic from universal.FinalChecks to a separate transform, misc.Transitions git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3657 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 7bdcee1de..28b9c002f 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -71,6 +71,8 @@ components.Filter "meta" (d/p) 780 universal.Decorations Transformer 820 +misc.Transitions standalone (r) 830 + universal.FinalChecks Transformer 840 universal.Messages Transformer 860 -- cgit v1.2.1 From e0a1eaac9d47da79a00c92c74ef7e789464421b7 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 5 Jul 2005 23:14:55 +0000 Subject: moved expose_internals logic out of FinalChecks into a separate transform, universal.ExposeInternals git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3658 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 28b9c002f..9468619fd 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -73,7 +73,9 @@ universal.Decorations Transformer 820 misc.Transitions standalone (r) 830 -universal.FinalChecks Transformer 840 +universal.ExposeInternals Transformer 840 + +universal.FinalChecks Transformer 850 universal.Messages Transformer 860 -- cgit v1.2.1 From 88b1bd28140150e41265cd8a84b5d0ee55f05138 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 5 Jul 2005 23:36:14 +0000 Subject: renamed universal.FinalChecks to references.DanglingReferences; changed priority to 680 git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3659 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 9468619fd..cd9cf3fe8 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -60,6 +60,8 @@ references.ExternalTargets standalone (r), pep (r) 640 references.InternalTargets standalone (r), pep (r) 660 +references.DanglingReferences standalone (r), pep (r) 680 + parts.SectNum "sectnum" (d/p) 710 parts.Contents "contents" (d/p), 720 @@ -71,12 +73,10 @@ components.Filter "meta" (d/p) 780 universal.Decorations Transformer 820 -misc.Transitions standalone (r) 830 +misc.Transitions standalone (r), pep (r) 830 universal.ExposeInternals Transformer 840 -universal.FinalChecks Transformer 850 - universal.Messages Transformer 860 universal.FilterMessages Transformer 870 -- cgit v1.2.1 From 7da476da6fda4e6f2be21d683c9616844ed55c37 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 17 Jul 2005 19:59:35 +0000 Subject: removed note on Unicode support of csv-table directive; ASCII NUL limitation isn't worth being documented (there is an explanatory error message); encoding option has been implemented git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3761 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 6 ------ 1 file changed, 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 73c0b39ca..b5941c8de 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -744,12 +744,6 @@ Working limitations: .. Add "strict" option to verify input? -* Due to limitations of the CSV parser, this directive is not Unicode - compatible. It may also have problems with ASCII NUL characters. - Accordingly, CSV tables should be ASCII-printable safe. - - .. Test with Unicode; see if that's really so. "encoding" option? - The following options are recognized: ``class`` : text -- cgit v1.2.1 From 1da732b52647b11e5dec0d202bede9ed758dcd3a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 29 Jul 2005 23:38:08 +0000 Subject: added hyperlinks to files git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3777 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/substitutions.txt | 92 +++++++++++++++++++++++++++--------------- 1 file changed, 60 insertions(+), 32 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/substitutions.txt b/docs/ref/rst/substitutions.txt index d4ff17a42..882239086 100644 --- a/docs/ref/rst/substitutions.txt +++ b/docs/ref/rst/substitutions.txt @@ -73,43 +73,43 @@ Character Entity Sets The following files contain substitution definitions corresponding to XML character entity sets, from the following standards: ISO 8879 & ISO 9573-13 (combined), MathML, and XHTML1. They were generated by -the ``tools/unicode2rstsubs.py`` program from the input file +the ``tools/dev/unicode2rstsubs.py`` program from the input file unicode.xml__, which is maintained as part of the MathML 2 Recommentation XML source. __ http://www.w3.org/2003/entities/xml/ -================== ================================================== -Entity Set File Description -================== ================================================== -isoamsa.txt Added Mathematical Symbols: Arrows -isoamsb.txt Added Mathematical Symbols: Binary Operators -isoamsc.txt Added Mathematical Symbols: Delimiters -isoamsn.txt Added Mathematical Symbols: Negated Relations -isoamso.txt Added Mathematical Symbols: Ordinary -isoamsr.txt Added Mathematical Symbols: Relations -isobox.txt Box and Line Drawing -isocyr1.txt Russian Cyrillic -isocyr2.txt Non-Russian Cyrillic -isodia.txt Diacritical Marks -isogrk1.txt Greek Letters -isogrk2.txt Monotoniko Greek -isogrk3.txt Greek Symbols -isogrk4.txt [1]_ Alternative Greek Symbols -isolat1.txt Added Latin 1 -isolat2.txt Added Latin 2 -isomfrk.txt [1]_ Mathematical Fraktur -isomopf.txt [1]_ Mathematical Openface (Double-struck) -isomscr.txt [1]_ Mathematical Script -isonum.txt Numeric and Special Graphic -isopub.txt Publishing -isotech.txt General Technical -mmlalias.txt MathML aliases for entities from other sets -mmlextra.txt [1]_ Extra names added by MathML -xhtml4-lat1.txt XHTML Latin 1 -xhtml4-special.txt XHTML Special Characters -xhtml4-symbol.txt XHTML Mathematical, Greek and Symbolic Characters -================== ================================================== +=================== ================================================= +Entity Set File Description +=================== ================================================= +isoamsa.txt_ Added Mathematical Symbols: Arrows +isoamsb.txt_ Added Mathematical Symbols: Binary Operators +isoamsc.txt_ Added Mathematical Symbols: Delimiters +isoamsn.txt_ Added Mathematical Symbols: Negated Relations +isoamso.txt_ Added Mathematical Symbols: Ordinary +isoamsr.txt_ Added Mathematical Symbols: Relations +isobox.txt_ Box and Line Drawing +isocyr1.txt_ Russian Cyrillic +isocyr2.txt_ Non-Russian Cyrillic +isodia.txt_ Diacritical Marks +isogrk1.txt_ Greek Letters +isogrk2.txt_ Monotoniko Greek +isogrk3.txt_ Greek Symbols +isogrk4.txt_ [1]_ Alternative Greek Symbols +isolat1.txt_ Added Latin 1 +isolat2.txt_ Added Latin 2 +isomfrk.txt_ [1]_ Mathematical Fraktur +isomopf.txt_ [1]_ Mathematical Openface (Double-struck) +isomscr.txt_ [1]_ Mathematical Script +isonum.txt_ Numeric and Special Graphic +isopub.txt_ Publishing +isotech.txt_ General Technical +mmlalias.txt_ MathML aliases for entities from other sets +mmlextra.txt_ [1]_ Extra names added by MathML +xhtml4-lat1.txt_ XHTML Latin 1 +xhtml4-special.txt_ XHTML Special Characters +xhtml4-symbol.txt_ XHTML Mathematical, Greek and Symbolic Characters +=================== ================================================= .. [1] There are ``*-wide.txt`` variants for each of these character entity set files, containing characters outside of the Unicode @@ -124,6 +124,34 @@ entity ``©``. The equivalent reStructuredText substitution reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is ``|copy|``. +.. _isoamsa.txt: ../../../docutils/parsers/rst/include/isoamsa.txt +.. _isoamsb.txt: ../../../docutils/parsers/rst/include/isoamsb.txt +.. _isoamsc.txt: ../../../docutils/parsers/rst/include/isoamsc.txt +.. _isoamsn.txt: ../../../docutils/parsers/rst/include/isoamsn.txt +.. _isoamso.txt: ../../../docutils/parsers/rst/include/isoamso.txt +.. _isoamsr.txt: ../../../docutils/parsers/rst/include/isoamsr.txt +.. _isobox.txt: ../../../docutils/parsers/rst/include/isobox.txt +.. _isocyr1.txt: ../../../docutils/parsers/rst/include/isocyr1.txt +.. _isocyr2.txt: ../../../docutils/parsers/rst/include/isocyr2.txt +.. _isodia.txt: ../../../docutils/parsers/rst/include/isodia.txt +.. _isogrk1.txt: ../../../docutils/parsers/rst/include/isogrk1.txt +.. _isogrk2.txt: ../../../docutils/parsers/rst/include/isogrk2.txt +.. _isogrk3.txt: ../../../docutils/parsers/rst/include/isogrk3.txt +.. _isogrk4.txt: ../../../docutils/parsers/rst/include/isogrk4.txt +.. _isolat1.txt: ../../../docutils/parsers/rst/include/isolat1.txt +.. _isolat2.txt: ../../../docutils/parsers/rst/include/isolat2.txt +.. _isomfrk.txt: ../../../docutils/parsers/rst/include/isomfrk.txt +.. _isomopf.txt: ../../../docutils/parsers/rst/include/isomopf.txt +.. _isomscr.txt: ../../../docutils/parsers/rst/include/isomscr.txt +.. _isonum.txt: ../../../docutils/parsers/rst/include/isonum.txt +.. _isopub.txt: ../../../docutils/parsers/rst/include/isopub.txt +.. _isotech.txt: ../../../docutils/parsers/rst/include/isotech.txt +.. _mmlalias.txt: ../../../docutils/parsers/rst/include/mmlalias.txt +.. _mmlextra.txt: ../../../docutils/parsers/rst/include/mmlextra.txt +.. _xhtml4-lat1.txt: ../../../docutils/parsers/rst/include/xhtml4-lat1.txt +.. _xhtml4-special.txt: ../../../docutils/parsers/rst/include/xhtml4-special.txt +.. _xhtml4-symbol.txt: ../../../docutils/parsers/rst/include/xhtml4-symbol.txt + .. Local Variables: -- cgit v1.2.1 From 679456246112254d9408e9da6ab70787a4eda0bf Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 30 Jul 2005 04:53:02 +0000 Subject: clarified/simplified git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3779 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 2282beac2..41045b84e 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -723,14 +723,16 @@ escaped in order to have the line parsed as an ordinary paragraph:: \A. Einstein was a really smart dude. -Nested enumerated lists must be created with indentation. For -example:: +Examples of nested enumerated lists:: - 1. Item 1. + 1. Item 1 initial text. a) Item 1a. b) Item 1b. + 2. a) Item 2a. + b) Item 2b. + Example syntax diagram:: +-------+----------------------+ -- cgit v1.2.1 From 01f344cfa4ebf63ce930644ca126783542418347 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 4 Aug 2005 03:00:27 +0000 Subject: add "new in Docutils 0.3.8" notice to auto-enumerated lists git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3786 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 41045b84e..23f6469b4 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -673,7 +673,8 @@ The following enumeration sequences are recognized: In addition, the auto-enumerator, "#", may be used to automatically enumerate a list. Auto-enumerated lists may begin with explicit enumeration, which sets the sequence. Fully auto-enumerated lists use -arabic numerals and begin with 1. +arabic numerals and begin with 1. (Auto-enumerated lists are new in +Docutils 0.3.8.) The following formatting types are recognized: @@ -1165,7 +1166,7 @@ Syntax diagram:: Line Blocks ----------- -Doctree elements: line_block, line. New in Docutils 0.3.5. +Doctree elements: line_block, line. (New in Docutils 0.3.5.) Line blocks are useful for address blocks, verse (poetry, song lyrics), and unadorned lists, where the structure of lines is -- cgit v1.2.1 From f8ffb27c69811c3e0b936505e4ab978ddd03dbdc Mon Sep 17 00:00:00 2001 From: lele <lele@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 14 Aug 2005 19:25:39 +0000 Subject: Fixed a typo in the Docutils release that introduced units git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3804 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 23f6469b4..264b9aabe 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2787,7 +2787,7 @@ characters (see `Escaping Mechanism`_ above). Units ===== -(New in Docutils 3.4.10.) +(New in Docutils 0.3.10.) All measures consist of a positive floating point number in standard (non-scientific) notation and a unit, possibly separated by one or -- cgit v1.2.1 From 572dab40eb2e04bea643f9d03f0900d91c4c6577 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 14 Aug 2005 20:24:03 +0000 Subject: two more typos git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3805 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index b5941c8de..2908d4959 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -202,7 +202,7 @@ The following options are recognized: specified, they are combined. For example, a height of 200 and a scale of 50 is equivalent to a height of 100 with no scale. - New in Docutils 3.4.10: It is also possible to specify a `length + New in Docutils 0.3.10: It is also possible to specify a `length value`_. ``width`` : integer @@ -210,7 +210,7 @@ The following options are recognized: the image horizontally. As with "height" above, when the "scale" option is also specified, they are combined. - New in Docutils 3.4.10: It is also possible to specify a length_ + New in Docutils 0.3.10: It is also possible to specify a length_ or `percentage value`_ (which is relative to the current line width). -- cgit v1.2.1 From 15f953a780c227ca084a01b0a87edc15ec88fca0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 18 Aug 2005 11:20:39 +0000 Subject: clarify colons in explicit target names git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3823 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 264b9aabe..6bbdd9361 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1851,7 +1851,7 @@ indirect. .. _split: `A Hyperlink`_ -If a reference name contains a colon followed by whitespace, either: +If the reference name contains any colons, either: - the phrase must be enclosed in backquotes:: -- cgit v1.2.1 From 25decd0059501f1581c3079896a21626fcdb8174 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 11 Sep 2005 22:26:19 +0000 Subject: updated docs: history and tranform list git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3873 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index cd9cf3fe8..05185d6ef 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -71,6 +71,8 @@ peps.PEPZero peps.Headers (t/p) 760 components.Filter "meta" (d/p) 780 +writer_aux.Compound newlatex2e (w) 810 + universal.Decorations Transformer 820 misc.Transitions standalone (r), pep (r) 830 -- cgit v1.2.1 From 5b111006c653af57889892100b7adc5ffcca8e6f Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 20 Sep 2005 20:04:53 +0000 Subject: Merged "transforms" branch into trunk. - Replaced ``default_transforms`` attribute of TransformSpec with ``get_transforms()`` method. - Added universal.Decorations and universal.ExposeInternals transforms as default transforms for all readers. - Added universal.Messages and universal.FilterMessages transforms as default transforms for all writers. - Added ``ReReader`` base class for readers that reread an existing document tree. - Added ``UnfilteredWriter`` base class for writers that pass the document tree on unchanged. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3892 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 05185d6ef..8cd01c895 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -73,15 +73,15 @@ components.Filter "meta" (d/p) 780 writer_aux.Compound newlatex2e (w) 810 -universal.Decorations Transformer 820 +universal.Decorations Reader (r) 820 misc.Transitions standalone (r), pep (r) 830 -universal.ExposeInternals Transformer 840 +universal.ExposeInternals Reader (r) 840 -universal.Messages Transformer 860 +universal.Messages Writer (w) 860 -universal.FilterMessages Transformer 870 +universal.FilterMessages Writer (w) 870 universal.TestMessages DocutilsTestSupport 880 -- cgit v1.2.1 From b709706e194b0134660d39a918d3f5429fe952ef Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 21 Sep 2005 19:15:45 +0000 Subject: adjusted spec to conform to actual behavior git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3896 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 6bbdd9361..ed6056e96 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -939,14 +939,9 @@ Processed, the "status" element's text will become simply "expansion text". The dollar sign delimiters and leading RCS keyword name are removed. -The RCS keyword processing only kicks in when both of these conditions -hold: - -1. The field list is in bibliographic context (first non-comment - construct in the document, after a document title if there is - one). - -2. The field name is a recognized bibliographic field name. +The RCS keyword processing only kicks in when the field list is in +bibliographic context (first non-comment construct in the document, +after a document title if there is one). Option Lists -- cgit v1.2.1 From c976bf8ced13397135c52212701c0ad3aed45013 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 22 Sep 2005 18:51:33 +0000 Subject: changed DanglingReferences priority back to 850 git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3897 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 8cd01c895..5e844e45c 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -60,8 +60,6 @@ references.ExternalTargets standalone (r), pep (r) 640 references.InternalTargets standalone (r), pep (r) 660 -references.DanglingReferences standalone (r), pep (r) 680 - parts.SectNum "sectnum" (d/p) 710 parts.Contents "contents" (d/p), 720 @@ -79,6 +77,8 @@ misc.Transitions standalone (r), pep (r) 830 universal.ExposeInternals Reader (r) 840 +references.DanglingReferences standalone (r), pep (r) 850 + universal.Messages Writer (w) 860 universal.FilterMessages Writer (w) 870 -- cgit v1.2.1 From 1b0c89fafde2292c03a0a21822ba083dca903bb1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 25 Sep 2005 15:49:54 +0000 Subject: added docutils/writers/support/ directory and removed tools/stylesheets/; updated defaults; removed docutils/transforms/html.py (no longer needed); removed ``_stylesheet_required`` internal setting; updated setup.py git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3901 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 5e844e45c..0595175b4 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -40,8 +40,6 @@ peps.Headers pep (r) 360 peps.Contents pep (r) 380 -html.StylesheetCheck html4css1 (w) 420 - references.AnonymousHyperlinks standalone (r), pep (r) 440 references.IndirectHyperlinks standalone (r), pep (r) 460 -- cgit v1.2.1 From 56141f49a0dff5ef21cd29e00479f41c4efd88db Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Sep 2005 13:31:55 +0000 Subject: clarification git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3910 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 2908d4959..f67ea4532 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1551,9 +1551,9 @@ base roles: specified, a "class" option with the directive argument (role name) as the value is implied. See the class_ directive above. -Specific roles may support other options and/or directive content. -See the `reStructuredText Interpreted Text Roles`_ document for -details. +Specific base roles may support other options and/or directive +content. See the `reStructuredText Interpreted Text Roles`_ document +for details. .. _reStructuredText Interpreted Text Roles: roles.html -- cgit v1.2.1 From 4c16652c99cfc1ba8ec7dd2697d606972a98e952 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 29 Sep 2005 13:10:07 +0000 Subject: Added support for "class" directive content. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3912 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index f67ea4532..88bcbf570 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1391,14 +1391,16 @@ Class :Directive Arguments: One or more, required (class names / attribute values). :Directive Options: None. -:Directive Content: None. +:Directive Content: Optional. If present, it is interpreted as body + elements. -The "class" directive sets a "class" attribute value on the first -immediately following non-comment element [#]_. For details of the -"class" attribute, see `its entry`__ in `The Docutils Document Tree`_. -The directive argument consists of one or more space-separated class -names, which are converted to lowercase and all non-alphanumeric -characters are converted to hyphens. (For the rationale, see below.) +The "class" directive sets the "class" attribute value on its content +or on the first immediately following non-comment element [#]_. For +details of the "class" attribute, see `its entry`__ in `The Docutils +Document Tree`_. The directive argument consists of one or more +space-separated class names, which are converted to lowercase and all +non-alphanumeric characters are converted to hyphens. (For the +rationale, see below.) __ ../doctree.html#class @@ -1415,6 +1417,12 @@ Examples:: This is an ordinary paragraph. + .. class:: multiple + + First paragraph. + + Second paragraph. + The text above is parsed and transformed into this doctree fragment:: <paragraph class="special"> @@ -1424,6 +1432,10 @@ The text above is parsed and transformed into this doctree fragment:: An Exceptional Section <paragraph> This is an ordinary paragraph. + <paragraph class="multiple"> + First paragraph. + <paragraph class="multiple"> + Second paragraph. .. [#] To set a "class" attribute value on a block quote, the "class" directive must be followed by an empty comment:: -- cgit v1.2.1 From 7d8c53e396f1ff64640cd8f2f9f093186504f727 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 2 Oct 2005 01:09:01 +0000 Subject: Updated for plural attributes "classes", "ids", "names", "dupnames". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3916 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 72 ++++++++++++++++++++++++++------------------------- docs/ref/docutils.dtd | 8 +++--- 2 files changed, 41 insertions(+), 39 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 68bfb408f..e6cd509de 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -4421,25 +4421,25 @@ system_message_ elements (via the `%backrefs.att;`_ parameter entity). The ``bullet`` attribute is used in the bullet_list_ element. -``class`` -========= +``classes`` +=========== `Attribute type`_: ``NMTOKENS``. Default value: none. -The ``class`` attribute contains one or more names used to classify an -element. The purpose of the attribute is to indicate an "is-a" -variant relationship, to allow an extensible way of defining +The ``classes`` attribute is a list containing one or more names used +to classify an element. The purpose of the attribute is to indicate +an "is-a" variant relationship, to allow an extensible way of defining sub-classes of existing elements. It can be used to carry context forward between a Docutils Reader and Writer, when a custom structure is reduced to a standardized document tree. One common use is in conjunction with stylesheets, to add selection criteria. It should not be used to carry formatting instructions or arbitrary content. -The ``class`` attribute's contents should be ignorable. Writers that +The ``classes`` attribute's contents should be ignorable. Writers that are not familiar with the variant expressed should be able to ignore the attribute. -``class`` is one of the `common attributes`_, shared by all Docutils +``classes`` is one of the `common attributes`_, shared by all Docutils elements. @@ -4451,17 +4451,17 @@ elements. The ``delimiter`` attribute is used in the option_argument_ element. -``dupname`` -=========== +``dupnames`` +============ -`Attribute type`_: ``NMTOKENS``. Default value: none. +`Attribute type`_: ``CDATA``. Default value: none. -The ``dupname`` attribute contains the name of an element when there -has been a naming conflict. The contents of the ``dupname`` attribute -would have been transferred from the `name`_ attribute. An element -may have at most one of the ``name`` or ``dupname`` attributes, but -not both. ``dupname`` is one of the `common attributes`_, shared by -all Docutils elements. +The ``dupnames`` attribute is a list containing the names of an +element when there has been a naming conflict. The contents of the +``dupnames`` attribute would have been transferred from the `names`_ +attribute. An element may have at most one of the ``names`` or +``dupnames`` attributes, but not both. ``dupnames`` is one of the +`common attributes`_, shared by all Docutils elements. ``enumtype`` @@ -4473,27 +4473,29 @@ all Docutils elements. The ``enumtype`` attribute is used in the enumerated_list_ element. -``id`` -====== +``ids`` +======= -`Attribute type`_: ``ID``. Default value: none. +`Attribute type`_: ``NMTOKENS``. Default value: none. -The ``id`` attribute contains a unique identifier key. ``id`` is one -of the `common attributes`_, shared by all Docutils elements. +The ``ids`` attribute is a list containing one or more unique +identifier keys. ``ids`` is one of the `common attributes`_, shared +by all Docutils elements. -``name`` -======== +``names`` +========= -`Attribute type`_: ``NMTOKENS``. Default value: none. +`Attribute type`_: ``CDATA``. Default value: none. -The ``name`` attribute contains the name of an element, typically -originating from the element's title or content. ``name`` must be -unique; if there are name conflicts (two or more elements want to the -same name), the contents will be transferred to the `dupname`_ -attribute on the duplicate elements. An element may have at most one -of the ``name`` or ``dupname`` attributes, but not both. ``name`` is -one of the `common attributes`_, shared by all Docutils elements. +The ``names`` attribute is a list containing the names of an element, +typically originating from the element's title or content. Each name +in ``names`` must be unique; if there are name conflicts (two or more +elements want to the same name), the contents will be transferred to +the `dupnames`_ attribute on the duplicate elements. An element may +have at most one of the ``names`` or ``dupnames`` attributes, but not +both. ``names`` is one of the `common attributes`_, shared by all +Docutils elements. ``prefix`` @@ -4668,11 +4670,11 @@ Entity definition: .. parsed-literal:: - id_ ID #IMPLIED - name_ NMTOKENS #IMPLIED - dupname_ NMTOKENS #IMPLIED + ids_ NMTOKENS #IMPLIED + names_ CDATA #IMPLIED + dupnames_ CDATA #IMPLIED source_ CDATA #IMPLIED - class_ NMTOKENS #IMPLIED + classes_ NMTOKENS #IMPLIED %additional.basic.atts; The ``%additional.basic.atts;`` parameter entity can be used by diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index f6628684a..c2024391f 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -53,11 +53,11 @@ Attributes shared by all elements in this DTD: - `class` is used to transmit individuality information forward. --> <!ENTITY % basic.atts - " id ID #IMPLIED - name CDATA #IMPLIED - dupname CDATA #IMPLIED + " ids NMTOKENS #IMPLIED + names CDATA #IMPLIED + dupnames CDATA #IMPLIED source CDATA #IMPLIED - class NMTOKENS #IMPLIED + classes NMTOKENS #IMPLIED %additional.basic.atts; "> <!-- External reference to a URI/URL. --> -- cgit v1.2.1 From 5ba8d0c43d40007f043459bdf0f842ca52d9add7 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 2 Oct 2005 04:39:00 +0000 Subject: fixed references git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3917 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 148 +++++++++++++++++++++++++-------------------------- 1 file changed, 74 insertions(+), 74 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index e6cd509de..caffc3a89 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -340,8 +340,8 @@ Content Model `%text.model;`_ :Attributes: - The ``address`` element contains the `common attributes`_ (id_, - name_, dupname_, source_, and class_), plus `xml:space`_. + The ``address`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus `xml:space`_. :Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes @@ -413,7 +413,7 @@ Content Model :Attributes: The ``admonition`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -480,7 +480,7 @@ Content Model :Attributes: The ``attention`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -542,7 +542,7 @@ Content Model :Attributes: The ``author`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes @@ -608,7 +608,7 @@ Content Model :Attributes: The ``authors`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes @@ -686,7 +686,7 @@ Content Model :Attributes: The ``block_quote`` element contains only the `common - attributes`_: id_, name_, dupname_, source_, and class_. + attributes`_: ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -760,7 +760,7 @@ Content Model :Attributes: The ``bullet_list`` element contains the `common attributes`_ - (id_, name_, dupname_, source_, and class_), plus bullet_. + (ids_, names_, dupnames_, source_, and classes_), plus bullet_. ``bullet`` is used to record the style of bullet from the input data. In documents processed from reStructuredText_, it contains @@ -844,7 +844,7 @@ Content Model :Attributes: The ``caution`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -915,7 +915,7 @@ Content Model :Attributes: The ``classifier`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -1005,7 +1005,7 @@ Content Model :Attributes: The ``contact`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes @@ -1071,7 +1071,7 @@ Content Model :Attributes: The ``copyright`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes @@ -1142,7 +1142,7 @@ Content Model :Attributes: The ``danger`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -1199,7 +1199,7 @@ Content Model :Attributes: The ``date`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes @@ -1270,7 +1270,7 @@ empty ``decoration`` elements are ever created. :Attributes: The ``decoration`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -1329,7 +1329,7 @@ Content Model :Attributes: The ``definition`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -1380,7 +1380,7 @@ Content Model :Attributes: The ``definition_list`` element contains only the `common - attributes`_: id_, name_, dupname_, source_, and class_. + attributes`_: ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -1462,7 +1462,7 @@ Content Model :Attributes: The ``definition_list_item`` element contains only the `common - attributes`_: id_, name_, dupname_, source_, and class_. + attributes`_: ids_, names_, dupnames_, source_, and classes_. Examples @@ -1542,7 +1542,7 @@ Content Model :Attributes: The ``description`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -1600,7 +1600,7 @@ Content Model :Attributes: The ``docinfo`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -1706,7 +1706,7 @@ Content Model :Attributes: The ``doctest_block`` element contains the `common attributes`_ - (id_, name_, dupname_, source_, and class_), plus `xml:space`_. + (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -1785,8 +1785,8 @@ See the `%structure.model;`_ parameter entity for details of the body of a ``document``. :Attributes: - The ``document`` element contains the `common attributes`_ (id_, - name_, dupname_, source_, and class_), plus an optional title__ + The ``document`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus an optional title__ attribute which stores the document title metadata. __ `title (attribute)`_ @@ -1873,7 +1873,7 @@ Content Model :Attributes: The ``enumerated_list`` element contains the `common attributes`_ - (id_, name_, dupname_, source_, and class_), plus enumtype_, + (ids_, names_, dupnames_, source_, and classes_), plus enumtype_, prefix_, suffix_, and start_. ``enumtype`` is used to record the intended enumeration sequence, @@ -1980,8 +1980,8 @@ Content Model (`%body.elements;`_)+ :Attributes: - The ``error`` element contains only the `common attributes`_: id_, - name_, dupname_, source_, and class_. + The ``error`` element contains only the `common attributes`_: ids_, + names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -2040,7 +2040,7 @@ Content Model :Attributes: The ``field`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes @@ -2088,7 +2088,7 @@ Content Model :Attributes: The ``field_body`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -2142,7 +2142,7 @@ Content Model :Attributes: The ``field_list`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -2224,7 +2224,7 @@ Content Model :Attributes: The ``field_name`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -2276,7 +2276,7 @@ Content Model :Attributes: The ``footer`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -2356,7 +2356,7 @@ Content Model :Attributes: The ``header`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -2416,8 +2416,8 @@ Content Model (`%body.elements;`_)+ :Attributes: - The ``hint`` element contains only the `common attributes`_: id_, - name_, dupname_, source_, and class_. + The ``hint`` element contains only the `common attributes`_: ids_, + names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -2486,7 +2486,7 @@ Content Model :Attributes: The ``important`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -2577,8 +2577,8 @@ Content Model `%text.model;`_ :Attributes: - The ``line`` element contains the `common attributes`_ (id_, - name_, dupname_, source_, and class_), plus `xml:space`_. + The ``line`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus `xml:space`_. Examples @@ -2632,8 +2632,8 @@ Content Model (line_ | line_block_)+ :Attributes: - The ``line_block`` element contains the `common attributes`_ (id_, - name_, dupname_, source_, and class_), plus `xml:space`_. + The ``line_block`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus `xml:space`_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -2740,7 +2740,7 @@ Content Model :Attributes: The ``list_item`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -2825,7 +2825,7 @@ Content Model :Attributes: The ``literal_block`` element contains the `common attributes`_ - (id_, name_, dupname_, source_, and class_), plus `xml:space`_. + (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -2896,8 +2896,8 @@ Content Model (`%body.elements;`_)+ :Attributes: - The ``note`` element contains only the `common attributes`_: id_, - name_, dupname_, source_, and class_. + The ``note`` element contains only the `common attributes`_: ids_, + names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -2957,7 +2957,7 @@ Content Model :Attributes: The ``option`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -3004,8 +3004,8 @@ Content Model (#PCDATA) :Attributes: - The ``option_argument`` element contains the `common attributes`_ (id_, - name_, dupname_, source_, and class_), plus delimiter_. + The ``option_argument`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus delimiter_. ``delimiter`` contains the text preceding the ``option_argument``: either the text separating it from the option_string_ (typically @@ -3060,7 +3060,7 @@ Content Model :Attributes: The ``option_group`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -3111,7 +3111,7 @@ Content Model :Attributes: The ``option_list`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -3197,7 +3197,7 @@ Content Model :Attributes: The ``option_list_item`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -3242,7 +3242,7 @@ Content Model :Attributes: The ``option_string`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -3288,7 +3288,7 @@ Content Model :Attributes: The ``organization`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes @@ -3354,7 +3354,7 @@ Content Model :Attributes: The ``paragraph`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -3437,7 +3437,7 @@ Content Model :Attributes: The ``revision`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes @@ -3533,7 +3533,7 @@ of a ``section``. :Attributes: The ``section`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%section.elements;`_ parameter entity directly includes @@ -3639,7 +3639,7 @@ Content Model :Attributes: The ``sidebar`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%structure.model;`_ parameter entity directly includes @@ -3705,7 +3705,7 @@ Content Model :Attributes: The ``status`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes @@ -3795,7 +3795,7 @@ Content Model :Attributes: The ``subtitle`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -3824,7 +3824,7 @@ Complete pseudo-XML_ result after parsing and applying transforms:: Note how two section levels have collapsed, promoting their titles to become the document's title and subtitle. Since there is only one -structural element (document), the subsection's ``id`` and ``name`` +structural element (document), the subsection's ``ids`` and ``names`` attributes are stored in the ``subtitle`` element. @@ -3894,7 +3894,7 @@ Content Model :Attributes: The ``term`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. Examples @@ -3955,8 +3955,8 @@ Content Model (`%body.elements;`_)+ :Attributes: - The ``tip`` element contains only the `common attributes`_: id_, - name_, dupname_, source_, and class_. + The ``tip`` element contains only the `common attributes`_: ids_, + names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes ``tip``. @@ -4013,8 +4013,8 @@ Content Model `%text.model;`_ :Attributes: - The ``title`` element contains the `common attributes`_ (id_, - name_, dupname_, source_, and class_), plus refid_ and auto_. + The ``title`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus refid_ and auto_. ``refid`` is used as a backlink to a table of contents entry. @@ -4089,7 +4089,7 @@ Content Model :Attributes: The ``topic`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%structure.model;`_ parameter entity directly includes @@ -4174,7 +4174,7 @@ The ``transition`` element has no content; it is a "point element". :Attributes: The ``transition`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%structure.model;`_ parameter entity directly includes @@ -4240,7 +4240,7 @@ Content Model :Attributes: The ``version`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes @@ -4310,7 +4310,7 @@ Content Model :Attributes: The ``warning`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + ids_, names_, dupnames_, source_, and classes_. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -4340,8 +4340,8 @@ Pseudo-XML_ fragment from simple parsing:: :depth: 1 _`Common Attributes`: Through the `%basic.atts;`_ parameter entity, -all elements contain the following attributes: id_, name_, dupname_, -source_, and class_. +all elements contain the following attributes: ids_, names_, dupnames_, +source_, and classes_. .. _attribute type: @@ -4408,7 +4408,7 @@ footnote_, footnote_reference_ and title_ elements (via the `Attribute type`_: ``IDREFS``. Default value: none. -The ``backrefs`` attribute contains a space-separated list of id_ +The ``backrefs`` attribute contains a space-separated list of ids_ references, used for backlinks from footnote_, citation_, and system_message_ elements (via the `%backrefs.att;`_ parameter entity). @@ -4511,7 +4511,7 @@ The ``prefix`` attribute is used in the enumerated_list_ element. `Attribute type`_: ``IDREF``. Default value: none. -The ``refid`` attribute contains references to `id`_ attributes in +The ``refid`` attribute contains references to `ids`_ attributes in other elements. It is used by the target_, reference_, footnote_reference_, citation_reference_, title_ and problematic_ elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter @@ -4524,7 +4524,7 @@ entities). `Attribute type`_: ``NMTOKENS``. Default value: none. The ``refname`` attribute contains an internal reference to the -`name`_ attribute of another element. On a `target`_ element, +`names`_ attribute of another element. On a `target`_ element, ``refname`` indicates an indirect target which may resolve to either an internal or external reference. ``refname`` is used by the target_, reference_, footnote_reference_, citation_reference_, and @@ -4817,7 +4817,7 @@ their attribute lists. ================ The ``%refid.att;`` parameter entity contains the refid_ attribute, an -internal reference to the `id`_ attribute of another element. +internal reference to the `ids`_ attribute of another element. Entity definition: @@ -4837,7 +4837,7 @@ footnote_reference_, reference_, and target_ elements. ================= The ``%refname.att;`` parameter entity contains the refname_ -attribute, an internal reference to the `name`_ attribute of another +attribute, an internal reference to the `names`_ attribute of another element. On a `target`_ element, ``refname`` indicates an indirect target which may resolve to either an internal or external reference. -- cgit v1.2.1 From 554fd14a2991750dd134aee52d40c6806aa0e8ad Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 11 Oct 2005 13:14:13 +0000 Subject: clarified row separators in simple tables git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3932 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index ed6056e96..921ac31a4 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1390,7 +1390,8 @@ Simple tables are described with horizontal borders made up of "=" and "-" characters. The equals sign ("=") is used for top and bottom table borders, and to separate optional header rows from the table body. The hyphen ("-") is used to indicate column spans in a single -row by underlining the joined columns. +row by underlining the joined columns, and may optionally be used to +explicitly and/or visually separate rows. A simple table begins with a top border of equals signs with one or more spaces at each column boundary (two or more spaces recommended). -- cgit v1.2.1 From 2b57cc35ca4e7793926e93ad1f7642acac61f5df Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 28 Oct 2005 16:11:45 +0000 Subject: clarified role of indentation git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3960 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 921ac31a4..3359d19a7 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -241,15 +241,14 @@ line of a document is treated as if it is followed by a blank line. Indentation ----------- -Indentation is used to indicate, and is only significant in -indicating: - -- multi-line contents of list items, -- multiple body elements within a list item (including nested lists), -- the definition part of a definition list item, -- block quotes, -- the extent of literal blocks, and -- the extent of explicit markup blocks. +Indentation is used to indicate -- and is only significant in +indicating -- block quotes, definitions (in definition list items), +and local nested content: + +- list item content (multi-line contents of list items, and multiple + body elements within a list item, including nested lists), +- the content of literal blocks, and +- the content of explicit markup blocks. Any text whose indentation is less than that of the current level (i.e., unindented text or "dedents") ends the current level of -- cgit v1.2.1 From 5eaa35732246484d010b80d2848eba8cd77158d8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 28 Oct 2005 16:12:56 +0000 Subject: added the "container" element & directive, a generic container git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3963 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 22 ++++++++++++++-------- docs/ref/docutils.dtd | 5 ++++- docs/ref/rst/directives.txt | 38 +++++++++++++++++++++++++++++++++----- 3 files changed, 51 insertions(+), 14 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index caffc3a89..25e5f9594 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -146,12 +146,12 @@ body elements. There are two subcategories of body elements: simple and compound. Category members: admonition_, attention_, block_quote_, bullet_list_, -caution_, citation_, comment_, compound_, danger_, definition_list_, -doctest_block_, enumerated_list_, error_, field_list_, figure_, -footnote_, hint_, image_, important_, line_block_, literal_block_, -note_, option_list_, paragraph_, pending_, raw_, rubric_, -substitution_definition_, system_message_, table_, target_, tip_, -warning_ +caution_, citation_, comment_, compound_, container_, danger_, +definition_list_, doctest_block_, enumerated_list_, error_, +field_list_, figure_, footnote_, hint_, image_, important_, +line_block_, literal_block_, note_, option_list_, paragraph_, +pending_, raw_, rubric_, substitution_definition_, system_message_, +table_, target_, tip_, warning_ Simple Body Elements @@ -172,7 +172,7 @@ Compound body elements contain local substructure (body subelements) and further body elements. They do not directly contain text data. Category members: admonition_, attention_, block_quote_, bullet_list_, -caution_, citation_, compound_, danger_, definition_list_, +caution_, citation_, compound_, container_, danger_, definition_list_, enumerated_list_, error_, field_list_, figure_, footnote_, hint_, important_, line_block, note_, option_list_, system_message_, table_, tip_, warning_ @@ -1036,6 +1036,12 @@ See docinfo_ for a more complete example, including processing context. +``container`` +============= + +`To be completed`_. + + ``copyright`` ============= @@ -4714,7 +4720,7 @@ Entity definition: .. parsed-literal:: - paragraph_ | compound_ | literal_block_ | doctest_block_ + paragraph_ | compound_ | container_ | literal_block_ | doctest_block_ | line_block_ | block_quote_ | table_ | figure_ | image_ | footnote_ | citation_ | rubric_ | bullet_list_ | enumerated_list_ | definition_list_ | field_list_ diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index c2024391f..154566033 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -124,7 +124,7 @@ resolve to either an internal or external reference. <!ENTITY % additional.body.elements ""> <!ENTITY % body.elements - " paragraph | compound | literal_block | doctest_block + " paragraph | compound | container | literal_block | doctest_block | line_block | block_quote | table | figure | image | footnote | citation | rubric | bullet_list | enumerated_list | definition_list | field_list @@ -308,6 +308,9 @@ Eventual replacement for docinfo? --> <!ELEMENT compound (%body.elements;)+> <!ATTLIST compound %basic.atts;> +<!ELEMENT container (%body.elements;)+> +<!ATTLIST container %basic.atts;> + <!ELEMENT bullet_list (list_item+)> <!ATTLIST bullet_list %basic.atts; diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 88bcbf570..ec6dceb41 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -622,11 +622,8 @@ that begins in one physical paragraph and ends in another. like HTML's ``<div>`` element. Do not use it only to group a sequence of elements, or you may get unexpected results. - If you happen to need a generic block-level container, please - describe your use-case in an email to the Docutils-users_ mailing - list. - - .. _Docutils-users: ../../user/mailing-lists.html#docutils-users + If you need a generic block-level container, please use the + container_ directive, described below. Compound paragraphs are typically rendered as multiple distinct text blocks, with the possibility of variations to emphasize their logical @@ -645,6 +642,37 @@ The following option is recognized: class_ directive below. +Container +========= + +:Directive Type: "container" +:Doctree Element: container +:Directive Arguments: One or more, optional (class names). +:Directive Options: None. +:Directive Content: Interpreted as body elements. + +(New in Docutils 0.3.10) + +The "container" directive surrounds its contents (arbitrary body +elements) with a generic block-level "container" element. Combined +with the optional "class_" attribute argument(s), this is an extension +mechanism for users & applications. For example:: + + .. container:: custom + + This paragraph might be rendered in a custom way. + +Parsing the above results in the following pseudo-XML:: + + <container classes="custom"> + <paragraph> + This paragraph might be rendered in a custom way. + +The "container" directive is the equivalent of HTML's ``<div>`` +element. It may be used to group a sequence of elements for user- or +application-specific purposes. + + -------- Tables -------- -- cgit v1.2.1 From 4250498dab37bd03b15cce64e310a3b9eba7233a Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 29 Oct 2005 11:53:25 +0000 Subject: added missing target; typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3966 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 ++ docs/ref/rst/restructuredtext.txt | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index ec6dceb41..a2b016f57 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1273,6 +1273,8 @@ Raw Data Pass-Through describe your situation in an email to the Docutils-users_ mailing list. +.. _Docutils-users: ../../user/mailing-lists.html#docutils-users + The "raw" directive indicates non-reStructuredText data that is to be passed untouched to the Writer. The names of the output formats are given in the directive arguments. The interpretation of the raw data diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 3359d19a7..d503d9054 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2239,7 +2239,7 @@ constructs is recognized, leave the ".." on a line by itself:: .. |even| this:: ! -A explicit markup start followed by a blank line and nothing else +An explicit markup start followed by a blank line and nothing else (apart from whitespace) is an "empty comment". It serves to terminate a preceding construct, and does **not** consume any indented text following. To have a block quote follow a list or any indented -- cgit v1.2.1 From e033ee28f912b3a7c0708c318daff3fd43d7859b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 29 Oct 2005 12:21:09 +0000 Subject: another minor text fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3967 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index a2b016f57..0b2148267 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1270,7 +1270,7 @@ Raw Data Pass-Through If you often need to use the "raw" directive or a "raw"-derived interpreted text role, that is a sign either of overuse/abuse or that functionality may be missing from reStructuredText. Please - describe your situation in an email to the Docutils-users_ mailing + describe your situation in a message to the Docutils-users_ mailing list. .. _Docutils-users: ../../user/mailing-lists.html#docutils-users -- cgit v1.2.1 From db725ada9c838f95536ce02e0d311ac0387180d3 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 29 Oct 2005 14:39:45 +0000 Subject: fixed links git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3974 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 4 ++-- docs/ref/rst/introduction.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 0b2148267..58fa324cf 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -844,7 +844,7 @@ List Table (New in Docutils 0.3.8. This is an initial implementation; `further ideas`__ may be implemented in the future.) -__ http://docutils.sf.net/docs/dev/rst/alternatives.html#list-driven-tables +__ ../../dev/rst/alternatives.html#list-driven-tables The "list-table" directive is used to create a table from data in a uniform two-level bullet list. "Uniform" means that each sublist @@ -1512,7 +1512,7 @@ The text above is parsed and transformed into this doctree fragment:: character must be a letter; no "unicode", "latin1", or "escape" characters), this results in the ``[a-z](-?[a-z0-9]+)*`` pattern. - .. _HTML 4.01 spec: http://www.w3.org/TR/html401 + .. _HTML 4.01 spec: http://www.w3.org/TR/html401/ .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1 diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index 2b64399a5..b7829816e 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -31,7 +31,7 @@ http://docutils.sourceforge.net/rst.html. .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _StructuredText: - http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage + http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage .. _Setext: http://docutils.sourceforge.net/mirror/setext.html .. _Docutils: http://docutils.sourceforge.net/ .. _A ReStructuredText Primer: ../../user/rst/quickstart.html @@ -295,7 +295,7 @@ followed. http://structuredtext.sourceforge.net/ .. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ .. _StructuredTextNG: - http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG + http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG .. _project history file: ../../../HISTORY.html .. _PEP 287: ../../peps/pep-0287.html .. _Docstring Processing System framework: ../../peps/pep-0256.html -- cgit v1.2.1 From 049c0dd4035c4f6aae3b0491f159535539e1c032 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 29 Oct 2005 21:17:26 +0000 Subject: fixed more occurences of "an email" git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3978 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index b396af2eb..3b8b114bc 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -279,7 +279,7 @@ must be used to obtain a ``title_reference`` element. If you often need to use "raw"-derived interpreted text roles or the "raw" directive, that is a sign either of overuse/abuse or that functionality may be missing from reStructuredText. Please - describe your situation in an email to the Docutils-users_ mailing + describe your situation in a message to the Docutils-users_ mailing list. .. _Docutils-users: ../../user/mailing-lists.html#docutils-user -- cgit v1.2.1 From 9cb76ea8dfc48a41b2a45e04d13ffa9b9d370f6d Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Nov 2005 23:16:02 +0000 Subject: fixed links git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3998 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/substitutions.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/substitutions.txt b/docs/ref/rst/substitutions.txt index 882239086..5ea9562f2 100644 --- a/docs/ref/rst/substitutions.txt +++ b/docs/ref/rst/substitutions.txt @@ -106,9 +106,9 @@ isopub.txt_ Publishing isotech.txt_ General Technical mmlalias.txt_ MathML aliases for entities from other sets mmlextra.txt_ [1]_ Extra names added by MathML -xhtml4-lat1.txt_ XHTML Latin 1 -xhtml4-special.txt_ XHTML Special Characters -xhtml4-symbol.txt_ XHTML Mathematical, Greek and Symbolic Characters +xhtml1-lat1.txt_ XHTML Latin 1 +xhtml1-special.txt_ XHTML Special Characters +xhtml1-symbol.txt_ XHTML Mathematical, Greek and Symbolic Characters =================== ================================================= .. [1] There are ``*-wide.txt`` variants for each of these character @@ -148,9 +148,9 @@ reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is .. _isotech.txt: ../../../docutils/parsers/rst/include/isotech.txt .. _mmlalias.txt: ../../../docutils/parsers/rst/include/mmlalias.txt .. _mmlextra.txt: ../../../docutils/parsers/rst/include/mmlextra.txt -.. _xhtml4-lat1.txt: ../../../docutils/parsers/rst/include/xhtml4-lat1.txt -.. _xhtml4-special.txt: ../../../docutils/parsers/rst/include/xhtml4-special.txt -.. _xhtml4-symbol.txt: ../../../docutils/parsers/rst/include/xhtml4-symbol.txt +.. _xhtml1-lat1.txt: ../../../docutils/parsers/rst/include/xhtml1-lat1.txt +.. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt +.. _xhtml1-symbol.txt: ../../../docutils/parsers/rst/include/xhtml1-symbol.txt .. -- cgit v1.2.1 From ccac3b33bd345ea21e0cbbda824f99ddcf11adb1 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 21 Nov 2005 19:50:32 +0000 Subject: updated spec to reflect that escaped colons inside of field names are now allowed; added history entry git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4092 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index d503d9054..e0cee6031 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -813,15 +813,16 @@ see `Bibliographic Fields`_ below, or the "image_" and "meta_" directives in `reStructuredText Directives`_. Field lists are mappings from field names to field bodies, modeled on -RFC822_ headers. A field name is made up of one or more letters, -numbers, whitespace, and punctuation, except colons (":"). Inline -markup is parsed in field names. Field names are case-insensitive -when further processed or transformed. The field name, along with a -single colon prefix and suffix, together form the field marker. The -field marker is followed by whitespace and the field body. The field -body may contain multiple body elements, indented relative to the -field marker. The first line after the field name marker determines -the indentation of the field body. For example:: +RFC822_ headers. A field name may consist of any characters, but +colons (":") inside of field names must be escaped with a backslash. +Inline markup is parsed in field names. Field names are +case-insensitive when further processed or transformed. The field +name, along with a single colon prefix and suffix, together form the +field marker. The field marker is followed by whitespace and the +field body. The field body may contain multiple body elements, +indented relative to the field marker. The first line after the field +name marker determines the indentation of the field body. For +example:: :Date: 2001-08-16 :Version: 1 -- cgit v1.2.1 From 118dd3d2aa36cf563590197e28830c1a905f9cd8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 8 Dec 2005 04:43:13 +0000 Subject: merged branches/s5 changes r4011:4155 into trunk/docutils git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4156 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/definitions.txt | 180 +++++++++++++++++++++++++++++++++++++++++ docs/ref/rst/directives.txt | 8 +- docs/ref/rst/substitutions.txt | 162 ------------------------------------- 3 files changed, 187 insertions(+), 163 deletions(-) create mode 100644 docs/ref/rst/definitions.txt delete mode 100644 docs/ref/rst/substitutions.txt (limited to 'docs/ref') diff --git a/docs/ref/rst/definitions.txt b/docs/ref/rst/definitions.txt new file mode 100644 index 000000000..78a2bf8da --- /dev/null +++ b/docs/ref/rst/definitions.txt @@ -0,0 +1,180 @@ +============================================ + reStructuredText Standard Definition Files +============================================ +:Author: David Goodger +:Contact: goodger@python.org +:Revision: $Revision$ +:Date: $Date$ +:Copyright: This document has been placed in the public domain. + +.. contents:: + + +This document describes standard definition files, such as sets of +substitution definitions and interpreted text roles, that can be +included in reStructuredText documents. The `"include" directive`__ +has a special syntax for these standard definition files, angle +brackets around the file name:: + + .. include:: <filename.txt> + +__ directives.html#include + +The individual data files are stored with the Docutils source code in +the "docutils" package, in the ``docutils/parsers/rst/include`` +directory. + + +Substitution Definitions +======================== + +Many of the standard definition files contain sets of `substitution +definitions`__, which can be used in documents via `substitution +references`__. For example, the copyright symbol is defined in +``isonum.txt`` as "copy":: + + .. include:: <isonum.txt> + + Copyright |copy| 2003 by John Q. Public, all rights reserved. + +__ restructuredtext.html#substitution-definitions +__ restructuredtext.html#substitution-references + +Individual substitution definitions can also be copied from definition +files and pasted into documents. This has two advantages: it removes +dependencies, and it saves processing of unused definitions. However, +multiple substitution definitions add clutter to the document. + +Substitution references require separation from the surrounding text +with whitespace or punctuation. To use a substitution without +intervening whitespace, you can use the disappearing-whitespace escape +sequence, backslash-space:: + + .. include:: isonum.txt + + Copyright |copy| 2003, BogusMegaCorp\ |trade|. + +Custom substitution definitions may use the `"unicode" directive`__. +Whitespace is ignored and removed, effectively sqeezing together the +text:: + + .. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN + .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 + .. with trademark sign + + Copyright |copy| 2003, |BogusMegaCorp (TM)|. + +__ directives.html#unicode + +In addition, the "ltrim", "rtrim", and "trim" options may be used with +the "unicode" directive to automatically trim spaces from the left, +right, or both sides (respectively) of substitution references:: + + .. |---| unicode:: U+02014 .. em dash + :trim: + + +Character Entity Sets +--------------------- + +The following files contain substitution definitions corresponding to +XML character entity sets, from the following standards: ISO 8879 & +ISO 9573-13 (combined), MathML, and XHTML1. They were generated by +the ``tools/dev/unicode2rstsubs.py`` program from the input file +unicode.xml__, which is maintained as part of the MathML 2 +Recommentation XML source. + +__ http://www.w3.org/2003/entities/xml/ + +=================== ================================================= +Entity Set File Description +=================== ================================================= +isoamsa.txt_ Added Mathematical Symbols: Arrows +isoamsb.txt_ Added Mathematical Symbols: Binary Operators +isoamsc.txt_ Added Mathematical Symbols: Delimiters +isoamsn.txt_ Added Mathematical Symbols: Negated Relations +isoamso.txt_ Added Mathematical Symbols: Ordinary +isoamsr.txt_ Added Mathematical Symbols: Relations +isobox.txt_ Box and Line Drawing +isocyr1.txt_ Russian Cyrillic +isocyr2.txt_ Non-Russian Cyrillic +isodia.txt_ Diacritical Marks +isogrk1.txt_ Greek Letters +isogrk2.txt_ Monotoniko Greek +isogrk3.txt_ Greek Symbols +isogrk4.txt_ [1]_ Alternative Greek Symbols +isolat1.txt_ Added Latin 1 +isolat2.txt_ Added Latin 2 +isomfrk.txt_ [1]_ Mathematical Fraktur +isomopf.txt_ [1]_ Mathematical Openface (Double-struck) +isomscr.txt_ [1]_ Mathematical Script +isonum.txt_ Numeric and Special Graphic +isopub.txt_ Publishing +isotech.txt_ General Technical +mmlalias.txt_ MathML aliases for entities from other sets +mmlextra.txt_ [1]_ Extra names added by MathML +xhtml1-lat1.txt_ XHTML Latin 1 +xhtml1-special.txt_ XHTML Special Characters +xhtml1-symbol.txt_ XHTML Mathematical, Greek and Symbolic Characters +=================== ================================================= + +.. [1] There are ``*-wide.txt`` variants for each of these character + entity set files, containing characters outside of the Unicode + basic multilingual plane or BMP (wide-Unicode; code points greater + than U+FFFF). Most pre-built Python distributions are "narrow" and + do not support wide-Unicode characters. Python *can* be built with + wide-Unicode support though; consult the Python build instructions + for details. + +For example, the copyright symbol is defined as the XML character +entity ``©``. The equivalent reStructuredText substitution +reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is +``|copy|``. + +.. _isoamsa.txt: ../../../docutils/parsers/rst/include/isoamsa.txt +.. _isoamsb.txt: ../../../docutils/parsers/rst/include/isoamsb.txt +.. _isoamsc.txt: ../../../docutils/parsers/rst/include/isoamsc.txt +.. _isoamsn.txt: ../../../docutils/parsers/rst/include/isoamsn.txt +.. _isoamso.txt: ../../../docutils/parsers/rst/include/isoamso.txt +.. _isoamsr.txt: ../../../docutils/parsers/rst/include/isoamsr.txt +.. _isobox.txt: ../../../docutils/parsers/rst/include/isobox.txt +.. _isocyr1.txt: ../../../docutils/parsers/rst/include/isocyr1.txt +.. _isocyr2.txt: ../../../docutils/parsers/rst/include/isocyr2.txt +.. _isodia.txt: ../../../docutils/parsers/rst/include/isodia.txt +.. _isogrk1.txt: ../../../docutils/parsers/rst/include/isogrk1.txt +.. _isogrk2.txt: ../../../docutils/parsers/rst/include/isogrk2.txt +.. _isogrk3.txt: ../../../docutils/parsers/rst/include/isogrk3.txt +.. _isogrk4.txt: ../../../docutils/parsers/rst/include/isogrk4.txt +.. _isolat1.txt: ../../../docutils/parsers/rst/include/isolat1.txt +.. _isolat2.txt: ../../../docutils/parsers/rst/include/isolat2.txt +.. _isomfrk.txt: ../../../docutils/parsers/rst/include/isomfrk.txt +.. _isomopf.txt: ../../../docutils/parsers/rst/include/isomopf.txt +.. _isomscr.txt: ../../../docutils/parsers/rst/include/isomscr.txt +.. _isonum.txt: ../../../docutils/parsers/rst/include/isonum.txt +.. _isopub.txt: ../../../docutils/parsers/rst/include/isopub.txt +.. _isotech.txt: ../../../docutils/parsers/rst/include/isotech.txt +.. _mmlalias.txt: ../../../docutils/parsers/rst/include/mmlalias.txt +.. _mmlextra.txt: ../../../docutils/parsers/rst/include/mmlextra.txt +.. _xhtml1-lat1.txt: ../../../docutils/parsers/rst/include/xhtml1-lat1.txt +.. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt +.. _xhtml1-symbol.txt: ../../../docutils/parsers/rst/include/xhtml1-symbol.txt + + +S5/HTML Definitions +=================== + +The "s5defs.txt_" standard definition file contains interpreted text +roles (classes) and other definitions for documents destined to become +`S5/HTML slide shows`_. + +.. _s5defs.txt: ../../../docutils/parsers/rst/include/s5defs.txt +.. _S5/HTML slide shows: ../../user/slide-shows.html + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 58fa324cf..12959e86d 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1065,7 +1065,7 @@ Target Footnotes :Directive Type: "target-notes" :Doctree Elements: pending, footnote, footnote_reference :Directive Arguments: None. -:Directive Options: None. +:Directive Options: Possible. :Directive Content: None. The "target-notes" directive creates a footnote for each external @@ -1074,6 +1074,12 @@ reference. For every explicit target (of the form, ``.. _target name: URL``) in the text, a footnote will be generated containing the visible URL as content. +The following option is recognized: + +``class`` : text + Set a "class" attribute value on all footnote_reference elements. + See the class_ directive below. + Footnotes ========= diff --git a/docs/ref/rst/substitutions.txt b/docs/ref/rst/substitutions.txt deleted file mode 100644 index 5ea9562f2..000000000 --- a/docs/ref/rst/substitutions.txt +++ /dev/null @@ -1,162 +0,0 @@ -======================================================== - reStructuredText Standard Substitution Definition Sets -======================================================== -:Author: David Goodger -:Contact: goodger@python.org -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -The data files described below contain sets of reStructuredText -`substitution definitions`__. They can be included in documents using -the `"include" directive's`__ special syntax for standard data files, -angle brackets around the file name:: - - .. include:: <filename.txt> - -__ restructuredtext.html#substitution-definitions -__ directives.html#include - -The definitions can then be used in documents using `substitution -references`__. For example, the copyright symbol is defined in -``isonum.txt`` as "copy":: - - .. include:: <isonum.txt> - - Copyright |copy| 2003 by John Q. Public, all rights reserved. - -__ restructuredtext.html#substitution-references - -Individual definitions can also be copied from these data files and -pasted into documents. This has two advantages: it removes -dependencies, and it saves processing of unused definitions. However, -multiple substitution definitions add clutter to the document. - -Substitution references require separation from the surrounding text -with whitespace or punctuation. To use a substitution without -intervening whitespace, you can use the disappearing-whitespace escape -sequence, backslash-space:: - - .. include:: isonum.txt - - Copyright |copy| 2003, BogusMegaCorp\ |trade|. - -Custom definitions may use the `"unicode" directive`__. Whitespace is -ignored and removed, effectively sqeezing together the text:: - - .. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - - Copyright |copy| 2003, |BogusMegaCorp (TM)|. - -__ directives.html#unicode - -In addition, the "ltrim", "rtrim", and "trim" options may be used with -the "unicode" directive to automatically trim spaces from the left, -right, or both sides (respectively) of substitution references:: - - .. |---| unicode:: U+02014 .. em dash - :trim: - -The individual data files are stored with the Docutils source code in -the "docutils" package, in the ``docutils/parsers/rst/include`` -directory. - - -Character Entity Sets -===================== - -The following files contain substitution definitions corresponding to -XML character entity sets, from the following standards: ISO 8879 & -ISO 9573-13 (combined), MathML, and XHTML1. They were generated by -the ``tools/dev/unicode2rstsubs.py`` program from the input file -unicode.xml__, which is maintained as part of the MathML 2 -Recommentation XML source. - -__ http://www.w3.org/2003/entities/xml/ - -=================== ================================================= -Entity Set File Description -=================== ================================================= -isoamsa.txt_ Added Mathematical Symbols: Arrows -isoamsb.txt_ Added Mathematical Symbols: Binary Operators -isoamsc.txt_ Added Mathematical Symbols: Delimiters -isoamsn.txt_ Added Mathematical Symbols: Negated Relations -isoamso.txt_ Added Mathematical Symbols: Ordinary -isoamsr.txt_ Added Mathematical Symbols: Relations -isobox.txt_ Box and Line Drawing -isocyr1.txt_ Russian Cyrillic -isocyr2.txt_ Non-Russian Cyrillic -isodia.txt_ Diacritical Marks -isogrk1.txt_ Greek Letters -isogrk2.txt_ Monotoniko Greek -isogrk3.txt_ Greek Symbols -isogrk4.txt_ [1]_ Alternative Greek Symbols -isolat1.txt_ Added Latin 1 -isolat2.txt_ Added Latin 2 -isomfrk.txt_ [1]_ Mathematical Fraktur -isomopf.txt_ [1]_ Mathematical Openface (Double-struck) -isomscr.txt_ [1]_ Mathematical Script -isonum.txt_ Numeric and Special Graphic -isopub.txt_ Publishing -isotech.txt_ General Technical -mmlalias.txt_ MathML aliases for entities from other sets -mmlextra.txt_ [1]_ Extra names added by MathML -xhtml1-lat1.txt_ XHTML Latin 1 -xhtml1-special.txt_ XHTML Special Characters -xhtml1-symbol.txt_ XHTML Mathematical, Greek and Symbolic Characters -=================== ================================================= - -.. [1] There are ``*-wide.txt`` variants for each of these character - entity set files, containing characters outside of the Unicode - basic multilingual plane or BMP (wide-Unicode; code points greater - than U+FFFF). Most pre-built Python distributions are "narrow" and - do not support wide-Unicode characters. Python *can* be built with - wide-Unicode support though; consult the Python build instructions - for details. - -For example, the copyright symbol is defined as the XML character -entity ``©``. The equivalent reStructuredText substitution -reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is -``|copy|``. - -.. _isoamsa.txt: ../../../docutils/parsers/rst/include/isoamsa.txt -.. _isoamsb.txt: ../../../docutils/parsers/rst/include/isoamsb.txt -.. _isoamsc.txt: ../../../docutils/parsers/rst/include/isoamsc.txt -.. _isoamsn.txt: ../../../docutils/parsers/rst/include/isoamsn.txt -.. _isoamso.txt: ../../../docutils/parsers/rst/include/isoamso.txt -.. _isoamsr.txt: ../../../docutils/parsers/rst/include/isoamsr.txt -.. _isobox.txt: ../../../docutils/parsers/rst/include/isobox.txt -.. _isocyr1.txt: ../../../docutils/parsers/rst/include/isocyr1.txt -.. _isocyr2.txt: ../../../docutils/parsers/rst/include/isocyr2.txt -.. _isodia.txt: ../../../docutils/parsers/rst/include/isodia.txt -.. _isogrk1.txt: ../../../docutils/parsers/rst/include/isogrk1.txt -.. _isogrk2.txt: ../../../docutils/parsers/rst/include/isogrk2.txt -.. _isogrk3.txt: ../../../docutils/parsers/rst/include/isogrk3.txt -.. _isogrk4.txt: ../../../docutils/parsers/rst/include/isogrk4.txt -.. _isolat1.txt: ../../../docutils/parsers/rst/include/isolat1.txt -.. _isolat2.txt: ../../../docutils/parsers/rst/include/isolat2.txt -.. _isomfrk.txt: ../../../docutils/parsers/rst/include/isomfrk.txt -.. _isomopf.txt: ../../../docutils/parsers/rst/include/isomopf.txt -.. _isomscr.txt: ../../../docutils/parsers/rst/include/isomscr.txt -.. _isonum.txt: ../../../docutils/parsers/rst/include/isonum.txt -.. _isopub.txt: ../../../docutils/parsers/rst/include/isopub.txt -.. _isotech.txt: ../../../docutils/parsers/rst/include/isotech.txt -.. _mmlalias.txt: ../../../docutils/parsers/rst/include/mmlalias.txt -.. _mmlextra.txt: ../../../docutils/parsers/rst/include/mmlextra.txt -.. _xhtml1-lat1.txt: ../../../docutils/parsers/rst/include/xhtml1-lat1.txt -.. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt -.. _xhtml1-symbol.txt: ../../../docutils/parsers/rst/include/xhtml1-symbol.txt - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: -- cgit v1.2.1 From e329a521a11f62212d4504d25cb1a3c5c76dfc18 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 12 Dec 2005 04:12:02 +0000 Subject: Added the universal.StripComments transform, the "strip_comments" setting, and the --strip-comments/--leave-comments options. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4183 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 0595175b4..54446f8dd 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -63,6 +63,8 @@ parts.SectNum "sectnum" (d/p) 710 parts.Contents "contents" (d/p), 720 peps.Contents (t/p) +universal.StripComments Reader (r) 740 + peps.PEPZero peps.Headers (t/p) 760 components.Filter "meta" (d/p) 780 -- cgit v1.2.1 From fec0a36bc5fb049147de33e97a2701b785011599 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 22 Dec 2005 23:46:04 +0000 Subject: added "Directives for Substitution Definitions" section, including docs for new "date" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4228 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 232 +++++++++++++++++++++++++------------------- 1 file changed, 134 insertions(+), 98 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 12959e86d..af88a3d4e 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1177,6 +1177,140 @@ Imagemap Non-standard element: imagemap. +----------------------------------------- + Directives for Substitution Definitions +----------------------------------------- + +The directives in this section may only be used in substitution +definitions. They may not be used directly, in standalone context. +The `image`_ directive may be used both in substitution definitions +and in the standalone context. + + +.. _replace: + +Replacement Text +================ + +:Directive Type: "replace" +:Doctree Element: Text & inline elements +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: A single paragraph; may contain inline markup. + +The "replace" directive is used to indicate replacement text for a +substitution reference. It may be used within substitution +definitions only. For example, this directive can be used to expand +abbreviations:: + + .. |reST| replace:: reStructuredText + + Yes, |reST| is a long word, so I can't blame anyone for wanting to + abbreviate it. + +As reStructuredText doesn't support nested inline markup, the only way +to create a reference with styled text is to use substitutions with +the "replace" directive:: + + I recommend you try |Python|_. + + .. |Python| replace:: Python, *the* best language around + .. _Python: http://www.python.org/ + + +.. _unicode: + +Unicode Character Codes +======================= + +:Directive Type: "unicode" +:Doctree Element: Text +:Directive Arguments: One or more, required (Unicode character codes, + optional text, and comments). +:Directive Options: Possible. +:Directive Content: None. + +The "unicode" directive converts Unicode character codes (numerical +values) to characters, and may be used in substitution definitions +only. + +The arguments, separated by spaces, can be: + +* **character codes** as + + - decimal numbers or + + - hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``, + ``u``, or ``\u`` or as XML-style hexadecimal character entities, + e.g. ``ᨫ`` + +* **text**, which is used as-is. + +Text following " .. " is a comment and is ignored. The spaces between +the arguments are ignored and thus do not appear in the output. +Hexadecimal codes are case-insensitive. + +For example, the following text:: + + Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| + all rights reserved. + + .. |copy| unicode:: 0xA9 .. copyright sign + .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 + .. with trademark sign + .. |---| unicode:: U+02014 .. em dash + :trim: + +results in: + + Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| + all rights reserved. + + .. |copy| unicode:: 0xA9 .. copyright sign + .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 + .. with trademark sign + .. |---| unicode:: U+02014 .. em dash + :trim: + +The following options are recognized: + +``ltrim`` : flag + Whitespace to the left of the substitution reference is removed. + +``rtrim`` : flag + Whitespace to the right of the substitution reference is removed. + +``trim`` : flag + Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides + of the substitution reference is removed. + + +Date +==== + +:Directive Type: "date" +:Doctree Element: Text +:Directive Arguments: One, optional (date format). +:Directive Options: None. +:Directive Content: None. + +The "date" directive generates the current local date and inserts it +into the document as text. This directive may be used in substitution +definitions only. + +The optional directive content is interpreted as the desired date +format, using the same codes as Python's time.strftime function. The +default format is "%Y-%m-%d" (ISO 8601 date), but time fields can also +be used. Examples:: + + .. |date| date:: + .. |time| date:: %H:%M + + Today's date is |date|. + + This document was generated on |date| at |time|. + + --------------- Miscellaneous --------------- @@ -1321,104 +1455,6 @@ The following options are recognized: Defaults to the document's encoding (if specified). -.. _replace: - -Replacement Text -================ - -:Directive Type: "replace" -:Doctree Element: Text & inline elements -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: A single paragraph; may contain inline markup. - -The "replace" directive is used to indicate replacement text for a -substitution reference. It may be used within substitution -definitions only. For example, this directive can be used to expand -abbreviations:: - - .. |reST| replace:: reStructuredText - - Yes, |reST| is a long word, so I can't blame anyone for wanting to - abbreviate it. - -As reStructuredText doesn't support nested inline markup, the only way -to create a reference with styled text is to use substitutions with -the "replace" directive:: - - I recommend you try |Python|_. - - .. |Python| replace:: Python, *the* best language around - .. _Python: http://www.python.org/ - - -.. _unicode: - -Unicode Character Codes -======================= - -:Directive Type: "unicode" -:Doctree Element: Text -:Directive Arguments: One or more, required (Unicode character codes, - optional text, and comments). -:Directive Options: Possible. -:Directive Content: None. - -The "unicode" directive converts Unicode character codes (numerical -values) to characters, and may be used in substitution definitions -only. - -The arguments, separated by spaces, can be: - -* **character codes** as - - - decimal numbers or - - - hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``, - ``u``, or ``\u`` or as XML-style hexadecimal character entities, - e.g. ``ᨫ`` - -* **text**, which is used as-is. - -Text following " .. " is a comment and is ignored. The spaces between -the arguments are ignored and thus do not appear in the output. -Hexadecimal codes are case-insensitive. - -For example, the following text:: - - Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| - all rights reserved. - - .. |copy| unicode:: 0xA9 .. copyright sign - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - .. |---| unicode:: U+02014 .. em dash - :trim: - -results in: - - Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| - all rights reserved. - - .. |copy| unicode:: 0xA9 .. copyright sign - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - .. |---| unicode:: U+02014 .. em dash - :trim: - -The following options are recognized: - -``ltrim`` : flag - Whitespace to the left of the substitution reference is removed. - -``rtrim`` : flag - Whitespace to the right of the substitution reference is removed. - -``trim`` : flag - Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides - of the substitution reference is removed. - - Class ===== -- cgit v1.2.1 From a4dc6c54aafa689141243e1e837dc2bc3b236939 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Dec 2005 23:48:48 +0000 Subject: Fixed bug with circular substitution definitions that put Docutils into an infinite loop. Circular substitution definitions are now detected & reported. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4233 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index e0cee6031..1445619b3 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2027,7 +2027,7 @@ Substitution definitions are indicated by an explicit markup start vertical bar, whitespace, and the definition block. Substitution text may not begin or end with whitespace. A substitution definition block contains an embedded inline-compatible directive (without the leading -".. "), such as an image_. For example:: +".. "), such as "image_" or "replace_". For example:: The |biohazard| symbol must be used on containers used to dispose of medical waste. -- cgit v1.2.1