Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[9112] trunk/docutils
|
From: <mi...@us...> - 2022-07-28 10:45:40
|
Revision: 9112
http://sourceforge.net/p/docutils/code/9112
Author: milde
Date: 2022-07-28 10:45:38 +0000 (Thu, 28 Jul 2022)
Log Message:
-----------
Update directives documentation
* Clarify the admonitions documentation (fixes bug #453).
* Provide hyperlink targets (anchors) for all directive names.
(Use anonymous targets for like-named "doctree" elements.)
Modified Paths:
--------------
trunk/docutils/docs/ref/doctree.txt
trunk/docutils/docs/ref/rst/directives.txt
trunk/docutils/docutils/parsers/rst/languages/de.py
Modified: trunk/docutils/docs/ref/doctree.txt
===================================================================
--- trunk/docutils/docs/ref/doctree.txt 2022-07-19 16:00:50 UTC (rev 9111)
+++ trunk/docutils/docs/ref/doctree.txt 2022-07-28 10:45:38 UTC (rev 9112)
@@ -424,6 +424,9 @@
:Analogues:
``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.
:Processing:
Rendered distinctly (inset and/or in a box, etc.).
@@ -4505,7 +4508,8 @@
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_.
+danger_, error_, hint_, important_, note_, tip_,
+and the generic admonition_.
Details
Modified: trunk/docutils/docs/ref/rst/directives.txt
===================================================================
--- trunk/docutils/docs/ref/rst/directives.txt 2022-07-19 16:00:50 UTC (rev 9111)
+++ trunk/docutils/docs/ref/rst/directives.txt 2022-07-28 10:45:38 UTC (rev 9112)
@@ -51,16 +51,14 @@
Admonitions
-------------
-.. From Webster's Revised Unabridged Dictionary (1913) [web1913]:
- Admonition
- Gentle or friendly reproof; counseling against a fault or
- error; expression of authoritative advice; friendly caution
- or warning.
+Admonitions ("safety messages" or "hazard statements") 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,
- Syn: {Admonition}, {Reprehension}, {Reproof}.
+Docutils defines a `generic admonition`_ as well as a set of
+`specific admonitions`_.
- Usage: Admonition is prospective, and relates to moral delinquencies;
- its object is to prevent further transgression.
.. _attention:
.. _caution:
@@ -76,18 +74,23 @@
====================
:Directive Types: "attention", "caution", "danger", "error", "hint",
- "important", "note", "tip", "warning", "admonition"
-:Doctree Elements: attention, caution, danger, error, hint, important,
- note, tip, warning, admonition_, title_
+ "important", "note", "tip", "warning"
+:Doctree Elements: `attention <../doctree.html#attention>`__,
+ `caution <../doctree.html#caution>`__ ,
+ `danger <../doctree.html#danger>`__,
+ `error <../doctree.html#error>`__,
+ `hint <../doctree.html#hint>`__,
+ `important <../doctree.html#important>`__,
+ `note <../doctree.html#note>`__,
+ `tip <../doctree.html#tip>`__,
+ `warning <../doctree.html#warning>`__
+
:Directive Arguments: None.
:Directive Options: class_, name_
: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.
-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::
+Specific admontions are rendered with a title matching the admonition type.
+For example::
.. DANGER::
Beware killer rabbits!
@@ -100,18 +103,6 @@
| 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
@@ -126,11 +117,14 @@
- It includes this bullet list.
+.. _admonition:
+
Generic Admonition
==================
:Directive Type: "admonition"
-:Doctree Elements: admonition_, title_
+:Doctree Elements: `admonition <../doctree.html#admonition>`__,
+ `title <../doctree.html#title>`__
:Directive Arguments: One, required (admonition title)
:Directive Options: class_, name_
:Directive Content: Interpreted as body elements.
@@ -139,9 +133,8 @@
author desires.
The author-supplied title is also used as a `"classes"`_ 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::
+after `identifier normalization`_ and adding the prefix "admonition-".
+For example, this admonition::
.. admonition:: And, by the way...
@@ -156,8 +149,7 @@
<paragraph>
You can make up your own admonition too.
-The class_ option overrides the computed `"classes"`_ attribute
-value.
+The class_ option overrides the generated `"classes"`_ attribute value.
--------
@@ -164,7 +156,7 @@
Images
--------
-There are two image directives: "image" and "figure".
+There are two image directives: image_ and figure_.
.. attention::
@@ -212,7 +204,7 @@
=====
:Directive Type: "image"
-:Doctree Element: image_
+:Doctree Element: `image <../doctree.html#image>`__
:Directive Arguments: One, required (image URI).
:Directive Options: Possible (see below).
:Directive Content: None.
@@ -482,7 +474,6 @@
Love, Ewan.
-
.. _parsed-literal:
Parsed Literal Block
@@ -517,6 +508,7 @@
(docinfo_, transition_?)?,
`%structure.model;`_ )
+
Code
====
@@ -690,11 +682,13 @@
See Epigraph_ above for an analogous example.
+.. compound:
+
Compound Paragraph
==================
:Directive Type: "compound"
-:Doctree Element: compound_
+:Doctree Element: `compound <../doctree.html#compound>`__
:Directive Arguments: None.
:Directive Options: class_, name_
:Directive Content: Interpreted as body elements.
@@ -767,7 +761,6 @@
application-specific purposes.
-
--------
Tables
--------
@@ -783,7 +776,7 @@
=====
:Directive Type: "table"
-:Doctree Element: table_
+:Doctree Element: `table <../doctree.html#table>`__
:Directive Arguments: One, optional (table title).
:Directive Options: Possible (see below).
:Directive Content: A normal `reStructuredText table`_.
@@ -835,6 +828,7 @@
.. _reStructuredText table: restructuredtext.html#tables
.. _table_style: ../../user/config.html#table-style
+
.. _csv-table:
CSV Table
@@ -1241,19 +1235,18 @@
@@@
+.. ---------------
+ HTML-Specific
+ ---------------
----------------
- HTML-Specific
----------------
+ Imagemap
+ ========
-Imagemap
-========
+ **NOT IMPLEMENTED YET**
-**NOT IMPLEMENTED YET**
+ Non-standard element: imagemap.
-Non-standard element: imagemap.
-
-----------------------------------------
Directives for Substitution Definitions
-----------------------------------------
@@ -1266,6 +1259,7 @@
.. _substitution definitions:
.. _substitution definition: restructuredtext.html#substitution-definitions
+
.. _replace:
Replacement Text
@@ -1507,13 +1501,14 @@
text markers will be searched in the specified lines (further limiting the
included content).
-.. _raw-directive:
+.. _raw:
+
Raw Data Pass-Through
=====================
:Directive Type: "raw"
-:Doctree Element: raw_
+:Doctree Element: `raw <../doctree.html#raw>`__
:Directive Arguments: One or more, required (output format types).
:Directive Options: Possible (see below).
:Directive Content: Stored verbatim, uninterpreted. None (empty) if a
@@ -1591,7 +1586,6 @@
.. _"raw" role: roles.html#raw
-.. _classes:
Class
=====
@@ -1742,6 +1736,7 @@
.. _HTML 4.01 spec: https://www.w3.org/TR/html401/
.. _CSS1 spec: https://www.w3.org/TR/REC-CSS1
+
.. _role:
Custom Interpreted Text Roles
@@ -1879,11 +1874,13 @@
parser is "title-reference".
+.. _meta:
+
Metadata
========
:Directive Type: "meta"
-:Doctree Element: meta_
+:Doctree Element: `meta <../doctree.html#meta>`__
:Directive Arguments: None.
:Directive Options: None.
:Directive Content: Must contain a flat field list.
@@ -1955,6 +1952,8 @@
.. _bibliographic fields: restructuredtext.html#bibliographic-fields
+.. _title:
+
Metadata Document Title
=======================
@@ -1973,6 +1972,7 @@
.. _document title: restructuredtext.html#document-title
.. _"title" configuration setting: ../../user/config.html#title
+
Restructuredtext-Test-Directive
===============================
@@ -1988,6 +1988,7 @@
followed by a literal block containing the rest of the directive
block.
+
--------------
Common Options
--------------
@@ -2031,10 +2032,9 @@
.. _identifier keys: ../doctree.html#ids-type
.. _"ids": ../doctree.html#ids
.. _"names": ../doctree.html#names
-.. _admonition: ../doctree.html#admonition
.. _block_quote: ../doctree.html#block-quote
.. _caption: ../doctree.html#caption
-.. _compound: ../doctree.html#compound
+.. _classes: ../doctree.html#classes
.. _container element: ../doctree.html#container
.. _decoration: ../doctree.html#decoration
.. _figure: ../doctree.html#figure
@@ -2041,7 +2041,6 @@
.. _footnote: ../doctree.html#footnote
.. _footnote_reference: ../doctree.html#footnote-reference
.. _generated: ../doctree.html#generated
-.. _image: ../doctree.html#image
.. _inline elements: ../doctree.html#inline-elements
.. _interpreted text role: roles.html
.. _literal_block: ../doctree.html#literal-block
@@ -2049,14 +2048,10 @@
.. _length: restructuredtext.html#length-units
.. _line_block: ../doctree.html#line-block
.. _math_block: ../doctree.html#math-block
-.. _meta: ../doctree.html#meta
.. _pending: ../doctree.html#pending
.. _percentage: restructuredtext.html#percentage-units
-.. _raw: ../doctree.html#raw
.. _rubric: ../doctree.html#rubric
.. _sidebar: ../doctree.html#sidebar
-.. _table: ../doctree.html#table
-.. _title: ../doctree.html#title
.. _title attribute: ../doctree.html#title-attribute
.. _topic: ../doctree.html#topic
Modified: trunk/docutils/docutils/parsers/rst/languages/de.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/languages/de.py 2022-07-19 16:00:50 UTC (rev 9111)
+++ trunk/docutils/docutils/parsers/rst/languages/de.py 2022-07-28 10:45:38 UTC (rev 9112)
@@ -27,7 +27,7 @@
'notiz': 'note',
'tipp': 'tip',
'warnung': 'warning',
- 'ermahnung': 'admonition',
+ 'ermahnung': 'admonition', # sic! Not used in this sense in rST.
'kasten': 'sidebar',
'seitenkasten': 'sidebar', # kept for backwards compatibiltity
'seitenleiste': 'sidebar',
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
