SF.net SVN: docutils:[9613 ] trunk/docutils

Revision: 9613
          http://sourceforge.net/p/docutils/code/9613
Author:   milde
Date:     2024-04-06 13:27:52 +0000 (Sat, 06 Apr 2024)
Log Message:
-----------
Fix doctree element attribute datatype definition and description.

Local tests revealed inconsistencies and omissions in the DTD
and its documentation.

Use aliases in doctree.txt for links where the id would clash with the ids
of element sections (e.g. `document`_ -> `document <rST document_>`__).

Modified Paths:
--------------
    trunk/docutils/HISTORY.txt
    trunk/docutils/docs/ref/doctree.txt
    trunk/docutils/docs/ref/docutils.dtd
    trunk/docutils/docs/ref/rst/restructuredtext.txt
    trunk/docutils/docutils/transforms/references.py

Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt	2024-04-05 23:07:13 UTC (rev 9612)
+++ trunk/docutils/HISTORY.txt	2024-04-06 13:27:52 UTC (rev 9613)
@@ -16,8 +16,15 @@
 Changes since 0.21.rc1
 ======================
 
-...
+* docs/ref/docutils.dtd
 
+  - Reference names (``%refname.type`` and ``%refnames.type``)
+    are whitespace-normalized but **not** always downcased.
+  - The <topic> element uses the "depth" and "local" attributes to store
+    "contents" directive options when used as placeholder for a generated
+    table of contents (LaTeX writers with `use_latex_toc`_ setting).
+
+
 Release 0.21.rc1 (2024-03-26)
 =============================
 

Modified: trunk/docutils/docs/ref/doctree.txt
===================================================================
--- trunk/docutils/docs/ref/doctree.txt	2024-04-05 23:07:13 UTC (rev 9612)
+++ trunk/docutils/docs/ref/doctree.txt	2024-04-06 13:27:52 UTC (rev 9613)
@@ -1302,12 +1302,14 @@
 Examples
 --------
 
-Docinfo_ is represented in reStructuredText by a `\<field_list>`_ in a
-bibliographic context: the first visible element of a `\<document>`_,
-after any document `\<title>`_/`\<subtitle>`_.
+`Bibliographic data`_ is represented in reStructuredText by a 
+`field list <rST field list_>`__ as the first visible element of a
+`document <rST document>`__ (after optional document title and subtitle).
 The field list is transformed into a <docinfo> element and its children
