HTML5: Support details disclosure elements

Items of a definition list with class argument "details" are
converted to `details disclosure elements`.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@8783 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

9 files changed, 160 insertions, 76 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 6b83f2fb3..2d7824a92 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -76,10 +76,13 @@ Changes Since 0.17.1
 
   - Removed attribute ``HTMLTranslator.topic_classes``
 
+  - Items of a definition list with class argument "details" are
+    converted to `details disclosure elements` (not with HTML4).
+
 * docutils/writers/html4css1/__init__.py:
 
-  - Overwrite methods using semantic tags and roles to keep backwards
-    compatibility.
+  - Overwrite methods in _html_base.HTMLTranslator that use HTM5 tags.
+    
 
 * docutils/writers/latex2e/__init__.py
 
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt
index 9bba9f818..ec0d11bdf 100644
--- a/docutils/RELEASE-NOTES.txt
+++ b/docutils/RELEASE-NOTES.txt
@@ -22,9 +22,6 @@ Future changes
 
 * `html5` writer:
 
-  - Use <summary> and <details> tags for term and definition of a
-    definition list with class value "details".
-
   - Do not longer set the "footnote-reference" class value for footnote
     references. Since 0.18, you can use the CSS selector
     ``[role="doc-noteref"]`` instead of ``.footnote-reference``
@@ -94,6 +91,9 @@ Release 0.18.dev
     Use class value "backrefs" instead of "fn-backref" for a span of
     back-references.
 
+    Items of a definition list with class argument "details" are
+    converted to `details disclosure elements`_.
+
   LaTeX:
      `legacy_class_functions`_ setting default changed to "False":
      admonitions are now environments.
@@ -119,6 +119,8 @@ __ docs/ref/doctree.html#meta
    docs/ref/rst/directives.html#identifier-normalization
 .. _id_prefix: docs/user/config.html#id-prefix
 .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
+.. _details disclosure elements:
+   https://www.w3.org/TR/html52/interactive-elements.html#the-details-element
 
 
 Release 0.17.1 (2021-04-16)
diff --git a/docutils/docutils/writers/_html_base.py b/docutils/docutils/writers/_html_base.py
index d536b4d33..3070b646c 100644
--- a/docutils/docutils/writers/_html_base.py
+++ b/docutils/docutils/writers/_html_base.py
@@ -727,24 +727,36 @@ class HTMLTranslator(nodes.NodeVisitor):
         pass
 
     def visit_definition(self, node):
-        self.body.append('</dt>\n')
-        self.body.append(self.starttag(node, 'dd', ''))
+        if "details" in node.parent.parent['classes']:
+            self.body.append('</summary>\n')
+        else:
+            self.body.append('</dt>\n')
+            self.body.append(self.starttag(node, 'dd', ''))
 
     def depart_definition(self, node):
-        self.body.append('</dd>\n')
+        if "details" not in node.parent.parent['classes']:
+            self.body.append('</dd>\n')
 
     def visit_definition_list(self, node):
-        classes = ['simple'] if self.is_compactable(node) else []
-        self.body.append(self.starttag(node, 'dl', classes=classes))
+        if "details" not in node['classes']:
+            classes = ['simple'] if self.is_compactable(node) else []
+            self.body.append(self.starttag(node, 'dl', classes=classes))
 
     def depart_definition_list(self, node):
-        self.body.append('</dl>\n')
+        if "details" not in node['classes']:
+            self.body.append('</dl>\n')
 
+    # Use a "details" disclosure element if parent has "class" arg "details".
     def visit_definition_list_item(self, node):
-        pass
+        if "details" in node.parent['classes']:
+            atts = {}
+            if "open" in node.parent['classes']:
+                atts['open'] = 'open'
+            self.body.append(self.starttag(node, 'details', **atts))
 
     def depart_definition_list_item(self, node):
-        pass
+        if "details" in node.parent['classes']:
+            self.body.append('</details>\n')
 
     def visit_description(self, node):
         self.body.append(self.starttag(node, 'dd', ''))
@@ -1567,10 +1579,13 @@ class HTMLTranslator(nodes.NodeVisitor):
         self.body.append('</tbody>\n')
 
     def visit_term(self, node):
-        # The parent node (definition_list_item) is omitted in HTML.
-        self.body.append(self.starttag(node, 'dt', '',
-                                       classes=node.parent['classes'],
-                                       ids=node.parent['ids']))
+        if "details" in node.parent.parent['classes']:
+            self.body.append(self.starttag(node, 'summary', ''))
+        else:
+            # The parent node (definition_list_item) is omitted in HTML.
+            self.body.append(self.starttag(node, 'dt', '',
+                                           classes=node.parent['classes'],
+                                           ids=node.parent['ids']))
 
     def depart_term(self, node):
         # Leave the end tag to `self.visit_definition()`,
diff --git a/docutils/docutils/writers/html4css1/__init__.py b/docutils/docutils/writers/html4css1/__init__.py
index 275144906..f41341498 100644
--- a/docutils/docutils/writers/html4css1/__init__.py
+++ b/docutils/docutils/writers/html4css1/__init__.py
@@ -292,7 +292,7 @@ class HTMLTranslator(writers._html_base.HTMLTranslator):
     def depart_compound(self, node):
         self.body.append('</div>\n')
 
