SF.net SVN: docutils:[9747 ] trunk/docutils
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9747
http://sourceforge.net/p/docutils/code/9747
Author: milde
Date: 2024-06-07 12:48:23 +0000 (Fri, 07 Jun 2024)
Log Message:
-----------
Allow multiple `<term>` elements in a `<definition_list_item>`.
Fixes feature-request #60 where this is requested for a Sphinx extension.
There is currently no corresponding rST syntax, definition list items with
multiple terms can be generated programatically or by the XML parser.
Add an XML test sample, validated with
xmllint --dtdvalid ../../docs/ref/docutils.dtd multiple-term-definition.xml
and test cases.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/ref/doctree.txt
trunk/docutils/docs/ref/docutils.dtd
trunk/docutils/docutils/nodes.py
trunk/docutils/test/test_writers/test_html5_polyglot_parts.py
trunk/docutils/test/test_writers/test_latex2e_misc.py
Added Paths:
-----------
trunk/docutils/test/data/multiple-term-definition.xml
Property Changed:
----------------
trunk/docutils/test/test_writers/test_html5_polyglot_parts.py
trunk/docutils/test/test_writers/test_latex2e_misc.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2024-06-06 14:03:57 UTC (rev 9746)
+++ trunk/docutils/HISTORY.txt 2024-06-07 12:48:23 UTC (rev 9747)
@@ -22,6 +22,11 @@
- Add tox.ini to pyproject.toml to be in sdist (bug #486).
- Fix license issue (bug #487).
+* docs/ref/docutils.dtd
+
+ - Allow multiple <term> elements in a <definition_list_item>.
+ Fixes feature-request #60
+
* docutils/nodes.py
- Raise TypeError if the "rawsource" argument in `Element.__init__()`
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2024-06-06 14:03:57 UTC (rev 9746)
+++ trunk/docutils/RELEASE-NOTES.txt 2024-06-07 12:48:23 UTC (rev 9747)
@@ -48,12 +48,6 @@
Document Tree / Docutils DTD
----------------------------
-* Allow multiple <term> elements in a <definition_list_item>
- in Docutils 0.22 (cf. `feature-requests:60`__).
- Third-party writers may need adaption.
-
- __ https://sourceforge.net/p/docutils/feature-requests/60/
-
* Do not lowercase reference names in the `refname attribute`_
(matching hyperlinks, footnotes, and citations remains case insensitive),
and drop the ``name`` attribute from <reference> nodes
@@ -212,8 +206,30 @@
Release 0.22b.dev (unpublished)
===============================
-.
+* Document Tree / Docutils DTD
+ - Allow multiple <term> elements in a <definition_list_item__>.
+ (Third-party writers may need adaption.)
+
+ - New method `Element.validate()`: Raise `nodes.ValidationError` if the
+ element does not comply with the `Docutils Document Model`_.
+ Provisional.
+
+ __ docs/ref/doctree.html#definition-list-item
+
+* New parser for `Docutils XML`_ (e.g., the output of the "xml" writer).
+ Provisional.
+
+ Try ``docutils --parser=xml test/data/multiple-term-definition.xml``
+ or use the :parser: option of the `"include" directive`_ to include
+ an XML file in a rST document.
+
+* Bugfixes and improvements (see HISTORY_).
+
+.. _Docutils Document Model:
+.. _Docutils XML: docs/ref/doctree.html
+
+
Release 0.21.2 (2024-04-23)
===========================
@@ -986,7 +1002,7 @@
Internationalization:
-* Added lithuanian mappings.
+* Added Lithuanian mappings.
Components:
Modified: trunk/docutils/docs/ref/doctree.txt
===================================================================
--- trunk/docutils/docs/ref/doctree.txt 2024-06-06 14:03:57 UTC (rev 9746)
+++ trunk/docutils/docs/ref/doctree.txt 2024-06-07 12:48:23 UTC (rev 9747)
@@ -1296,8 +1296,8 @@
<definition_list_item>
======================
-The <definition_list_item> element contains a single
-`\<term>`_/`\<definition>`_ pair (with optional `\<classifier>`_).
+A wrapper for a set of terms (with optional classifiers) and the
+associated definition in a `\<definition_list>`_.
:Category: `Body Subelements`_ (compound)
@@ -1304,7 +1304,7 @@
:Analogues: <definition_list_item> is analogous to the
DocBook_ <variablelistentry> element.
-:Processing: The optional `\<classifier>`_ can be rendered differently
+:Processing: The optional `\<classifier>`_\ s can be rendered differently
from the `\<term>`_. They should be separated visually,
typically by spaces plus a colon or dash.
@@ -1312,11 +1312,14 @@
<definition_list_item>.
:Children: <definition_list_item> elements each contain
- a single `\<term>`_, an optional `\<classifier>`_,
+ one or more `\<term>`_ elements,
+ zero or more `\<classifier>`_ elements,
and a `\<definition>`_::
- (term, classifier?, definition)
+ ((term, classifier*)+, definition)
+ Changed in Docutils 0.22: allow multiple terms.
+
:Attributes: The <definition_list_item> element contains only the
`common attributes`_.
Modified: trunk/docutils/docs/ref/docutils.dtd
===================================================================
--- trunk/docutils/docs/ref/docutils.dtd 2024-06-06 14:03:57 UTC (rev 9746)
+++ trunk/docutils/docs/ref/docutils.dtd 2024-06-07 12:48:23 UTC (rev 9747)
@@ -399,7 +399,7 @@
<!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;>
Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py 2024-06-06 14:03:57 UTC (rev 9746)
+++ trunk/docutils/docutils/nodes.py 2024-06-07 12:48:23 UTC (rev 9747)
@@ -2023,9 +2023,9 @@
class definition_list_item(Part, Element):
- content_model = ( # (term, classifier*, definition)
+ content_model = ( # ((term, classifier*)+, definition)
(term, '.'),
- (classifier, '*'),
+ ((classifier, term), '*'),
(definition, '.'))
Added: trunk/docutils/test/data/multiple-term-definition.xml
===================================================================
--- trunk/docutils/test/data/multiple-term-definition.xml (rev 0)
+++ trunk/docutils/test/data/multiple-term-definition.xml 2024-06-07 12:48:23 UTC (rev 9747)
@@ -0,0 +1,31 @@
+<!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML" "http://docutils.sourceforge.net/docs/ref/docutils.dtd">
+<document source="test data">
+ <definition_list>
+ <definition_list_item>
+ <term>New in Docutils 0.22</term>
+ <definition>
+ <paragraph>A definition list item may contain several
+ terms with optional classifier(s).</paragraph>
+ <paragraph>However, there is currently no corresponding
+ reStructuredText syntax.</paragraph>
+ </definition>
+ </definition_list_item>
+ <definition_list_item>
+ <term>term 2a</term>
+ <term>term 2b</term>
+ <definition>
+ <paragraph>definition 2</paragraph>
+ </definition>
+ </definition_list_item>
+ <definition_list_item>
+ <term>term 3a</term>
+ <classifier>classifier 3a</classifier>
+ <classifier>classifier 3aa</classifier>
+ <term>term 3b</term>
+ <classifier>classifier 3b</classifier>
+ <definition>
+ <paragraph>definition 3</paragraph>
+ </definition>
+ </definition_list_item>
+ </definition_list>
+</document>
Property changes on: trunk/docutils/test/data/multiple-term-definition.xml
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:keywords
## -0,0 +1 ##
+Author Date Id Revision
\ No newline at end of property
Modified: trunk/docutils/test/test_writers/test_html5_polyglot_parts.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_polyglot_parts.py 2024-06-06 14:03:57 UTC (rev 9746)
+++ trunk/docutils/test/test_writers/test_html5_polyglot_parts.py 2024-06-07 12:48:23 UTC (rev 9747)
@@ -13,7 +13,6 @@
"""
from pathlib import Path
-import os
import re
import sys
import unittest
@@ -35,8 +34,10 @@
# pygments output changed in version 2.14
with_pygments = False
-ROOT_PREFIX = (Path(__file__).parent.parent/'functional'/'input').as_posix()
-DATA_ROOT = os.path.abspath(os.path.join(__file__, '..', '..', 'data'))
+# TEST_ROOT is ./test/ from the docutils root
+TEST_ROOT = Path(__file__).parents[1]
+DATA_ROOT = TEST_ROOT / 'data'
+ROOT_PREFIX = (TEST_ROOT / 'functional/input').as_posix()
# Pillow/PIL is optional:
if PIL:
@@ -540,6 +541,28 @@
<p>No caption nor legend.</p>
""",
}],
+[f"""\
+.. include:: {DATA_ROOT}/multiple-term-definition.xml
+ :parser: xml
+""",
+{'fragment': """\
+<dl>
+<dt>New in Docutils 0.22</dt>
+<dd><p>A definition list item may contain several
+terms with optional classifier(s).</p>
+<p>However, there is currently no corresponding
+reStructuredText syntax.</p>
+</dd>
+<dt>term 2a</dt>
+<dt>term 2b</dt>
+<dd><p>definition 2</p>
+</dd>
+<dt>term 3a<span class="classifier">classifier 3a</span><span class="classifier">classifier 3aa</span><dt>term 3b<span class="classifier">classifier 3b</span></dt>
+<dd><p>definition 3</p>
+</dd>
+</dl>
+""",
+}],
])
Property changes on: trunk/docutils/test/test_writers/test_html5_polyglot_parts.py
___________________________________________________________________
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Modified: trunk/docutils/test/test_writers/test_latex2e_misc.py
===================================================================
--- trunk/docutils/test/test_writers/test_latex2e_misc.py 2024-06-06 14:03:57 UTC (rev 9746)
+++ trunk/docutils/test/test_writers/test_latex2e_misc.py 2024-06-07 12:48:23 UTC (rev 9747)
@@ -16,11 +16,23 @@
Miscellaneous LaTeX writer tests.
"""
+from pathlib import Path
+import sys
import unittest
+
+if __name__ == '__main__':
+ # prepend the "docutils root" to the Python library path
+ # so we import the local `docutils` package.
+ sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
from docutils import core
-contents_test_input = """\
+# TEST_ROOT is ./test/ from the docutils root
+TEST_ROOT = Path(__file__).parents[1]
+DATA_ROOT = TEST_ROOT / 'data'
+
+sample_toc = """\
.. contents:: TOC
foo
@@ -31,13 +43,38 @@
"""
+sample_multiterm = f"""\
+.. include:: {DATA_ROOT}/multiple-term-definition.xml
+ :parser: xml
+"""
+expected_multiterm = """
+\\begin{description}
+\\item[{New in Docutils 0.22}] \n\
+A definition list item may contain several
+terms with optional classifier(s).
+However, there is currently no corresponding
+reStructuredText syntax.
+
+\\item[{term 2a}] \n\
+\\item[{term 2b}] \n\
+definition 2
+
+\\item[{term 3a}] (\\textbf{classifier 3a})
+(\\textbf{classifier 3aa})
+\\item[{term 3b}] (\\textbf{classifier 3b})
+definition 3
+\\end{description}
+"""
+
+
class PublishTestCase(unittest.TestCase):
+ maxDiff = None
settings = {'_disable_config': True,
# avoid latex writer future warnings:
'use_latex_citations': False,
- 'legacy_column_widths': True,
+ 'legacy_column_widths': False,
}
def test_publish_from_doctree(self):
@@ -48,7 +85,7 @@
settings = self.settings.copy()
settings['output_encoding'] = 'unicode'
settings['warning_stream'] = '' # don't warn for missing ToC details
- doctree = core.publish_doctree(contents_test_input,
+ doctree = core.publish_doctree(sample_toc,
settings_overrides=settings)
result = core.publish_from_doctree(doctree,
writer_name='latex',
@@ -59,7 +96,7 @@
def test_publish_parts(self):
"""Check for the presence of documented parts.
"""
- parts = core.publish_parts(contents_test_input,
+ parts = core.publish_parts(sample_multiterm,
writer_name='latex',
settings_overrides=self.settings)
documented_parts = [
@@ -83,6 +120,7 @@
'whole'
]
self.assertEqual(documented_parts, sorted(parts.keys()))
+ self.assertEqual(expected_multiterm, parts['body'])
class WarningsTestCase(unittest.TestCase):
Property changes on: trunk/docutils/test/test_writers/test_latex2e_misc.py
___________________________________________________________________
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
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