Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[9499] trunk/docutils
|
From: <mi...@us...> - 2023-12-06 20:49:11
|
Revision: 9499
http://sourceforge.net/p/docutils/code/9499
Author: milde
Date: 2023-12-06 20:49:08 +0000 (Wed, 06 Dec 2023)
Log Message:
-----------
Documentation revision.
Use `<...>` notation for Document Tree elements
(similar to the [MDN](https://developer.mozilla.org/docs/Web/HTML)).
Format RELEASE NOTES for more consistency.
Less section nesting in "config" doc.
The `<h6>` section headings came out in smaller font size that the main text
with the standard firefox and chromium style sheets.
Small fixes and additions.
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/index.txt
trunk/docutils/docs/ref/doctree.txt
trunk/docutils/docs/ref/rst/restructuredtext.txt
trunk/docutils/docs/ref/rst/roles.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docs/user/html.txt
trunk/docutils/docs/user/latex.txt
trunk/docutils/docs/user/todo-lists.txt
trunk/docutils/docs/user/tools.txt
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2023-12-06 20:48:52 UTC (rev 9498)
+++ trunk/docutils/RELEASE-NOTES.txt 2023-12-06 20:49:08 UTC (rev 9499)
@@ -161,18 +161,20 @@
Release 0.21 (unpublished)
==========================
-* Drop support for Python 3.7 and 3.8.
+* General:
-* Provide ``rst2*`` "console_scripts" `entry points`_
- (without the ``.py`` extension) instead of installing the
- ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_
+ - Drop support for Python 3.7 and 3.8.
- Exceptions: ``rstpep2html.py`` and ``rst2odt_prepstyles.py``:
+ - Provide ``rst2*`` "console_scripts" `entry points`_
+ (without the ``.py`` extension) instead of installing the
+ ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_
- - Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview. [#]_
- - Use ``python -m docutils.writers.odf_odt.prepstyles``
- to `strip the page size`__ from an ODT writer stylesheet.
+ Exceptions: ``rstpep2html.py`` and ``rst2odt_prepstyles.py``:
+ - Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview. [#]_
+ - Use ``python -m docutils.writers.odf_odt.prepstyles``
+ to `strip the page size`__ from an ODT writer stylesheet.
+
__ docs/user/odt.html#page-size
.. [#] Some Linux distributions already use the short names.
@@ -179,20 +181,15 @@
.. [#] The final rendering is done by a Sphinx-based build system
(cf. :PEP:`676`).
-* Simpler and more secure `input encoding`_ default behaviour:
+* reStructuredText:
- Do not use the locale encoding as fallback if Python is started in
- `UTF-8 mode`_. Stop using "latin1" as second fallback.
+ - Use the same CSV format for the ``:header:`` option and the main data
+ of the "csv-table_" directive.
- Remove BOM (U+FEFF ZWNBSP at start of data) only if the `input_encoding`_
- configuration setting is None, '', 'utf-8-sig', 'utf-16', or 'utf-32'.
- Do not remove other ZWNBSPs.
+ - New option "loading" for the `"image" directive`_.
+ Sets the new attribute loading__ of the <image> doctree element.
-* New attribute loading__ for the Docutils doctree node: <image> storing
- the new "loading" option of the `"image" directive`_.
-
__ docs/ref/doctree.html#loading
- .. _"image" directive: docs/ref/rst/directives.html#image
* Configuration changes:
@@ -199,28 +196,51 @@
- New configuration setting root-prefix_.
Configurable root directory for included files.
- .. _root-prefix: docs/user/config.html#root-prefix
+ - Simpler and more secure `input encoding`_ default behaviour:
-* "html5" writer:
- Stop setting the "footnote-reference" class value for footnote references.
- You can use the CSS selector ``[role="doc-noteref"]``
- since Docutils 0.18 (see minimal.css for examples).
+ Do not use the locale encoding as fallback if Python is started in
+ `UTF-8 mode`_. Stop using "latin1" as second fallback.
-* Use the same CSV format for the ``:header:`` option and the main data
- of the "csv-table_" directive.
+ Remove BOM (U+FEFF ZWNBSP at start of data) only if the `input_encoding`_
+ configuration setting is None, '', 'utf-8-sig', 'utf-16', or 'utf-32'.
+ Do not remove other ZWNBSPs.
+* Output changes:
+
+ HTML5:
+ Stop setting the "footnote-reference" class value for footnote
+ references. Use the CSS selector ``[role="doc-noteref"]``
+ (works since Docutils 0.18, see minimal.css for examples).
+
* Removed objects:
- - `nodes.reprunicode` and `nodes.ensure_str()`
- (not required with Python 3),
- `utils.Reporter.set_conditions()` (obsolete)
- `core.Publisher.setup_option_parser()` (internal, obsolete)
+ `docutils.nodes.reprunicode`, `docutils.nodes.ensure_str()`
+ Python 2 compatibility hacks
+ `docutils.utils.Reporter.set_conditions()`
+ obsolete
+ `docutils.core.Publisher.setup_option_parser()`
+ internal, obsolete
- - File ``install.py``. See README.txt__ for alternatives.
+* New files:
+ ``docutils/writers/html5_polyglot/italic-field-names.css``
+ Alternative style for Docutils field-lists.
+
+* Removed files:
+
+ ``install.py``, ``setup.py``
+ Metadata is now stored in ``pyproject.toml``,
+ supported by pip_ since version 19.0 (2019-01-22).
+ See README__ for installation alternatives.
+
+ __ README.html#installation
+
+* Bugfixes and improvements (see HISTORY_).
+
.. _input encoding: docs/api/publisher.html#encodings
.. _csv-table: docs/ref/rst/directives.html#csv-table
-__ README.html#installation
+.. _"image" directive: docs/ref/rst/directives.html#image
+.. _root-prefix: docs/user/config.html#root-prefix
Release 0.20.1 (2023-05-17)
Modified: trunk/docutils/docs/index.txt
===================================================================
--- trunk/docutils/docs/index.txt 2023-12-06 20:48:52 UTC (rev 9498)
+++ trunk/docutils/docs/index.txt 2023-12-06 20:49:08 UTC (rev 9499)
@@ -14,7 +14,7 @@
.. _Docutils distribution: https://docutils.sourceforge.io/#download
.. header::
- Docutils_ | Overview | About__ | Users__ | Reference__ | Developers__
+ Docutils_ | Overview | About__ | Users__ | Reference__ | API_ | Developers__
.. _Docutils: https://docutils.sourceforge.io/
__ `project fundamentals`_
@@ -26,70 +26,64 @@
.. contents::
-Project Fundamentals
-====================
+Docutils Stakeholders
+=====================
-These files are for all `Docutils stakeholders`_. They are kept at the
-top level of the Docutils project directory.
+can be categorized in several groups:
+ .. class:: details
-.. class:: narrow run-in
+ End-users
+ users of reStructuredText and the Docutils tools.
+ Although some are developers (e.g. Python developers utilizing
+ reStructuredText for docstrings in their source), many are not.
+ Client-developers
+ developers using Docutils as a library,
+ programmers developing *with* Docutils.
+ Component-developers:
+ those who implement application-specific components,
+ directives, and/or roles, separately from Docutils.
+ Core-developers
+ developers of the Docutils codebase and participants
+ in the Docutils project community.
+ Re-implementers
+ developers of alternate implementations of Docutils.
-:README_: Project overview: quick-start, requirements,
- installation, and usage.
-:COPYING_: Conditions for Docutils redistribution, with links to
- licenses.
-:FAQ_: Docutils Frequently Asked Questions. If you have a
- question or issue, there's a good chance it's already
- answered here.
-:BUGS_: A list of known bugs, and how to report a bug.
-:RELEASE-NOTES_: Summary of the major changes in recent releases and
- notice of future incompatible changes.
-:HISTORY_: Detailed change history log.
-:THANKS_: Acknowledgements.
-
-.. _README: ../README.html
-.. _BUGS: ../BUGS.html
-.. _COPYING: ../COPYING.html
-.. _Docutils FAQ:
-.. _FAQ: ../FAQ.html
-.. _RELEASE-NOTES: ../RELEASE-NOTES.html
-.. _HISTORY: ../HISTORY.html
-.. _THANKS: ../THANKS.html
-
-
-.. _docutils stakeholders:
.. class:: details
-Docutils Stakeholders …
- can be categorized in several groups:
+There's a lot of overlap between these groups.
+ Most (perhaps all) developers are also end-users.
+ Core-developers are also client-developers, and may also
+ be component-developers in other projects.
+ Component-developers are also client-developers.
- End-users:
- users of reStructuredText and the Docutils tools.
- Although some are developers (e.g. Python developers utilizing
- reStructuredText for docstrings in their source), many are not.
- Client-developers:
- developers using Docutils as a library,
- programmers developing *with* Docutils.
+Project Fundamentals
+====================
- Component-developers:
- those who implement application-specific components,
- directives, and/or roles, separately from Docutils.
+These files are for all `Docutils stakeholders`_. They are kept at the
+top level of the Docutils project directory.
- Core-developers:
- developers of the Docutils codebase and participants
- in the Docutils project community.
+`README <../README.html>`_:
+ Project overview: quick-start, requirements,
+ installation, and usage.
- Re-implementers:
- developers of alternate implementations of Docutils.
+`COPYING <../COPYING.html>`_:
+ Conditions for Docutils redistribution,
+ with links to licenses.
+`FAQ <../FAQ.html>`_:
+ Docutils Frequently Asked Questions. If you have a question or issue,
+ there's a good chance it's already answered here.
+`BUGS <../BUGS.html>`_:
+ A list of known bugs, and how to report a bug.
+`RELEASE-NOTES <../RELEASE-NOTES.html>`_:
+ Summary of the major changes in recent releases and
+ notice of future incompatible changes.
+`HISTORY <../HISTORY.html>`_:
+ Detailed change history log.
+`THANKS <../THANKS.html>`_:
+ Acknowledgements.
- There's a lot of overlap between these groups. Most (perhaps all)
- core-developers, component-developers, client-developers, and
- re-implementers are also end-users. Core-developers are also
- client-developers, and may also be component-developers in other
- projects. Component-developers are also client-developers.
-
.. _user:
Introductory & Tutorial Material for End-Users
@@ -201,8 +195,7 @@
Instructions for Developers
===========================
-:Security: `Deploying Docutils Securely <howto/security.html>`__
-
+* `Deploying Docutils Securely <howto/security.html>`__
* `Inside A Docutils Command-Line Front-End Tool <howto/cmdline-tool.html>`__
* `Runtime Settings Processing <dev/runtime-settings-processing.html>`__
* `Writing HTML (CSS) Stylesheets for Docutils
Modified: trunk/docutils/docs/ref/doctree.txt
===================================================================
--- trunk/docutils/docs/ref/doctree.txt 2023-12-06 20:48:52 UTC (rev 9498)
+++ trunk/docutils/docs/ref/doctree.txt 2023-12-06 20:49:08 UTC (rev 9499)
@@ -79,8 +79,9 @@
+---------+
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.
+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
@@ -95,8 +96,16 @@
occur at the same level.
.. _HTML: https://www.w3.org/TR/html52/
+.. _XMLSpec: https://www.w3.org/XML/1998/06/xmlspec-report.htm
.. _DocBook: https://tdg.docbook.org/tdg/5.1/
-.. _XMLSpec: https://www.w3.org/XML/1998/06/xmlspec-report.htm
+.. _DocBook <caution>: https://tdg.docbook.org/tdg/5.1/caution.html
+.. _DocBook <footnote>: https://tdg.docbook.org/tdg/5.1/footnote.html
+.. _DocBook <footnoteref>: https://tdg.docbook.org/tdg/5.1/footnoteref.html
+.. _DocBook <imagedata>: https://tdg.docbook.org/tdg/5.1/imagedata
+.. _DocBook <important>: https://tdg.docbook.org/tdg/5.1/important.html
+.. _DocBook <note>: https://tdg.docbook.org/tdg/5.1/note.html
+.. _DocBook <tip>: https://tdg.docbook.org/tdg/5.1/tip.html
+.. _DocBook <warning>: https://tdg.docbook.org/tdg/5.1/warning.html
Structural Elements
@@ -107,7 +116,7 @@
elements or further structural elements. Structural elements can only
be child elements of other structural elements.
-Category members: document_, section_, topic_, sidebar_
+Category members: `\<document>`_, `\<section>`_, `\<topic>`_, `\<sidebar>`_
Structural Subelements
@@ -114,33 +123,36 @@
----------------------
Structural subelements are child elements of structural elements.
-Simple structural subelements (title_, subtitle_) contain text
-data; the others are compound and do not directly contain text data.
+Simple structural subelements (`\<title>`_, `\<subtitle>`_) contain text
+data; the others are compound elements and do not directly contain text
+data.
-Category members: title_, subtitle_, decoration_, docinfo_, meta_,
-transition_
+Category members: `\<title>`_, `\<subtitle>`_, `\<decoration>`_,
+`\<docinfo>`_, `\<meta>`_, `\<transition>`_
Bibliographic Elements
``````````````````````
-The docinfo_ element is an optional child of document_. It groups
-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.
+The `\<docinfo>`_ element is an optional child of `\<document>`_.
+It groups 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_
+Category members: `\<address>`_, `\<author>`_, `\<authors>`_,
+`\<contact>`_, `\<copyright>`_, `\<date>`_, `\<field>`_,
+`\<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.
+The `\<decoration>`_ element is also an optional child of `\<document>`_.
+It groups together elements used to generate page headers and footers.
-Category members: footer_, header_
+Category members: `\<footer>`_, `\<header>`_
Body Elements
@@ -147,18 +159,23 @@
=============
Body elements are contained within structural elements and compound
-body elements. There are two subcategories of body elements: simple
-and compound.
+body elements. There are two subcategories of body elements: simple__
+and compound__.
-Category members: admonition_, attention_, block_quote_, bullet_list_,
-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_
+Category members: `\<admonition>`_, `\<attention>`_, `\<block_quote>`_,
+`\<bullet_list>`_, `\<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
+__ compound body elements
+
Simple Body Elements
--------------------
@@ -166,9 +183,9 @@
that contain text data may also contain inline elements. Such
elements therefore have a "mixed content model".
-Category members: comment_, doctest_block_, image_, literal_block_,
-math_block_, paragraph_, pending_, raw_, rubric_, substitution_definition_,
-target_
+Category members: `\<comment>`_, `\<doctest_block>`_, `\<image>`_,
+`\<literal_block>`_, `\<math_block>`_, `\<paragraph>`_, `\<pending>`_,
+`\<raw>`_, `\<rubric>`_, `\<substitution_definition>`_, `\<target>`_
Compound Body Elements
@@ -177,31 +194,34 @@
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_, container_, danger_, definition_list_,
-enumerated_list_, error_, field_list_, figure_, footnote_, hint_,
-important_, line_block, note_, option_list_, system_message_, table_,
-tip_, warning_
+Category members: `\<admonition>`_, `\<attention>`_, `\<block_quote>`_,
+`\<bullet_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>`_
Body Subelements
````````````````
-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
+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 (simple): attribution_, caption_, classifier_,
-colspec_, field_name_, label_, line_, option_argument_,
-option_string_, term_
+Category members (simple): `\<attribution>`_, `\<caption>`_,
+`\<classifier>`_, `\<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_,
-option_, option_group_, option_list_item_, row_, tbody_, tgroup_,
-thead_
+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
@@ -211,10 +231,12 @@
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_, inline_, literal_,
-math_, problematic_, reference_, strong_, subscript_,
-substitution_reference_, superscript_, target_, title_reference_, raw_
+Category members: `\<abbreviation>`_, `\<acronym>`_,
+`\<citation_reference>`_, `\<emphasis>`_, `\<footnote_reference>`_,
+`\<generated>`_, `\<image>`_, `\<inline>`_, `\<literal>`_,
+`\<math>`_, `\<problematic>`_, `\<raw>`_, `\<reference>`_,
+`\<strong>`_, `\<subscript>`_, `\<substitution_reference>`_,
+`\<superscript>`_, `\<target>`_, `\<title_reference>`_
-------------------
@@ -285,107 +307,79 @@
its writing.
-``abbreviation``
-================
+<abbreviation>
+==============
-The ``abbreviation`` element is an inline element used to represent an
-abbreviation being used in the document. An example of an abbreviation is 'St'
-being used instead of 'Street'.
+The <abbreviation> element is an inline element used to represent an
+abbreviation being used in the document.
+An example of an abbreviation is 'St' being used instead of 'Street'.
-
Details
-------
-:Category:
- `Inline Elements`_
+:Category: `Inline Elements`_
+:Analogues: <abbreviation> is analogous to the HTML <abbr> element.
+:Parents: All elements employing the `%inline.elements;`_ parameter
+ entity in their content models may contain <abbreviation>.
+:Children: <abbreviation> elements may contain text data plus `inline
+ elements`_ (`%text.model;`_).
+:Attributes: The <abbreviation> element contains only the `common attributes`_.
-:Analogues:
- ``abbreviation`` is analogous to the HTML "abbr" element.
-
-:Parents:
- All elements employing the `%inline.elements;`_ parameter entity in their
- content models may contain ``abbreviation``.
-
-:Children:
- ``abbreviation`` elements may contain text data plus `inline elements`_.
-
- .. parsed-literal::
-
- `%text.model;`_
-
-:Attributes:
- The ``abbreviation`` element contains only the `common attributes`_.
-
-
Examples
--------
-The ``abbreviation`` element is not exposed in default restructured text. It
-can only be accessed through custom roles.
+The reStructuredText `abbreviation role`_ creates an <abbreviation> element::
-Pseudo-XML_ example from a custom `:abbr:` role::
+ :abbreviation:`St` is a common abbreviation for "street".
+Pseudo-XML_ fragment from simple parsing::
+
<paragraph>
- <abbreviation explanation="Street">
+ <abbreviation>
St
is a common abbreviation for "street".
+.. _abbreviation role: rst/roles.html#abbreviation
-``acronym``
-===========
+<acronym>
+=========
+
`To be completed`_.
-``address``
+<address>
===========
-The ``address`` element holds the surface mailing address information
-for the author (individual or group) of the document, or a third-party
+The <address> element holds the surface mailing address information
+for the author(s) (individual or group) of the document, or a third-party
contact address. Its structure is identical to that of the
-literal_block_ element: whitespace is significant, especially
+`\<literal_block>`_ element: whitespace is significant, especially
newlines.
-
Details
-------
-:Category:
- `Bibliographic Elements`_
+:Category: `Bibliographic Elements`_
+:Analogues: <address> is analogous to the DocBook_ <address> element.
+:Processing: 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>`_.
+:Parents: The following elements may contain <address>:
+ `\<docinfo>`_, `\<authors>`_.
+:Children: <address> elements contain text data plus `inline elements`_
+ (`%text.model;`_).
+:Attributes: The <address> element contains the `common attributes`_
+ plus `xml:space`_.
+:Parameter Entities: The `%bibliographic.elements;`_ parameter entity
+ directly includes <address>.
-:Analogues:
- ``address`` is analogous to the DocBook "address" element.
-
-:Processing:
- 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_.
-
-:Parents:
- The following elements may contain ``address``: docinfo_, authors_
-
-:Children:
- ``address`` elements contain text data plus `inline elements`_.
-
- .. parsed-literal::
-
- `%text.model;`_
-
-:Attributes:
- The ``address`` element contains the `common attributes`_ plus
- `xml:space`_.
-
-:Parameter Entities:
- The `%bibliographic.elements;`_ parameter entity directly includes
- ``address``.
-
-
Examples
--------
-reStructuredText_ source::
+In reStructuredText, "address" is one of the registered
+`bibliographic fields`_::
Document Title
==============
@@ -393,7 +387,7 @@
:Address: 123 Example Ave.
Example, EX
-Complete pseudo-XML_ result after parsing and applying transforms::
+Complete pseudo-XML_ result after parsing and applying transforms_::
<document ids="document-title" names="document title">
<title>
@@ -403,121 +397,97 @@
123 Example Ave.
Example, EX
-See docinfo_ for a more complete example, including processing
+See `\<docinfo>`_ for a more complete example, including processing
context.
-``admonition``
-==============
+<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_.
+The <admonition> element is a generic, titled *admonition*,
+a distinctive and self-contained notice.
+See also the specific admonition elements
+`\<attention>`_ `\<caution>`_, `\<danger>`_, `\<error>`_, `\<hint>`_,
+`\<important>`_, `\<note>`_, `\<tip>`_, and `\<warning>`_.
Details
-------
-:Category:
- `Compound Body Elements`_
+:Category: `Compound Body Elements`_
-:Analogues:
- ``admonition`` has no direct analogues in common DTDs. It can be
- emulated with primitives and type effects.
+:Analogues: The generic <admonition> has no direct analogues in common DTDs.
+ It can be emulated with primitives and type effects.
+ The specific admonitions `\<caution>`_, `\<note>`_,
+ `\<tip>`_, and `\<warning>`_ are analogous to the
+ respective DocBook_ elements.
- The specific admonitions caution_, note_, tip_, and warning_
- are analogous to the respective DocBook elements.
+:Processing: Rendered distinctly (inset and/or in a box, etc.).
-:Processing:
- Rendered distinctly (inset and/or in a box, etc.).
+:Parents: All elements employing the `%body.elements;`_
+ or `%structure.model;`_ parameter entities in
+ their content models may contain <admonition>.
-: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`_.
-:Children:
- ``admonition`` elements begin with a title_ and may contain one or
- more `body elements`_. ::
+:Attributes: The <admonition> element contains only the `common attributes`_.
- (title_, (`%body.elements;`_)+)
+:Parameter Entities: The `%body.elements;`_ parameter entity directly
+ includes <admonition>. The `%structure.model;`_
+ parameter entity indirectly includes <admonition>.
-:Attributes:
- The ``admonition`` element contains only the `common attributes`_.
-
-:Parameter Entities:
- The `%body.elements;`_ parameter entity directly includes
- ``admonition``. The `%structure.model;`_ parameter entity
- indirectly includes ``admonition``.
-
-
Examples
--------
-reStructuredText source::
+The reStructuredText `"admonition" directive`_ creates a generic
+<admonition> element::
- .. admonition:: And, by the way...
+ .. admonition:: By the way...
You can make up your own admonition too.
Pseudo-XML_ fragment from simple parsing::
- <admonition class="admonition-and-by-the-way">
+ <admonition class="admonition-by-the-way">
<title>
- And, by the way...
+ By the way...
<paragraph>
You can make up your own admonition too.
+.. _"admonition" directive: rst/directives.html#admonition
-``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_, and the generic admonition_.
+<attention>
+===========
+The <attention> element is an *admonition*, a distinctive and
+self-contained notice. See also the generic `\<admonition>`_
+and the other specific admonition elements `\<caution>`_,
+`\<danger>`_, `\<error>`_, `\<hint>`_, `\<important>`_, `\<note>`_,
+`\<tip>`_, and `\<warning>`_.
Details
-------
-:Category:
- `Compound Body Elements`_
+:Category: `Compound 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).
+: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`_.
+:Attributes: The <attention> element contains only the `common attributes`_.
+:Parameter Entities: The `%body.elements;`_ parameter entity
+ directly includes <attention>. The `%structure.model;`_
+ parameter entity indirectly includes <attention>.
-: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).
-
-
-: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`_.
-
- .. parsed-literal::
-
- (`%body.elements;`_)+
-
-:Attributes:
- The ``attention`` element contains only the `common attributes`_.
-
-:Parameter Entities:
- The `%body.elements;`_ parameter entity directly includes
- ``attention``. The `%structure.model;`_ parameter entity
- indirectly includes ``attention``.
-
-
Examples
--------
-reStructuredText source::
+A reStructuredText `"attention" directive`_::
.. Attention:: All your base are belong to us.
@@ -527,53 +497,40 @@
<paragraph>
All your base are belong to us.
+.. _"attention" directive: rst/directives.html#attention
-``attribution``
-===============
+<attribution>
+=============
+
`To be completed`_.
-``author``
-==========
+<author>
+========
-The ``author`` element holds the name of the author of the document.
+The <author> element holds the name of the author (or one of the authors)
+of the document.
-
Details
-------
-:Category:
- `Bibliographic Elements`_
+:Category: `Bibliographic Elements`_
+:Analogues: <author> is analogous to the DocBook_ <author> element.
+:Processing: See `\<docinfo>`_.
+:Parents: The following elements may contain <author>:
+ `\<docinfo>`_, `\<authors>`_.
+:Children: <author> elements may contain text data plus `inline elements`_
+ (`%text.model;`_).
+:Attributes: The <author> element contains only the `common attributes`_.
+:Parameter Entities: The `%bibliographic.elements;`_ parameter entity
+ directly includes <author>.
-:Analogues:
- ``author`` is analogous to the DocBook "author" element.
-
-:Processing:
- See docinfo_.
-
-:Parents:
- The following elements may contain ``author``: docinfo_, authors_
-
-:Children:
- ``author`` elements may contain text data plus `inline elements`_.
-
- .. parsed-literal::
-
- `%text.model;`_
-
-:Attributes:
- The ``author`` element contains only the `common attributes`_.
-
-:Parameter Entities:
- The `%bibliographic.elements;`_ parameter entity directly includes
- ``author``.
-
-
Examples
--------
-reStructuredText_ source::
+In reStructuredText, "author" is one of the registered
+`bibliographic fields`_::
Document Title
==============
@@ -580,7 +537,7 @@
:Author: J. Random Hacker
-Complete pseudo-XML_ result after parsing and applying transforms::
+Complete pseudo-XML_ result after parsing and applying transforms_::
<document ids="document-title" names="document title">
<title>
@@ -589,50 +546,36 @@
<author>
J. Random Hacker
-See docinfo_ for a more complete example, including processing
+See `\<docinfo>`_ for a more complete example, including processing
context.
-``authors``
-===========
+<authors>
+=========
-The ``authors`` element is a container for author information for
+The <authors> element is a container for author information for
documents with multiple authors.
-
Details
-------
-:Category:
- `Bibliographic Elements`_
+:Category: `Bibliographic Elements`_
+:Analogues: <authors> is analogous to the DocBook_ <authors> element.
+:Processing: See `\<docinfo>`_.
+:Parents: Only the `\<docinfo>`_ element contains <authors>.
+:Children: <authors> elements may contain the following elements:
+ `\<author>`_, `\<organization>`_, `\<address>`_, `\<contact>`_::
-:Analogues:
- ``authors`` is analogous to the DocBook "authors" element.
+ ((author, organization?, address?, contact?)+)
+:Attributes: The <authors> element contains only the `common attributes`_.
+:Parameter Entities: The `%bibliographic.elements;`_ parameter entity
+ directly includes <authors>.
-:Processing:
- See docinfo_.
-
-:Parents:
- Only the docinfo_ element contains ``authors``.
-
-:Children:
- ``authors`` elements may contain the following elements: author_,
- organization_, address_, contact_::
-
- ((author, organization?, address?, contact?)+)
-
-:Attributes:
- The ``authors`` element contains only the `common attributes`_.
-
-:Parameter Entities:
- The `%bibliographic.elements;`_ parameter entity directly includes
- ``authors``.
-
-
Examples
--------
-reStructuredText_ source::
+In reStructuredText, "authors" is one of the registered
+`bibliographic fields`_::
Document Title
==============
@@ -639,7 +582,7 @@
:Authors: J. Random Hacker; Jane Doe
-Complete pseudo-XML_ result after parsing and applying transforms::
+Complete pseudo-XML_ result after parsing and applying transforms_::
<document ids="document-title" names="document title">
<title>
@@ -652,61 +595,43 @@
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.
+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
+See `\<docinfo>`_ for a more complete example, including processing
context.
-``block_quote``
-===============
+<block_quote>
+=============
-The ``block_quote`` element is used for quotations set off from the
+The <block_quote> element is used for quotations set off from the
main text (standalone).
-
Details
-------
-:Category:
- `Compound Body Elements`_
+:Category: `Compound 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.
+:Parents: All elements employing the `%body.elements;`_
+ or `%structure.model;`_ parameter entities in their
+ content models may contain <block_quote>.
+:Children: <block_quote> elements contain `body elements`_
+ followed by an optional `\<attribution>`_ element.
+:Attributes: The <block_quote> element contains only the `common attributes`_.
+:Parameter Entities: The `%body.elements;`_ parameter entity
+ directly includes <block_quote>. The `%structure.model;`_
+ parameter entity indirectly includes <block_quote>.
-: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.
-
-:Parents:
- All elements employing the `%body.elements;`_ or
- `%structure.model;`_ parameter entities in their content models
- may contain ``block_quote``.
-
-:Children:
- ``block_quote`` elements contain `body elements`_ followed by an
- optional attribution_ element.
-
- .. parsed-literal::
-
- ((`%body.elements;`_)+, attribution?)
-
-:Attributes:
- The ``block_quote`` element contains only the `common attributes`_.
-
-:Parameter Entities:
- The `%body.elements;`_ parameter entity directly includes
- ``block_quote``. The `%structure.model;`_ parameter entity
- indirectly includes ``block_quote``.
-
-
Examples
--------
-reStructuredText source::
+In reStructuredText, an indented text block without preceding markup
+is a `block quote`_::
As a great palaeontologist once said,
@@ -724,61 +649,45 @@
<attribution>
Anne Elk (Miss)
+.. _block quote: rst/restructuredtext.html#block-quotes
-``bullet_list``
-===============
-The ``bullet_list`` element contains list_item_ elements which are
+<bullet_list>
+=============
+
+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`_
+:Category: `Compound Body Elements`_
+:Analogues: <bullet_list> is analogous to the HTML<ul> element [#]_
+ and to the DocBook_ <itemizedlist> element.
+:Processing: Each list item should begin a new vertical block,
+ prefaced by a bullet/dingbat.
+: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.
+:Attributes: The <bullet_list> element contains the `common attributes`_
+ plus bullet_.
+:Parameter Entities: The `%body.elements;`_ parameter entity directly includes
+ <bullet_list>. The `%structure.model;`_ parameter entity
+ indirectly includes <bullet_list>.
-: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"
- 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.
+.. [#] 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.
-: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::
-
- (list_item_+)
-
-:Attributes:
- The ``bullet_list`` element contains the `common attributes`_
- plus bullet_.
-
- ``bullet`` is used to record the style of bullet from the input
- 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
- ``bullet_list``. The `%structure.model;`_ parameter entity
- indirectly includes ``bullet_list``.
-
-
Examples
--------
-reStructuredText_ source::
+A reStructuredText `bullet list`_::
- Item 1, paragraph 1.
@@ -798,64 +707,46 @@
<paragraph>
Item 2.
-See list_item_ for another example.
+See `\<list_item>`_ for another example.
+.. _bullet list: rst/restructuredtext.html#bullet-lists
-``caption``
-===========
+<caption>
+=========
+
`To be completed`_.
-``caution``
-===========
+<caution>
+=========
-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_, and the generic admonition_.
+The <caution> element is an *admonition*, a distinctive and
+self-contained notice. See also the generic `\<admonition>`_ and the
+other specific admonition elements `\<attention>`_, `\<danger>`_,
+`\<error>`_, `\<hint>`_, `\<important>`_, `\<note>`_, `\<tip>`_, and
+`\<warning>`_.
-
Details
-------
-:Category:
- `Compound Body Elements`_
+:Category: `Compound 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).
+: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`_.
+:Attributes: The <caution> element contains only the `common attributes`_.
+:Parameter Entities: The `%body.elements;`_ parameter entity
+ directly includes <caution>. The `%structure.model;`_
+ parameter entity indirectly includes <caution>.
-: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).
-
-.. _DocBook "caution": https://tdg.docbook.org/tdg/5.1/caution.html
-
-: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`_.
-
- .. parsed-literal::
-
- (`%body.elements;`_)+
-
-:Attributes:
- The ``caution`` element contains only the `common attributes`_.
-
-:Parameter Entities:
- The `%body.elements;`_ parameter entity directly includes
- ``caution``. The `%structure.model;`_ parameter entity
- indirectly includes ``caution``.
-
-
Examples
--------
-reStructuredText source::
+A reStructuredText `"caution" directive`_::
.. Caution:: Don't take any wooden nickels.
@@ -865,58 +756,44 @@
<paragraph>
Don't take any wooden nickels.
+.. _"caution" directive: rst/directives.html#caution
-``citation``
-============
+<citation>
+==========
+
`To be completed`_.
-``citation_reference``
-======================
+<citation_reference>
+====================
`To be completed`_.
-``classifier``
-==============
+<classifier>
+============
-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.
+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)
+:Category: `Body Subelements`_ (simple)
+:Analogues: <classifier> has no direct analogues in common DTDs.
+ It can be emulated with primitives or type effects.
+:Processing: See `\<definition_list_item>`_.
+:Parents: Only the `\<definition_list_item>`_ element contains <classifier>.
+:Children: <classifier> elements may contain text data plus
+ `inline elements`_ (`%text.model;`_).
+:Attributes: The <classifier> element contains only the `common attributes`_.
-:Analogues:
- ``classifier`` has no direct analogues in common DTDs. It can be
- emulated with primitives or type effects.
-
-:Processing:
- See definition_list_item_.
-
-:Parents:
- Only the definition_list_item_ element contains ``classifier``.
-
-:Children:
- ``classifier`` elements may contain text data plus `inline elements`_.
-
- .. parsed-literal::
-
- `%text.model;`_
-
-:Attributes:
- The ``classifier`` element contains only the `common attributes`_.
-
-
Examples
--------
-Here is a hypothetical data dictionary. reStructuredText_ source::
+A reStructuredText `definition list`_ with classifiers::
name : string
Customer name.
@@ -944,114 +821,84 @@
Temporary index variable.
-``colspec``
-===========
+<colspec>
+=========
-Specifications for a column in a table_.
+Specifications for a column in a `\<table>`_.
-
Details
-------
-:Category:
- `Body Subelements`_ (simple)
+:Category: `Body Subelements`_ (simple)
+:Analogues: <colspec> is based on the [exchange-table-model]_
+ and analogous to the DocBook_ <colspec> element.
+:Processing: The <colspec> element contains layout information
+ for the parent `\<table>`_.
+:Parents: Only the `\<tgroup>`_ element contains <colspec>.
+:Children: <colspec> is an empty element and has no children.
+:Attributes: The <colspec> element contains the optional "colnum", "colname",
+ "colwidth", "colsep", "rowsep", "align", "char", and
+ "charoff" attributes defined in the exchange-table-model_
+ plus the `common attributes`_ and `stub`_.
-:Analogues:
- ``colspec`` is based on the [exchange-table-model]_ and
- analogous to the DocBook "colspec" element.
+ Docutils uses only colwidth_ and stub_.
-:Processing:
- The ``colspec`` element contains layout information for the parent
- table_.
+ .. attention::
+ In contrast to the definition in the exchange-table-model_,
+ unitless values of the "colwidth" are interpreted as
+ proportional values, not fixed values with unit "pt".
-:Parents:
- Only the tgroup_ element contains ``colspec``.
+ .. The reference implementation `html4css2` converts
+ column widths values to percentages.
-:Children:
- ``colspec`` is an empty element and has no children.
+ Future versions of Docutils may use the standard form
+ ``number*``, e.g., “5*” for 5 times the proportion.
-:Attributes:
- The ``colspec`` element contains the optional "colnum", "colname",
- "colwidth", "colsep", "rowsep", "align", "char", and "charoff"
- attributes defined in the exchange-table-model_ plus the
- `common attributes`_ and `stub`_.
-
- Docutils uses only colwidth_ and stub_.
-
- .. attention::
-
- In contrast to the definition in the exchange-table-model_,
- unitless values of the "colwidth" are interpreted as proportional
- values, not fixed values with unit "pt".
-
- .. The reference implementation `html4css2` converts column
- widths values to percentages.
-
- Future versions of Docutils may use the standard form
- ``number*``, e.g., “5*” for 5 times the proportion.
-
Examples
--------
-See table_.
+See `\<table>`_.
-``comment``
-===========
+<comment>
+=========
`To be completed`_.
-``compound``
-============
+<compound>
+==========
`To be completed`_.
-``contact``
-===========
+<contact>
+=========
-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.
+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`_
+:Category: `Bibliographic Elements`_
+:Analogues: <contact> is analogous to the DocBook_ <email> element.
+ The HTML <address> element serves a similar purpose.
+:Processing: See `\<docinfo>`_.
+:Parents: The following elements may contain <contact>:
+ `\<docinfo>`_, `\<authors>`_.
+:Children: <contact> elements may contain text data
+ plus `inline elements`_ (`%text.model;`_).
+:Attributes: The <contact> element contains only the `common attributes`_.
+:Parameter Entities: The `%bibliographic.elements;`_ parameter entity
+ directly includes <contact>.
-:Analogues:
- ``contact`` is analogous to the DocBook "email" element. The HTML
- "address" element serves a similar purpose.
-
-:Processing:
- See docinfo_.
-
-:Parents:
- The following elements may contain ``contact``: docinfo_, authors_
-
-:Children:
- ``contact`` elements may contain text data plus `inline
- elements`_.
-
- .. parsed-literal::
-
- `%text.model;`_
-
-:Attributes:
- The ``contact`` element contains only the `common attributes`_.
-
-:Parameter Entities:
- The `%bibliographic.elements;`_ parameter entity directly includes
- ``contact``.
-
-
Examples
--------
-reStructuredText_ source::
+In reStructuredText, "contact" is one of the registered
+`bibliographic fields`_::
Document Title
==============
@@ -1058,7 +905,7 @@
:Contact: jr...@ex...
-Complete pseudo-XML_ result after parsing and applying transforms::
+Complete pseudo-XML_ result after parsing and applying transforms_::
<document ids="document-title" names="document title">
<title>
@@ -1068,57 +915,40 @@
<reference refuri="mailto:jr...@ex...">
jr...@ex...
-See docinfo_ for a more complete example, including processing
+See `\<docinfo>`_ for a more complete example, including processing
context.
-``container``
-=============
+<container>
+===========
`To be completed`_.
-``copyright``
-=============
+<copyright>
+===========
-The ``copyright`` element contains the document's copyright statement.
+The <copyright> element contains the document's copyright statement.
Details
-------
-:Category:
- `Bibliographic Elements`_
+:Category: `Bibliographic Elements`_
+:Analogues: <copyright> is analogous to the DocBook_ <copyright> element.
+:Processing: See `\<docinfo>`_.
+:Parents: Only the `\<docinfo>`_ element contains <copyright>.
+:Children: <copyright> elements may contain text data plus
+ `inline elements`_ (`%text.model;`_).
+:Attributes: The <copyright> element contains only the `common attributes`_.
+:Parameter Entities: The `%bibliographic.elements;`_ parameter entity
+ directly includes <copyright>.
-:Analogues:
- ``copyright`` is analogous to the DocBook "copyright" element.
-
-:Processing:
- See docinfo_.
-
-:Parents:
- Only the docinfo_ element contains ``copyright``.
-
-:Children:
- ``copyright`` elements may contain text data plus `inline
- elements`_.
-
- .. parsed-literal::
-
- `%text.model;`_
-
-:Attributes:
- The ``copyright`` element contains only the `common attributes`_.
-
-:Parameter Entities:
- The `%bibliographic.elements;`_ parameter entity directly includes
- ``copyright``.
-
-
Examples
--------
-reStructuredText_ source::
+In reStructuredText, "copyright" is one of the registered
+`bibliographic fields`_::
Document Title
==============
@@ -1125,7 +955,7 @@
:Copyright: This document has been placed in the public domain.
-Complete pseudo-XML_ result after parsing and applying transforms::
+Complete pseudo-XML_ result after parsing and applying transforms_::
<document ids="document-title" names="document title">
<title>
@@ -1134,58 +964,40 @@
<copyright>
This document has been placed in the public domain.
-See docinfo_ for a more complete example, including processing
-context.
+See `\<docinfo>`_ for a more complete example,
+including processing context.
-``danger``
-==========
+<danger>
+========
-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_, and the generic admonition_.
+The <danger> element is an *admonition*, a distinctive and
+self-contained notice. See also the generic `\<admonition>`_
+and the other specific admonition elements `\<attention>`_,
+`\<caution>`_, `\<error>`_, `\<hint>`_, `\<important>`_,
+`\<note>`_, `\<tip>`_, and `\<warning>`_.
-
Details
-------
-:Category:
- `Compound Body Elements`_
+:Category: `Compound 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).
+: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`_.
+:Attributes: The <danger> element contains only the `common attributes`_.
+:Parameter Entities: The `%body.elements;`_ parameter entity
+ directly includes <danger>. The `%structure.model;`_
+ parameter entity indirectly includes <danger>.
-: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).
-
-: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`_.
-
- .. parsed-literal::
-
- (`%body.elements;`_)+
-
-:Attributes:
- The ``danger`` element contains only the `common attributes`_.
-
-:Parameter Entities:
- The `%body.elements;`_ parameter entity directly includes
- ``danger``. The `%structure.model;`_ parameter entity
- indirectly includes ``danger``.
-
-
Examples
--------
-reStructuredText source::
+A reStructuredText `"danger" directive`_::
.. DANGER:: Mad scientist at work!
@@ -1195,48 +1007,33 @@
<paragraph>
Mad scientist at work!
+.. _"danger" directive: rst/directives.html#danger
-``date``
-========
-The ``date`` element contains the date of publication, release, or
+<date>
+======
+
+The <date> element contains the date of publication, release, or
last modification of the document.
-
Details
-------
-:Category:
- `Bibliographic Elements`_
+:Category: `Bibliographic Elements`_
+:Analogues: <date> is analogous to the DocBook_ <date> element.
+:Processing: Often used with the RCS/CVS keyword "Date". See `\<docinfo>`_.
+:Parents: Only the `\<docinfo>`_ element contains <date>.
+:Children: <date> elements may contain text data plus `inline elements`_
+ (`%text.model;`_).
+:Attributes: The <date> element contains only the `common attributes`_.
+:Parameter Entities: The `%bibliographic.elements;`_ parameter entity
+ directly includes <date>.
-:Analogues:
- ``date`` is analogous to the DocBook "date" element.
-
-:Processing:
- Often used with the RCS/CVS keyword "Date". See docinfo_.
-
-:Parents:
- Only the docinfo_ element contains ``date``.
-
-:Children:
- ``date`` elements may contain text data plus `inline elements`_.
-
- .. parsed-literal::
-
- `%text.model;`_
-
-:Attributes:
- The ``date`` element contains only the `common attributes`_.
-
-:Parameter Entities:
- The `%bibliographic.elements;`_ parameter entity directly includes
- ``date``.
-
-
Examples
--------
-reStructuredText_ source::
+In reStructuredText, "date" is one of the registered
+`bibliographic fields`_::
Document Title
==============
@@ -1243,7 +1040,7 @@
:Date: 2002-08-20
-Complete pseudo-XML_ result after parsing and applying transforms::
+Complete pseudo-XML_ result after parsing and applying transforms_::
<document ids="document-title" names="document title">
<title>
@@ -1252,158 +1049,93 @@
<date>
2002-08-20
-See docinfo_ for a more complete example, including processing
-context.
+See `\<docinfo>`_ for a more complete example,
+including processing context.
-``decoration``
-==============
+<decoration>
+============
-The ``decoration`` element is a container for header_ and footer_
+The <decoration> element is a container for `\<header>`_ and `\<footer>`_
elements and potential future extensions. These elements are used for
notes, time/datestamp, processing information, etc.
-
Details
-------
-:Category:
- `Structural Subelements`_
+:Category: `Structural Subelements`_
+:Analogues: There are no direct analogies to <decoration> in HTML or
+ in DocBook.
+:Processing: See the individual `decorative elements`_.
+:Parents: Only the `\<document>`_ element contains <decoration>.
+:Children: <decoration> elements may contain the `decorative elements`_
+ `\<header>`_ and/or `\<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`_.
-: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.
-
-:Processing:
- See the individual `decorative elements`_.
-
-:Parents:
- Only the document_ element contains ``decoration``.
-
-:Children:
- ``decoration`` elements may contain `decorative elements`_.
-
- .. 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`_.
-
-
Examples
--------
+See `\<header>`_ and `\<footer>`_.
-reStructuredText_ source::
- A paragraph.
+<definition>
+============
-Complete pseudo-XML_ result after parsing and applying transforms,
-assuming that the datestamp command-line option or configuration
-setting has been supplied::
+The <definition> element is a container for the body elements
+used to define a `\<term>`_ in a `\<definition_list>`_.
- <document>
- <decoration>
- <footer>
- <paragraph>
- Generated on: 2002-08-20.
- <paragraph>
- A paragraph.
-
-
-``definition``
-==============
-
-The ``definition`` element is a container for the body elements used
-to define a term_ in a definition_list_.
-
-
Details
-------
-:Category:
- `Body Subelements`_ (compound)
+:Category: `Body Subelements`_ (compound)
+:Analogues: <definition> is analogous to the HTML <dd> element
+ and to the DocBook_ <listitem> element
+ (inside a <variablelistentry> element).
+:Processing: See `\<definition_list_ite...
[truncated message content] |