-    # ersatz for first/last pseudo-classes
+    # ersatz for first/last pseudo-classes, no special handling of "details"
     def visit_definition(self, node):
         self.body.append('</dt>\n')
         self.body.append(self.starttag(node, 'dd', ''))
@@ -308,6 +308,13 @@ class HTMLTranslator(writers._html_base.HTMLTranslator):
     def depart_definition_list(self, node):
         self.body.append('</dl>\n')
 
+    # no special handling of "details"
+    def visit_definition_list_item(self, node):
+        pass
+
+    def depart_definition_list_item(self, node):
+        pass
+
     # use a table for description lists
     def visit_description(self, node):
         self.body.append(self.starttag(node, 'td', ''))
@@ -870,6 +877,15 @@ class HTMLTranslator(writers._html_base.HTMLTranslator):
     def depart_thead(self, node):
         self.body.append('</thead>\n')
 
+    # no special handling of "details" in definition list
+    def visit_term(self, node):
+        self.body.append(self.starttag(node, 'dt', '',
+                                       classes=node.parent['classes'],
+                                       ids=node.parent['ids']))
+
+    def depart_term(self, node):
+        pass
+
 
 class SimpleListChecker(writers._html_base.SimpleListChecker):
 
diff --git a/docutils/docutils/writers/html5_polyglot/minimal.css b/docutils/docutils/writers/html5_polyglot/minimal.css
index 98f899e46..28f2f06ae 100644
--- a/docutils/docutils/writers/html5_polyglot/minimal.css
+++ b/docutils/docutils/writers/html5_polyglot/minimal.css
@@ -75,6 +75,7 @@ span.problematic {
 /* Nested Paragraphs */
 p:first-child { margin-top: 0; }
 p:last-child { margin-bottom: 0; }
+details > p:last-child { margin-bottom: 1em; }
 
 /* Table of Contents */
 .contents ul.auto-toc { /* section numbers present */
@@ -265,7 +266,7 @@ footer { border-top: 1px solid black; }
 
 /* Images are block-level by default in Docutils */
 /* New HTML5 block elements: set display for older browsers */
-img, header, section, footer, aside, nav, main, article, figure, video {
+img, header, footer, main, aside, nav, section, figure, video, details {
   display: block;
 }
 /* inline images */
diff --git a/docutils/docutils/writers/html5_polyglot/plain.css b/docutils/docutils/writers/html5_polyglot/plain.css
index 1a5ce3d1f..8d525cc62 100644
--- a/docutils/docutils/writers/html5_polyglot/plain.css
+++ b/docutils/docutils/writers/html5_polyglot/plain.css
@@ -80,7 +80,8 @@ table {
   margin-bottom: 0.5em;
 }
 
-h1, h2, h3, h4, h5, h6, dd {
+h1, h2, h3, h4, h5, h6,
+dd, details > p:last-child {
   margin-bottom: 0.5em;
 }
 
@@ -142,6 +143,10 @@ div.dedication p.topic-title {
   font-style: normal;
 }
 
+/* disclosures */
+details { padding-left: 1em; }
+summary { margin-left: -1em; }
+
 /* Text Blocks */
 /* =========== */
 
diff --git a/docutils/docutils/writers/html5_polyglot/responsive.css b/docutils/docutils/writers/html5_polyglot/responsive.css
index e5ec95a29..21153202e 100644
--- a/docutils/docutils/writers/html5_polyglot/responsive.css
+++ b/docutils/docutils/writers/html5_polyglot/responsive.css
@@ -55,7 +55,7 @@ table {
   margin-bottom: 0.5em;
 }
 h1, h2, h3, h4, h5, h6,
-dl > dd {
+dl > dd, details > p:last-child {
   margin-bottom: 0.5em;
 }
 
@@ -165,6 +165,10 @@ dd > ol:first-child {
   clear: left;
 }
 
+/* disclosures */
+details { padding-left: 1em; }
+summary { margin-left: -1em; }
+
 /* Footnotes and Citations */
 .footnote {
   font-size: small;
diff --git a/docutils/test/functional/expected/standalone_rst_html5.html b/docutils/test/functional/expected/standalone_rst_html5.html
index 9b95c17c1..d27d1573f 100644
--- a/docutils/test/functional/expected/standalone_rst_html5.html
+++ b/docutils/test/functional/expected/standalone_rst_html5.html
@@ -148,16 +148,17 @@ They are transformed from section titles after parsing. -->
 <li><p><a class="reference internal" href="#styling-with-class-arguments" id="toc-entry-45"><span class="sectnum">3.2</span> Styling with Class Arguments</a></p>
 <ul class="auto-toc">
 <li><p><a class="reference internal" href="#description-lists" id="toc-entry-46"><span class="sectnum">3.2.1</span> Description Lists</a></p></li>
-<li><p><a class="reference internal" href="#field-list-variants" id="toc-entry-47"><span class="sectnum">3.2.2</span> Field List Variants</a></p></li>
-<li><p><a class="reference internal" href="#table-variants" id="toc-entry-48"><span class="sectnum">3.2.3</span> Table Variants</a></p></li>
-<li><p><a class="reference internal" href="#numbered-figures" id="toc-entry-49"><span class="sectnum">3.2.4</span> Numbered Figures</a></p></li>
+<li><p><a class="reference internal" href="#details-disclosure-elements" id="toc-entry-47"><span class="sectnum">3.2.2</span> Details disclosure elements</a></p></li>
+<li><p><a class="reference internal" href="#field-list-variants" id="toc-entry-48"><span class="sectnum">3.2.3</span> Field List Variants</a></p></li>
+<li><p><a class="reference internal" href="#table-variants" id="toc-entry-49"><span class="sectnum">3.2.4</span> Table Variants</a></p></li>
+<li><p><a class="reference internal" href="#numbered-figures" id="toc-entry-50"><span class="sectnum">3.2.5</span> Numbered Figures</a></p></li>
 </ul>
 </li>
-<li><p><a class="reference internal" href="#text-level-semantics" id="toc-entry-50"><span class="sectnum">3.3</span> Text-Level Semantics</a></p></li>
-<li><p><a class="reference internal" href="#indicating-edits" id="toc-entry-51"><span class="sectnum">3.4</span> Indicating Edits</a></p></li>
+<li><p><a class="reference internal" href="#text-level-semantics" id="toc-entry-51"><span class="sectnum">3.3</span> Text-Level Semantics</a></p></li>
+<li><p><a class="reference internal" href="#indicating-edits" id="toc-entry-52"><span class="sectnum">3.4</span> Indicating Edits</a></p></li>
 </ul>
 </li>
-<li><p><a class="reference internal" href="#error-handling" id="toc-entry-52"><span class="sectnum">4</span> Error Handling</a></p></li>
+<li><p><a class="reference internal" href="#error-handling" id="toc-entry-53"><span class="sectnum">4</span> Error Handling</a></p></li>
 </ul>
 </nav>
 <section id="structural-elements">
@@ -192,7 +193,7 @@ activated with the <span class="docutils literal"><span class="pre">--section-su
 (<a class="reference external" href="http://www.python.org">http://www.python.org</a>), external hyperlinks (<a class="reference external" href="http://www.python.org/">Python</a> <a class="footnote-reference brackets" href="#footnote-7" id="footnote-reference-18" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a>), internal
 cross-references (<a class="reference internal" href="#example">example</a>), external hyperlinks with embedded URIs
 (<a class="reference external" href="http://www.python.org">Python web site</a>), <a class="reference external" href="http://www.python.org/">anonymous hyperlink
-references</a> <a class="footnote-reference brackets" href="#footnote-7" id="footnote-reference-25" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a> (<a class="reference external" href="https://docutils.sourceforge.io/">a second reference</a> <a class="footnote-reference brackets" href="#footnote-12" id="footnote-reference-26" role="doc-noteref"><span class="fn-bracket">[</span>12<span class="fn-bracket">]</span></a>), footnote references (manually
+references</a> <a class="footnote-reference brackets" href="#footnote-7" id="footnote-reference-26" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a> (<a class="reference external" href="https://docutils.sourceforge.io/">a second reference</a> <a class="footnote-reference brackets" href="#footnote-13" id="footnote-reference-27" role="doc-noteref"><span class="fn-bracket">[</span>13<span class="fn-bracket">]</span></a>), footnote references (manually
 numbered <a class="footnote-reference brackets" href="#footnote-1" id="footnote-reference-1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>, anonymous auto-numbered <a class="footnote-reference brackets" href="#footnote-2" id="footnote-reference-2" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a>, labeled auto-numbered
 <a class="footnote-reference brackets" href="#label" id="footnote-reference-3" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a>, or symbolic <a class="footnote-reference brackets" href="#footnote-3" id="footnote-reference-4" role="doc-noteref"><span class="fn-bracket">[</span>*<span class="fn-bracket">]</span></a>), citation references (see <a class="citation-reference" href="#cit2002" id="citation-reference-1" role="doc-biblioref">[CIT2002]</a>),
 substitution references (<img alt="EXAMPLE" src="../../../docs/user/rst/images/biohazard.png" /> &amp;
@@ -550,29 +551,29 @@ this: <a href="#system-message-5"><span class="problematic" id="problematic-3">`
 <h3><a class="toc-backref" href="#toc-entry-22"><span class="sectnum">2.14</span> Directives</a></h3>
 <nav class="contents local" id="contents">
 <ul class="auto-toc simple">
-<li><p><a class="reference internal" href="#document-parts" id="toc-entry-53"><span class="sectnum">2.14.1</span> Document Parts</a></p></li>
-<li><p><a class="reference internal" href="#images-and-figures" id="toc-entry-54"><span class="sectnum">2.14.2</span> Images and Figures</a></p></li>
-<li><p><a class="reference internal" href="#tables" id="toc-entry-55"><span class="sectnum">2.14.3</span> Tables</a></p></li>
-<li><p><a class="reference internal" href="#admonitions" id="toc-entry-56"><span class="sectnum">2.14.4</span> Admonitions</a></p></li>
-<li><p><a class="reference internal" href="#topics-sidebars-and-rubrics" id="toc-entry-57"><span class="sectnum">2.14.5</span> Topics, Sidebars, and Rubrics</a></p></li>
-<li><p><a class="reference internal" href="#target-footnotes" id="toc-entry-58"><span class="sectnum">2.14.6</span> Target Footnotes</a></p></li>
-<li><p><a class="reference internal" href="#replacement-text" id="toc-entry-59"><span class="sectnum">2.14.7</span> Replacement Text</a></p></li>
-<li><p><a class="reference internal" href="#compound-paragraph" id="toc-entry-60"><span class="sectnum">2.14.8</span> Compound Paragraph</a></p></li>
-<li><p><a class="reference internal" href="#parsed-literal-blocks" id="toc-entry-61"><span class="sectnum">2.14.9</span> Parsed Literal Blocks</a></p></li>
-<li><p><a class="reference internal" href="#code" id="toc-entry-62"><span class="sectnum">2.14.10</span> Code</a></p></li>
-<li><p><a class="reference internal" href="#meta" id="toc-entry-63"><span class="sectnum">2.14.11</span> Meta</a></p></li>
+<li><p><a class="reference internal" href="#document-parts" id="toc-entry-54"><span class="sectnum">2.14.1</span> Document Parts</a></p></li>
+<li><p><a class="reference internal" href="#images-and-figures" id="toc-entry-55"><span class="sectnum">2.14.2</span> Images and Figures</a></p></li>
+<li><p><a class="reference internal" href="#tables" id="toc-entry-56"><span class="sectnum">2.14.3</span> Tables</a></p></li>
+<li><p><a class="reference internal" href="#admonitions" id="toc-entry-57"><span class="sectnum">2.14.4</span> Admonitions</a></p></li>
+<li><p><a class="reference internal" href="#topics-sidebars-and-rubrics" id="toc-entry-58"><span class="sectnum">2.14.5</span> Topics, Sidebars, and Rubrics</a></p></li>
+<li><p><a class="reference internal" href="#target-footnotes" id="toc-entry-59"><span class="sectnum">2.14.6</span> Target Footnotes</a></p></li>
+<li><p><a class="reference internal" href="#replacement-text" id="toc-entry-60"><span class="sectnum">2.14.7</span> Replacement Text</a></p></li>
+<li><p><a class="reference internal" href="#compound-paragraph" id="toc-entry-61"><span class="sectnum">2.14.8</span> Compound Paragraph</a></p></li>
+<li><p><a class="reference internal" href="#parsed-literal-blocks" id="toc-entry-62"><span class="sectnum">2.14.9</span> Parsed Literal Blocks</a></p></li>
+<li><p><a class="reference internal" href="#code" id="toc-entry-63"><span class="sectnum">2.14.10</span> Code</a></p></li>
+<li><p><a class="reference internal" href="#meta" id="toc-entry-64"><span class="sectnum">2.14.11</span> Meta</a></p></li>
 </ul>
 </nav>
 <p>These are just a sample of the many reStructuredText Directives.  For
-others, please see <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html">reStructuredText Directives</a> <a class="footnote-reference brackets" href="#footnote-13" id="footnote-reference-27" role="doc-noteref"><span class="fn-bracket">[</span>13<span class="fn-bracket">]</span></a>.</p>
+others, please see <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html">reStructuredText Directives</a> <a class="footnote-reference brackets" href="#footnote-14" id="footnote-reference-28" role="doc-noteref"><span class="fn-bracket">[</span>14<span class="fn-bracket">]</span></a>.</p>
 <section id="document-parts">
-<h4><a class="toc-backref" href="#toc-entry-53"><span class="sectnum">2.14.1</span> Document Parts</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-54"><span class="sectnum">2.14.1</span> Document Parts</a></h4>
 <p>An example of the &quot;contents&quot; directive can be seen above this section
 (a local, untitled table of <a class="reference internal" href="#contents">contents</a>) and at the beginning of the
 document (a document-wide <a class="reference internal" href="#table-of-contents">table of contents</a>).</p>
 </section>
 <section id="images-and-figures">
-<h4><a class="toc-backref" href="#toc-entry-54"><span class="sectnum">2.14.2</span> Images and Figures</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-55"><span class="sectnum">2.14.2</span> Images and Figures</a></h4>
 <p>An image directive (also clickable -- a hyperlink reference):</p>
 <a class="reference internal image-reference" href="#directives"><img alt="../../../docs/user/rst/images/title.png" class="class1 class2" src="../../../docs/user/rst/images/title.png" style="width: 70%;" /></a>
 <p>Image with multiple IDs:</p>
@@ -670,7 +671,7 @@ rendering software used.</p>
 upon the style sheet and the browser or rendering software used.</p>
 </section>
 <section id="tables">
-<h4><a class="toc-backref" href="#toc-entry-55"><span class="sectnum">2.14.3</span> Tables</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-56"><span class="sectnum">2.14.3</span> Tables</a></h4>
 <p>Tables may be given titles and additional arguments with the <em>table</em>
 directive:</p>
 <table class="align-left">
@@ -764,7 +765,7 @@ writer/backend).</p>
 </table>
 </section>
 <section id="admonitions">
-<h4><a class="toc-backref" href="#toc-entry-56"><span class="sectnum">2.14.4</span> Admonitions</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-57"><span class="sectnum">2.14.4</span> Admonitions</a></h4>
 <aside class="admonition attention">
 <p class="admonition-title">Attention!</p>
 <p>Directives at large.</p>
@@ -813,7 +814,7 @@ Reader discretion is strongly advised.</p>
 </aside>
 </section>
 <section id="topics-sidebars-and-rubrics">
-<h4><a class="toc-backref" href="#toc-entry-57"><span class="sectnum">2.14.5</span> Topics, Sidebars, and Rubrics</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-58"><span class="sectnum">2.14.5</span> Topics, Sidebars, and Rubrics</a></h4>
 <p><em>Sidebars</em> are like miniature, parallel documents.</p>
 <aside class="sidebar">
 <p class="sidebar-title">Optional Sidebar Title</p>
@@ -837,10 +838,10 @@ document's structure. It is typically highlighted in red (hence the name).</p>
 allowed (e.g. inside a directive).</p>
 </section>
 <section id="target-footnotes">
-<h4><a class="toc-backref" href="#toc-entry-58"><span class="sectnum">2.14.6</span> Target Footnotes</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-59"><span class="sectnum">2.14.6</span> Target Footnotes</a></h4>
 <aside class="footnote brackets" id="footnote-7" role="note">
 <span class="label"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></span>
-<span class="backrefs">(<a role="doc-backlink" href="#footnote-reference-18">1</a>,<a role="doc-backlink" href="#footnote-reference-19">2</a>,<a role="doc-backlink" href="#footnote-reference-20">3</a>,<a role="doc-backlink" href="#footnote-reference-25">4</a>)</span>
+<span class="backrefs">(<a role="doc-backlink" href="#footnote-reference-18">1</a>,<a role="doc-backlink" href="#footnote-reference-19">2</a>,<a role="doc-backlink" href="#footnote-reference-20">3</a>,<a role="doc-backlink" href="#footnote-reference-26">4</a>)</span>
 <p><a class="reference external" href="http://www.python.org/">http://www.python.org/</a></p>
 </aside>
 <aside class="footnote brackets" id="footnote-8" role="note">
@@ -849,51 +850,55 @@ allowed (e.g. inside a directive).</p>
 </aside>
 <aside class="footnote brackets" id="footnote-9" role="note">
 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-22">9</a><span class="fn-bracket">]</span></span>
-<p><a class="reference external" href="http://docutils.sourceforge.net/docs/user/config.html#table-style">http://docutils.sourceforge.net/docs/user/config.html#table-style</a></p>
+<p><a class="reference external" href="https://www.w3.org/TR/html52/interactive-elements.html#the-details-element">https://www.w3.org/TR/html52/interactive-elements.html#the-details-element</a></p>
 </aside>
 <aside class="footnote brackets" id="footnote-10" role="note">
 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-23">10</a><span class="fn-bracket">]</span></span>
-<p><a class="reference external" href="http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf">http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf</a></p>
+<p><a class="reference external" href="http://docutils.sourceforge.net/docs/user/config.html#table-style">http://docutils.sourceforge.net/docs/user/config.html#table-style</a></p>
 </aside>
 <aside class="footnote brackets" id="footnote-11" role="note">
 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-24">11</a><span class="fn-bracket">]</span></span>
-<p><a class="reference external" href="http://docutils.sourceforge.net/docs/dev/todo.html#interpreted-text">http://docutils.sourceforge.net/docs/dev/todo.html#interpreted-text</a></p>
+<p><a class="reference external" href="http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf">http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf</a></p>
 </aside>
 <aside class="footnote brackets" id="footnote-12" role="note">
-<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-26">12</a><span class="fn-bracket">]</span></span>
-<p><a class="reference external" href="https://docutils.sourceforge.io/">https://docutils.sourceforge.io/</a></p>
+<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-25">12</a><span class="fn-bracket">]</span></span>
+<p><a class="reference external" href="http://docutils.sourceforge.net/docs/dev/todo.html#interpreted-text">http://docutils.sourceforge.net/docs/dev/todo.html#interpreted-text</a></p>
 </aside>
 <aside class="footnote brackets" id="footnote-13" role="note">
 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-27">13</a><span class="fn-bracket">]</span></span>
-<p><a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html">https://docutils.sourceforge.io/docs/ref/rst/directives.html</a></p>
+<p><a class="reference external" href="https://docutils.sourceforge.io/">https://docutils.sourceforge.io/</a></p>
 </aside>
 <aside class="footnote brackets" id="footnote-14" role="note">
 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-28">14</a><span class="fn-bracket">]</span></span>
-<p><a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata">https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata</a></p>
+<p><a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html">https://docutils.sourceforge.io/docs/ref/rst/directives.html</a></p>
 </aside>
 <aside class="footnote brackets" id="footnote-15" role="note">
 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-29">15</a><span class="fn-bracket">]</span></span>
-<p><a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag">https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag</a></p>
+<p><a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata">https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata</a></p>
 </aside>
 <aside class="footnote brackets" id="footnote-16" role="note">
 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-30">16</a><span class="fn-bracket">]</span></span>
-<p><a class="reference external" href="https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article">https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article</a></p>
+<p><a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag">https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag</a></p>
 </aside>
 <aside class="footnote brackets" id="footnote-17" role="note">
 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-31">17</a><span class="fn-bracket">]</span></span>
-<p><a class="reference external" href="https://html.spec.whatwg.org/#text-level-semantics">https://html.spec.whatwg.org/#text-level-semantics</a></p>
+<p><a class="reference external" href="https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article">https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article</a></p>
 </aside>
 <aside class="footnote brackets" id="footnote-18" role="note">
 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-32">18</a><span class="fn-bracket">]</span></span>
+<p><a class="reference external" href="https://html.spec.whatwg.org/#text-level-semantics">https://html.spec.whatwg.org/#text-level-semantics</a></p>
+</aside>
+<aside class="footnote brackets" id="footnote-19" role="note">
+<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-33">19</a><span class="fn-bracket">]</span></span>
 <p><a class="reference external" href="https://html.spec.whatwg.org/multipage/edits.html">https://html.spec.whatwg.org/multipage/edits.html</a></p>
 </aside>
 </section>
 <section id="replacement-text">
-<h4><a class="toc-backref" href="#toc-entry-59"><span class="sectnum">2.14.7</span> Replacement Text</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-60"><span class="sectnum">2.14.7</span> Replacement Text</a></h4>
 <p>I recommend you try <a class="reference external" href="http://www.python.org/">Python, <em>the</em> best language around</a> <a class="footnote-reference brackets" href="#footnote-7" id="footnote-reference-20" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a>.</p>
 </section>
 <section id="compound-paragraph">
-<h4><a class="toc-backref" href="#toc-entry-60"><span class="sectnum">2.14.8</span> Compound Paragraph</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-61"><span class="sectnum">2.14.8</span> Compound Paragraph</a></h4>
 <p>The <em>compound</em> directive is used to create a &quot;compound paragraph&quot;, which
 is a single logical paragraph containing multiple physical body
 elements. For example:</p>
@@ -1004,7 +1009,7 @@ by</p>
 </div>
 </section>
 <section id="parsed-literal-blocks">
-<h4><a class="toc-backref" href="#toc-entry-61"><span class="sectnum">2.14.9</span> Parsed Literal Blocks</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-62"><span class="sectnum">2.14.9</span> Parsed Literal Blocks</a></h4>
 <pre class="literal-block">This is a parsed literal block.
     This line is indented.  The next line is blank.
 
@@ -1014,7 +1019,7 @@ inline formulas: <span class="formula"><i>A</i> = 2<i>π</i><i>r</i><sup>2</
 footnotes <a class="footnote-reference brackets" href="#footnote-1" id="footnote-reference-9" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>, <span class="target" id="hyperlink-targets">hyperlink targets</span>, and <a class="reference external" href="http://www.python.org/">references</a>.</pre>
 </section>
 <section id="code">
-<h4><a class="toc-backref" href="#toc-entry-62"><span class="sectnum">2.14.10</span> Code</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-63"><span class="sectnum">2.14.10</span> Code</a></h4>
 <p>Blocks of source code can be set with the <cite>code</cite> directive. If the code
 language is specified, the content is parsed and tagged by the <a class="reference external" href="http://pygments.org/">Pygments</a> <a class="footnote-reference brackets" href="#footnote-8" id="footnote-reference-21" role="doc-noteref"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></a>
 syntax highlighter and can be formatted with a style sheet. (Code parsing
@@ -1039,8 +1044,8 @@ as a code block, here the rst file <span class="docutils literal">header_footer.
 </code><small class="ln">2 </small><code data-lineno="2 ">.. footer:: Document footer</code></pre>
 </section>
 <section id="meta">
-<h4><a class="toc-backref" href="#toc-entry-63"><span class="sectnum">2.14.11</span> Meta</a></h4>
-<p>The <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata">“meta” directive</a> <a class="footnote-reference brackets" href="#footnote-14" id="footnote-reference-28" role="doc-noteref"><span class="fn-bracket">[</span>14<span class="fn-bracket">]</span></a> is used to specify metadata to be stored in,
+<h4><a class="toc-backref" href="#toc-entry-64"><span class="sectnum">2.14.11</span> Meta</a></h4>
+<p>The <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata">“meta” directive</a> <a class="footnote-reference brackets" href="#footnote-15" id="footnote-reference-29" role="doc-noteref"><span class="fn-bracket">[</span>15<span class="fn-bracket">]</span></a> is used to specify metadata to be stored in,
 e.g., HTML META tags or ODT file properties.</p>
 </section>
 </section>
@@ -1278,7 +1283,7 @@ crunchy, now would it?</p></td>
 <li><p>Use only <a class="reference internal" href="#meta">meta</a> keywords recognized by HTML 5.
 Add HTML5-compatible meta tags for docinfo items
 &quot;authors&quot;, &quot;date&quot;, and &quot;copyright&quot;.</p>
-<p>Add a <a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag">viewport meta tag</a> <a class="footnote-reference brackets" href="#footnote-15" id="footnote-reference-29" role="doc-noteref"><span class="fn-bracket">[</span>15<span class="fn-bracket">]</span></a> to tell mobile browsers
+<p>Add a <a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag">viewport meta tag</a> <a class="footnote-reference brackets" href="#footnote-16" id="footnote-reference-30" role="doc-noteref"><span class="fn-bracket">[</span>16<span class="fn-bracket">]</span></a> to tell mobile browsers
 to use the device-width as viewport.</p>
 </li>
 <li><p>Set table column widths with &lt;style=&quot;width: ...&quot;&gt;, not &quot;width&quot; argument.</p></li>
@@ -1290,7 +1295,7 @@ space.</p></li>
 &lt;footer&gt;, &lt;aside&gt;, &lt;figure&gt;, and &lt;figcaption&gt;.
 See <span class="docutils literal">minimal.css</span> and <span class="docutils literal">responsive.css</span> for styling rule examples.</p>
 <p>Change the <cite>initial_header_level</cite> setting default to &quot;2&quot;, as browsers
-use the <a class="reference external" href="https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article">same style for &lt;h1&gt; and &lt;h2&gt; when nested in a &lt;section&gt;</a> <a class="footnote-reference brackets" href="#footnote-16" id="footnote-reference-30" role="doc-noteref"><span class="fn-bracket">[</span>16<span class="fn-bracket">]</span></a>.</p>
+use the <a class="reference external" href="https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article">same style for &lt;h1&gt; and &lt;h2&gt; when nested in a &lt;section&gt;</a> <a class="footnote-reference brackets" href="#footnote-17" id="footnote-reference-31" role="doc-noteref"><span class="fn-bracket">[</span>17<span class="fn-bracket">]</span></a>.</p>
 </li>
 <li><p>Use HTML5 tags &lt;small&gt;, &lt;s&gt;, &lt;q&gt;, &lt;dfn&gt;, &lt;var&gt;, &lt;samp&gt;, &lt;kbd&gt;,
 &lt;i&gt;, &lt;b&gt;, &lt;u&gt;, &lt;mark&gt;, and &lt;bdi&gt; if a matching class value
@@ -1366,8 +1371,22 @@ encyclopedias etc. (as well as the LaTeX <cite>description</cite> environment).<
 </dd>
 </dl>
 </section>
+<section id="details-disclosure-elements">
+<h4><a class="toc-backref" href="#toc-entry-47"><span class="sectnum">3.2.2</span> Details disclosure elements</a></h4>
+<p>Items of <a class="reference internal" href="#definition-lists">definition lists</a> with class argument &quot;details&quot; are converted
+to <a class="reference external" href="https://www.w3.org/TR/html52/interactive-elements.html#the-details-element">details</a> <a class="footnote-reference brackets" href="#footnote-9" id="footnote-reference-22" role="doc-noteref"><span class="fn-bracket">[</span>9<span class="fn-bracket">]</span></a> disclosure elements with the term becoming the &quot;summary&quot;.</p>
+<details>
+<summary>A summary</summary>
+<p>with details only visible after user interaction.</p>
+</details>
+<details open="open">
+<summary>Another summary</summary>
+<p>with open details because the source list has the additional class
+value &quot;open&quot;.</p>
+</details>
+</section>
 <section id="field-list-variants">
-<h4><a class="toc-backref" href="#toc-entry-47"><span class="sectnum">3.2.2</span> Field List Variants</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-48"><span class="sectnum">3.2.3</span> Field List Variants</a></h4>
 <p>For field lists, the &quot;compact/open&quot;, &quot;narrow&quot; and &quot;run-in&quot; styles are defined
 in the style sheets <span class="docutils literal">plain.css</span> and <span class="docutils literal">responsive.css</span>.</p>
 <dl class="simple">
@@ -1448,9 +1467,9 @@ body is wrapped and aligns with other fields.</p>
 </dl>
 </section>
 <section id="table-variants">
-<h4><a class="toc-backref" href="#toc-entry-48"><span class="sectnum">3.2.3</span> Table Variants</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-49"><span class="sectnum">3.2.4</span> Table Variants</a></h4>
 <p>The following styles can be applied to individual tables via a class
-argument or as document wide setting with the <a class="reference external" href="http://docutils.sourceforge.net/docs/user/config.html#table-style">table-style</a> <a class="footnote-reference brackets" href="#footnote-9" id="footnote-reference-22" role="doc-noteref"><span class="fn-bracket">[</span>9<span class="fn-bracket">]</span></a> configuration
+argument or as document wide setting with the <a class="reference external" href="http://docutils.sourceforge.net/docs/user/config.html#table-style">table-style</a> <a class="footnote-reference brackets" href="#footnote-10" id="footnote-reference-23" role="doc-noteref"><span class="fn-bracket">[</span>10<span class="fn-bracket">]</span></a> configuration
 setting (or command line argument).</p>
 <ul>
 <li><p>Numbered tables can be achieved with the &quot;numbered&quot; class option:</p>
@@ -1490,7 +1509,7 @@ setting (or command line argument).</p>
 common request and already on the <cite>TODO list</cite>.</p>
 </li>
 <li><p>A table with &quot;booktabs&quot; class value, is rendered similar to the style
-from the <a class="reference external" href="http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf">booktabs</a> <a class="footnote-reference brackets" href="#footnote-10" id="footnote-reference-23" role="doc-noteref"><span class="fn-bracket">[</span>10<span class="fn-bracket">]</span></a> LaTeX package.</p>
+from the <a class="reference external" href="http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf">booktabs</a> <a class="footnote-reference brackets" href="#footnote-11" id="footnote-reference-24" role="doc-noteref"><span class="fn-bracket">[</span>11<span class="fn-bracket">]</span></a> LaTeX package.</p>
 </li>
 </ul>
 <p>&quot;Booktabs&quot; style table, numbered, centre-aligned, with auto-sized columns:</p>
@@ -1528,7 +1547,7 @@ from the <a class="reference external" href="http://tug.ctan.org/tex-archive/mac
 </blockquote>
 </section>
 <section id="numbered-figures">
-<h4><a class="toc-backref" href="#toc-entry-49"><span class="sectnum">3.2.4</span> Numbered Figures</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-50"><span class="sectnum">3.2.5</span> Numbered Figures</a></h4>
 <p>Numbered figures can be achieved with the &quot;numbered&quot; <span class="docutils literal">:figclass:</span> option:</p>
 <figure class="numbered">
 <img alt="reStructuredText, the markup syntax" src="../../../docs/user/rst/images/title.svg" style="width: 100%;" />
@@ -1539,9 +1558,9 @@ from the <a class="reference external" href="http://tug.ctan.org/tex-archive/mac
 </section>
 </section>
 <section id="text-level-semantics">
-<h3><a class="toc-backref" href="#toc-entry-50"><span class="sectnum">3.3</span> Text-Level Semantics</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-51"><span class="sectnum">3.3</span> Text-Level Semantics</a></h3>
 <p>This section describes the <a class="reference external" href="https://html.spec.whatwg.org/#text-level-semantics">HTML 5 tags for representation of text-level
-semantics</a> <a class="footnote-reference brackets" href="#footnote-17" id="footnote-reference-31" role="doc-noteref"><span class="fn-bracket">[</span>17<span class="fn-bracket">]</span></a> and their reStructuredText equivalents.</p>
+semantics</a> <a class="footnote-reference brackets" href="#footnote-18" id="footnote-reference-32" role="doc-noteref"><span class="fn-bracket">[</span>18<span class="fn-bracket">]</span></a> and their reStructuredText equivalents.</p>
 <dl class="description">
 <dt>a</dt>
 <dd><p>Hyperlinks</p>
@@ -1737,7 +1756,7 @@ a substitution.</p>
 <span class="label"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></span>
 <span class="backrefs">(<a role="doc-backlink" href="#footnote-reference-10">1</a>,<a role="doc-backlink" href="#footnote-reference-14">2</a>,<a role="doc-backlink" href="#footnote-reference-16">3</a>,<a role="doc-backlink" href="#footnote-reference-17">4</a>)</span>
 <p>Would gain from support for attributes/arguments
-to inline roles. See <a class="reference external" href="http://docutils.sourceforge.net/docs/dev/todo.html#interpreted-text">TODO</a> <a class="footnote-reference brackets" href="#footnote-11" id="footnote-reference-24" role="doc-noteref"><span class="fn-bracket">[</span>11<span class="fn-bracket">]</span></a></p>
+to inline roles. See <a class="reference external" href="http://docutils.sourceforge.net/docs/dev/todo.html#interpreted-text">TODO</a> <a class="footnote-reference brackets" href="#footnote-12" id="footnote-reference-25" role="doc-noteref"><span class="fn-bracket">[</span>12<span class="fn-bracket">]</span></a></p>
 </aside>
 <aside class="footnote brackets" id="attribute-required" role="note">
 <span class="label"><span class="fn-bracket">[</span>6<span class="fn-bracket">]</span></span>
@@ -1747,8 +1766,8 @@ roles to make sense.</p>
 </aside>
 </section>
 <section id="indicating-edits">
-<h3><a class="toc-backref" href="#toc-entry-51"><span class="sectnum">3.4</span> Indicating Edits</a></h3>
-<p>The <a class="reference external" href="https://html.spec.whatwg.org/multipage/edits.html">HTML tags for representation of edits to the document</a> <a class="footnote-reference brackets" href="#footnote-18" id="footnote-reference-32" role="doc-noteref"><span class="fn-bracket">[</span>18<span class="fn-bracket">]</span></a> and their
+<h3><a class="toc-backref" href="#toc-entry-52"><span class="sectnum">3.4</span> Indicating Edits</a></h3>
+<p>The <a class="reference external" href="https://html.spec.whatwg.org/multipage/edits.html">HTML tags for representation of edits to the document</a> <a class="footnote-reference brackets" href="#footnote-19" id="footnote-reference-33" role="doc-noteref"><span class="fn-bracket">[</span>19<span class="fn-bracket">]</span></a> and their
 reStructuredText equivalents are:</p>
 <dl class="description">
 <dt>ins</dt>
@@ -1773,7 +1792,7 @@ reStructuredText equivalents are:</p>
 </section>
 </section>
 <section id="error-handling">
-<h2><a class="toc-backref" href="#toc-entry-52"><span class="sectnum">4</span> Error Handling</a></h2>
+<h2><a class="toc-backref" href="#toc-entry-53"><span class="sectnum">4</span> Error Handling</a></h2>
 <p>Any errors caught during processing will generate system messages.</p>
 <p>There should be five messages in the following, auto-generated
 section, &quot;Docutils System Messages&quot;:</p>
diff --git a/docutils/test/functional/input/data/html5-features.txt b/docutils/test/functional/input/data/html5-features.txt
index c51b5a75b..fbd006917 100644
--- a/docutils/test/functional/input/data/html5-features.txt
+++ b/docutils/test/functional/input/data/html5-features.txt
@@ -96,6 +96,25 @@ or
     nested
       definition lists
 
+Details disclosure elements
+```````````````````````````
+
+Items of `definition lists`_ with class argument "details" are converted
+to `details`_ disclosure elements with the term becoming the "summary".
+
+.. class:: details
+
+A summary
+  with details only visible after user interaction.
+
+.. class:: details open
+
+Another summary
+  with open details because the source list has the additional class
+  value "open".
+
+.. _details:
+   https://www.w3.org/TR/html52/interactive-elements.html#the-details-element
 
 Field List Variants
 ```````````````````