-by the `frontmatter.DocInfo` transform_.  Source::
+by the `frontmatter.DocInfo`_ transform. [#abstract-dedication]_
 
+Source::
+
     Docinfo Example
     ===============
 
@@ -1352,10 +1354,15 @@
 See `\<field_list>`_ for an example in a non-bibliographic context.  Also
 see the individual examples for the various `bibliographic elements`_.
 
-.. _docinfo:
+.. [#abstract-dedication] Exceptions are the fields "abstract" and
+   "dedication" that are transformed to `\<topic>`_ elements adjacent to
+   the <docinfo>.
+
+.. _bibliographic data:
 .. _bibliographic fields: rst/restructuredtext.html#bibliographic-fields
+.. _rST document: rst/restructuredtext.html#document
+.. _rST field list: rst/restructuredtext.html#field-lists
 
-
 <doctest_block>
 ===============
 
@@ -1432,8 +1439,10 @@
 :Parents:    The <document> element has no parents.
 
 :Children:   <document> elements may contain `structural subelements`_,
-             `structural elements`_, and `body elements`_::
+             `structural elements`_, and `body elements`_
 
+             .. parsed-literal::
+
                ( (title, subtitle?)?,
                  decoration?,
                  (docinfo, transition?)?,
@@ -1712,7 +1721,7 @@
 Examples
 --------
 
-A reStructuredText `field list`_::
+A reStructuredText `field list <rST field list_>`__::
 
     :Author: Me
     :Version: 1
@@ -1748,7 +1757,6 @@
                     integer
 
 .. _directive: rst/restructuredtext.html#directives
-.. _field list: rst/restructuredtext.html#field-lists
 
 
 <field_name>
@@ -3581,6 +3589,9 @@
 `\<rubric>`_ element to get an informal heading inside a <table>
 or a <list>, or inside another <topic>.
 
+Docutils uses the <topic> element also for a generated `table of contents`_,
+and the "abstract" and "dedication" `bibliographic fields`_.
+
 Details
 -------
 
@@ -3599,7 +3610,8 @@
 
                  (title?, (%body.elements;)+)
 
-:Attributes: The <topic> element contains only the `common attributes`_.
+:Attributes: The <topic> element contains the `common attributes`_ plus
+             depth_ and local_.
 
 :Parameter Entities: The `%structure.model;`_ parameter entity
              directly includes <topic>.
@@ -3622,6 +3634,8 @@
             Body.
 
 .. _"topic" directive: rst/directives.html#topic
+.. _"contents" directive:
+.. _table of contents: rst/directives.html#table-of-contents
 
 
 <transition>
@@ -3839,7 +3853,7 @@
     ``%classnames.type;`` is used in the `classes`_ attribute.
 
 _`refname.type`
-    A normalized_ `reference name`_. Resolves to CDATA (in contrast to
+    A `reference name`_. Resolves to CDATA (in contrast to
     NMTOKENS, `reference names`_ may consist of any text).
 
     ``%refname.type;`` is used in the `name`_ and `refname`_ attributes.
@@ -3953,8 +3967,8 @@
 
 Attribute type: `CDATA`_ (str).  Default value: none (inherit).
 
-The ``align`` attribute is used in the `\<figure>`_, 
-`\<image>`_, `\<table>`_, and `\<tgroup>`_ elements 
+The ``align`` attribute is used in the `\<figure>`_,
+`\<image>`_, `\<table>`_, and `\<tgroup>`_ elements
 (via the `%align-h.att;`_ and `%align-hv.att;`_ parameter entities).
 
 
@@ -4062,7 +4076,7 @@
 interpreted as “pt” if neither a proportion nor a fixed unit is
 specified.
 
-__ 
+__
 
 .. important::
    Currently, Docutils only allows unitless integers in the ``colwidth``
@@ -4079,7 +4093,14 @@
 separating it from the `\<option_string>`_ (typically either "=" or " ")
 or the text between option arguments (typically either "," or " ").
 
+``depth``
+=========
 
+Attribute type: number_ (int). Default value: none.
+
+The ``depth`` attribute may be used in a `\<topic>`_ element generated by
+the `"contents" directive`_ to hold the value of the "depth" option.
+
 ``dupnames``
 ============
 
@@ -4150,6 +4171,15 @@
 The ``line`` attribute is used in the `\<system_message>`_ element.
 
 
+``local``
+=========
+
+Attribute type: yesorno_ (int). Default value: none.
+
+The ``local`` attribute may be used in a `\<topic>` element generated by
+the `"contents" directive`_ to hold the value of the "local" option.
+
+
 ``ltrim``
 =========
 
@@ -4199,12 +4229,16 @@
 ``name``
 =========
 
-Attribute type: `refname.type`_ (str).  Default value: none.
+Attribute type: `refname.type`_ or `NMTOKEN`_ (str).
+Default value: none.
 
-The ``name`` attribute is used in the `\<reference>`_ element.
+The ``name`` attribute in the `\<reference>`_ element accepts
+`refname.type`_ values.
+Case is preserved (but ignored when resolving reference names).
 
-The equally named attribute of the `\<meta>`_ element contains a
-"metadata name".
+The ``name`` attribute in the `\<meta>`_ element accepts `NMTOKEN`_ values.
+The output format may limit valid values to a set of keywords
+(EnumeratedType_).
 
 
 ``names``
@@ -4213,8 +4247,8 @@
 Attribute type: `refnames.type`_ (list[str]).  Default value: none.
 
 The ``names`` attribute is a space-separated list containing
-`normalized`_ `reference names`_ of an element. Whitespace inside a
-name is backslash escaped.
+`reference names`_ of an element. 
+Whitespace inside a name is backslash escaped.
 Each name in the list 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.
@@ -4229,8 +4263,6 @@
 ``names`` is one of the `common attributes`_, shared by all
 Docutils elements.
 
-.. _normalized:
-   rst/restructuredtext.html#normalized-reference-names
 .. _internal hyperlink targets:
    rst/restructuredtext.html#internal-hyperlink-targets
 .. _name option: rst/directives.html#name
@@ -4251,7 +4283,7 @@
 
 The ``refid`` attribute contains a reference to an `identifier key`_
 
-``refid`` is used by the `\<citation_reference>`_, `\<footnote_reference>`_, 
+``refid`` is used by the `\<citation_reference>`_, `\<footnote_reference>`_,
 `\<problematic>`_, `\<reference>`_, `\<target>`_, and `\<title>`_ elements
 (via the `%refid.att;`_ and `%reference.atts;`_ parameter entities).
 
@@ -4780,8 +4812,8 @@
 
 .. _transform:
 .. _transforms: ../api/transforms.html
+.. _frontmatter.DocInfo: ../api/transforms.html#docinfo
 
-
 
 ..
    Local Variables:

Modified: trunk/docutils/docs/ref/docutils.dtd
===================================================================
--- trunk/docutils/docs/ref/docutils.dtd	2024-04-05 23:07:13 UTC (rev 9612)
+++ trunk/docutils/docs/ref/docutils.dtd	2024-04-06 13:27:52 UTC (rev 9613)
@@ -57,8 +57,9 @@
 
 The CDATA type is used because a `reference name` may consist of any text.
 
-`Normalization` implies downcasing and replacing runs of whitespace with
-single space characters. -->
+"Normalization" implies replacing runs of whitespace with single space
+characters. Matching substitution references to definitions is case-sensitive
+but forgiving. Resolving other cross references ignores case. -->
 <!ENTITY % refname.type  "CDATA">
 
 <!-- A space-separated list of `reference names`.
@@ -77,7 +78,7 @@
 <!-- A reference to an `identifier key` in another element's `ids` attribute.
 
 The NMTOKEN type is used, because Docutils `identifier keys` do not use the
-``ID`` attribute type, as required by the `IDREF Validity constraint`_ -->
+``ID`` attribute type, as required by the `IDREF Validity constraint`_. -->
 <!ENTITY % idref.type  "NMTOKEN">
 
 <!-- A list of references to `identifier keys` in other elements. -->
@@ -360,7 +361,10 @@
 <!ATTLIST section %basic.atts;>
 
 <!ELEMENT topic (title?, (%body.elements;)+)>
-<!ATTLIST topic %basic.atts;>
+<!ATTLIST topic
+    %basic.atts;
+    depth %number;  #IMPLIED
+    local %yesorno; #IMPLIED>
 
 <!ELEMENT sidebar (title?, subtitle?, (%body.elements; | topic)+)>
 <!ATTLIST sidebar %basic.atts;>
@@ -468,7 +472,7 @@
 that is typeset as mathematical notation (display formula).
 -->
 <!ELEMENT math_block (#PCDATA)>
-<!ATTLIST math_block 
+<!ATTLIST math_block
     %basic.atts;
     %fixedspace.att;>
 

Modified: trunk/docutils/docs/ref/rst/restructuredtext.txt
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.txt	2024-04-05 23:07:13 UTC (rev 9612)
+++ trunk/docutils/docs/ref/rst/restructuredtext.txt	2024-04-06 13:27:52 UTC (rev 9613)
@@ -438,7 +438,7 @@
   a single space), and
 
 - case is normalized (all alphabetic characters are converted to
-  lowercase).
+  lowercase). [#case-forgiving]_
 
 For example, the following `hyperlink references`_ are equivalent::
 
@@ -457,7 +457,13 @@
 footnote, citation) may be processed and rendered differently.  Some
 care should be taken to avoid reference name conflicts.
 
+`Substitution references`_ and `substitution definitions`_ use a
+different namespace.
 
+.. [#case-forgiving] Matching `substitution references`_ to
+   `substitution definitions`_ is case-sensitive but forgiving.
+
+
 Document Structure
 ==================
 

Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py	2024-04-05 23:07:13 UTC (rev 9612)
+++ trunk/docutils/docutils/transforms/references.py	2024-04-06 13:27:52 UTC (rev 9613)
@@ -25,7 +25,7 @@
         <paragraph>
             This is a test.
 
-    PropagateTargets propagates the ids and names of the internal
+    `PropagateTargets` propagates the ids and names of the internal
     targets preceding the paragraph to the paragraph itself::
 
         <target refid="internal1">

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.



_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins