HTML5: ARIA roles for citations and citation-references.

Use <div> with DPub ARIA role "doc-biblioentry" for citations.
Wrapping citations in a list (required for elements with role
"doc-biblioentry").

Use role "doc-biblioref" for citation-references.

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

7 files changed, 67 insertions, 41 deletions

diff --git a/docutils/docutils/nodes.py b/docutils/docutils/nodes.py
index 81b4841a3..b3587e989 100644
--- a/docutils/docutils/nodes.py
+++ b/docutils/docutils/nodes.py
@@ -324,6 +324,13 @@ class Node(object):
         except StopIteration:
             return None
 
+    def previous_sibling(self):
+        """Return preceding sibling node or ``None``."""
+        try:
+            return self.parent[self.parent.index(self)-1]
+        except (AttributeError, IndexError):
+            return None
+
 if sys.version_info < (3, 0):
     class reprunicode(unicode):
         """
diff --git a/docutils/docutils/writers/_html_base.py b/docutils/docutils/writers/_html_base.py
index e47e303a9..d536b4d33 100644
--- a/docutils/docutils/writers/_html_base.py
+++ b/docutils/docutils/writers/_html_base.py
@@ -619,12 +619,23 @@ class HTMLTranslator(nodes.NodeVisitor):
     def depart_caption(self, node):
         self.body.append('</p>\n')
 
+    # Use semantic tag and DPub role (HTML4 uses a table)
     def visit_citation(self, node):
-        self.visit_footnote(node)
+        # role 'doc-bibloentry' requires wrapping in an element with
+        # role 'list' and an element with role 'doc-bibliography'
+        # https://www.w3.org/TR/dpub-aria-1.0/#doc-biblioentry)
+        if not isinstance(node.previous_sibling(), type(node)):
+            self.body.append('<div role="list" class="citation-list">\n')
+        self.body.append(self.starttag(node, 'div', classes=[node.tagname],
+                                       role="doc-biblioentry"))
 
     def depart_citation(self, node):
-        self.depart_footnote(node)
+        self.body.append('</div>\n')
+        next_node = node.next_node(descend=False, siblings=True)
+        if not isinstance(next_node, type(node)):
+            self.body.append('</div>\n')
 
+    # Use DPub role (overwritten in HTML4)
     def visit_citation_reference(self, node):
         href = '#'
         if 'refid' in node:
@@ -633,9 +644,9 @@ class HTMLTranslator(nodes.NodeVisitor):
             href += self.document.nameids[node['refname']]
         # else: # TODO system message (or already in the transform)?
         # 'Citation reference missing.'
-        self.body.append(self.starttag(
-            node, 'a', '[', CLASS='citation-reference', href=href))
-            # TODO: role='doc-biblioref' # HTML5 only
+        self.body.append(self.starttag(node, 'a', suffix='[', href=href,
+                                       classes=['citation-reference'],
+                                       role='doc-biblioref'))
 
     def depart_citation_reference(self, node):
         self.body.append(']</a>')
@@ -916,16 +927,11 @@ class HTMLTranslator(nodes.NodeVisitor):
         del self.body[start:]
 
     # use HTML5 element <aside> with ARIA role "note" for footnote text
-    # (the html4css1 writer uses a table instead).
-    # TODO: role='doc-biblioentry' for citations
-    # (requires wrapping in an element with role='list'
-    # https://www.w3.org/TR/dpub-aria-1.0/#doc-biblioentry)
+    # (the html4css1 writer uses a table).
     def visit_footnote(self, node):
-        classes = [node.tagname]
-        if isinstance(node, nodes.footnote):
-            classes.append(self.settings.footnote_references)
-        self.body.append(self.starttag(node, 'aside',
-                                       classes=classes, role="note"))
+        classes = [node.tagname, self.settings.footnote_references]
+        self.body.append(self.starttag(node, 'aside', classes=classes,
+                                       role="note"))
 
     def depart_footnote(self, node):
         self.body.append('</aside>\n')
@@ -1076,8 +1082,7 @@ class HTMLTranslator(nodes.NodeVisitor):
         backrefs = node.parent.get('backrefs', [])
         if len(backrefs) == 1:
             self.body.append('</a>')
-        self.body.append('<span class="fn-bracket">]</span>')
-        self.body.append('</span>\n')
+        self.body.append('<span class="fn-bracket">]</span></span>\n')
         if len(backrefs) > 1:
             backlinks = ['<a role="doc-backlink" href="#%s">%s</a>' % (ref, i)
                          for (i, ref) in enumerate(backrefs, 1)]
diff --git a/docutils/docutils/writers/html4css1/__init__.py b/docutils/docutils/writers/html4css1/__init__.py
index f78623784..275144906 100644
--- a/docutils/docutils/writers/html4css1/__init__.py
+++ b/docutils/docutils/writers/html4css1/__init__.py
@@ -260,6 +260,18 @@ class HTMLTranslator(writers._html_base.HTMLTranslator):
         self.body.append('</td></tr>\n'
                          '</tbody>\n</table>\n')
 
+    def visit_citation_reference(self, node):
+        href = '#'
+        if 'refid' in node:
+            href += node['refid']
+        elif 'refname' in node:
+            href += self.document.nameids[node['refname']]
+        self.body.append(self.starttag(node, 'a', suffix='[', href=href,
+                                       classes=['citation-reference']))
+
+    def depart_citation_reference(self, node):
+        self.body.append(']</a>')
+
     # insert classifier-delimiter (not required with CSS2)
     def visit_classifier(self, node):
         self.body.append(' <span class="classifier-delimiter">:</span> ')
@@ -345,7 +357,7 @@ class HTMLTranslator(writers._html_base.HTMLTranslator):
 
     def depart_doctest_block(self, node):
         self.body.append('\n</pre>\n')
-    
+
     # insert an NBSP into empty cells, ersatz for first/last
     def visit_entry(self, node):
         writers._html_base.HTMLTranslator.visit_entry(self, node)
diff --git a/docutils/docutils/writers/html5_polyglot/minimal.css b/docutils/docutils/writers/html5_polyglot/minimal.css
index 183459d19..e072fb9aa 100644
--- a/docutils/docutils/writers/html5_polyglot/minimal.css
+++ b/docutils/docutils/writers/html5_polyglot/minimal.css
@@ -146,16 +146,14 @@ span.option { white-space: nowrap; }
 
 /* Footnotes and Citations  */
 
-.footnote, .citation {
-  margin: 1em 0; /* default paragraph skip (Firefox) */
-}
+.footnote, .citation { margin: 1em 0; } /* default paragraph skip (Firefox) */
 /* hanging indent */
-.footnote { padding-left: 1.7em; }
 .citation { padding-left: 2em; }
-.footnote.superscript { padding-left: 1em; }
-.footnote > .label { margin-left: -1.7em; }
+.footnote { padding-left: 1.7em; }
+.footnote.superscript { padding-left: 0.9em; }
 .citation > .label { margin-left: -2em; }
-.footnote.superscript > .label { margin-left: -1em; }
+.footnote > .label { margin-left: -1.7em; }
+.footnote.superscript > .label { margin-left: -0.9em; }
 
 .footnote > .label + *,
 .citation > .label + * {
diff --git a/docutils/test/functional/expected/footnotes_html5.html b/docutils/test/functional/expected/footnotes_html5.html
index a574cf960..3bf40ba73 100644
--- a/docutils/test/functional/expected/footnotes_html5.html
+++ b/docutils/test/functional/expected/footnotes_html5.html
@@ -13,7 +13,7 @@
 <h1 class="title">Test footnote and citation rendering</h1>
 
 <p>Paragraphs may contain footnote references (manually numbered<a class="footnote-reference superscript" 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 superscript" 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 superscript" 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 superscript" href="#footnote-3" id="footnote-reference-4" role="doc-noteref"><span class="fn-bracket">[</span>*<span class="fn-bracket">]</span></a>) or citation references (<a class="citation-reference" href="#cit2002" id="citation-reference-1">[CIT2002]</a>, <a class="citation-reference" href="#du2015" id="citation-reference-2">[DU2015]</a>).</p>
+symbolic<a class="footnote-reference superscript" href="#footnote-3" id="footnote-reference-4" role="doc-noteref"><span class="fn-bracket">[</span>*<span class="fn-bracket">]</span></a>) or citation references (<a class="citation-reference" href="#cit2002" id="citation-reference-1" role="doc-biblioref">[CIT2002]</a>, <a class="citation-reference" href="#du2015" id="citation-reference-2" role="doc-biblioref">[DU2015]</a>).</p>
 <aside class="footnote superscript" id="footnote-1" role="note">
 <span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>
 <span class="backrefs">(<a role="doc-backlink" href="#footnote-reference-1">1</a>,<a role="doc-backlink" href="#footnote-reference-5">2</a>)</span>
@@ -52,25 +52,27 @@ nonexistent footnote:<a class="footnote-reference superscript" href="#footnote-6
 </aside>
 <section id="citations">
 <h2>Citations</h2>
-<aside class="citation" id="cit2002" role="note">
+<div role="list" class="citation-list">
+<div class="citation" id="cit2002" role="doc-biblioentry">
 <span class="label"><span class="fn-bracket">[</span>CIT2002<span class="fn-bracket">]</span></span>
 <span class="backrefs">(<a role="doc-backlink" href="#citation-reference-1">1</a>,<a role="doc-backlink" href="#citation-reference-3">2</a>)</span>
 <p>Citations are text-labeled footnotes. They may be
 rendered separately and differently from footnotes.</p>
-</aside>
-<aside class="citation" id="du2015" role="note">
+</div>
+<div class="citation" id="du2015" role="doc-biblioentry">
 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#citation-reference-2">DU2015</a><span class="fn-bracket">]</span></span>
 <p><cite>Example document</cite>, Hometown: 2015.</p>
-</aside>
-<p>Here's a reference to the above, <a class="citation-reference" href="#cit2002" id="citation-reference-3">[CIT2002]</a>.</p>
+</div>
+</div>
+<p>Here's a reference to the above, <a class="citation-reference" href="#cit2002" id="citation-reference-3" role="doc-biblioref">[CIT2002]</a>.</p>
 <aside class="footnote superscript" id="footnote-6" role="note">
 <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-8">5</a><span class="fn-bracket">]</span></span>
 <p>this footnote is missing in the standard example document.</p>
 </aside>
-<p>Footnotes may contain block elements like lists<a class="footnote-reference superscript" href="#list-note" id="footnote-reference-9" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a><a class="footnote-reference superscript" href="#footnote-7" id="footnote-reference-10" role="doc-noteref"><span class="fn-bracket">[</span>6<span class="fn-bracket">]</span></a>,
-admonitions<a class="footnote-reference superscript" href="#footnote-8" id="footnote-reference-11" role="doc-noteref"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></a>, or tables<a class="footnote-reference superscript" href="#footnote-9" id="footnote-reference-12" role="doc-noteref"><span class="fn-bracket">[</span>9<span class="fn-bracket">]</span></a>.</p>
+<p>Footnotes may contain block elements like lists<a class="footnote-reference superscript" href="#footnote-7" id="footnote-reference-9" role="doc-noteref"><span class="fn-bracket">[</span>6<span class="fn-bracket">]</span></a><a class="footnote-reference superscript" href="#list-note" id="footnote-reference-10" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a><a class="footnote-reference superscript" href="#footnote-8" id="footnote-reference-11" role="doc-noteref"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></a>,
+admonitions<a class="footnote-reference superscript" href="#footnote-9" id="footnote-reference-12" role="doc-noteref"><span class="fn-bracket">[</span>9<span class="fn-bracket">]</span></a>, or tables<a class="footnote-reference superscript" href="#footnote-10" id="footnote-reference-13" role="doc-noteref"><span class="fn-bracket">[</span>10<span class="fn-bracket">]</span></a>.</p>
 <aside class="footnote superscript" id="footnote-7" role="note">
-<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-10">6</a><span class="fn-bracket">]</span></span>
+<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-9">6</a><span class="fn-bracket">]</span></span>
 <ol class="arabic simple">
 <li><p>An ordered list</p></li>
 <li><p>in a footnote.</p></li>
@@ -78,7 +80,7 @@ admonitions<a class="footnote-reference superscript" href="#footnote-8" id="foot
 </aside>
 <aside class="footnote superscript" id="list-note" 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-9">1</a>,<a role="doc-backlink" href="#footnote-reference-13">2</a>)</span>
+<span class="backrefs">(<a role="doc-backlink" href="#footnote-reference-10">1</a>,<a role="doc-backlink" href="#footnote-reference-14">2</a>)</span>
 <ul class="simple">
 <li><p>An unordered list (bullet list)</p></li>
 <li><p>in a footnote.</p></li>
@@ -104,7 +106,7 @@ admonitions<a class="footnote-reference superscript" href="#footnote-8" id="foot
 </aside>
 </aside>
 <aside class="footnote superscript" id="footnote-10" role="note">
-<span class="label"><span class="fn-bracket">[</span>10<span class="fn-bracket">]</span></span>
+<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-13">10</a><span class="fn-bracket">]</span></span>
 <table>
 <colgroup>
 <col style="width: 36%" />
@@ -120,7 +122,7 @@ admonitions<a class="footnote-reference superscript" href="#footnote-8" id="foot
 </tbody>
 </table>
 </aside>
-<p>This<a class="footnote-reference superscript" href="#list-note" id="footnote-reference-13" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a> is a second reference to the footnote containing
+<p>This<a class="footnote-reference superscript" href="#list-note" id="footnote-reference-14" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a> is a second reference to the footnote containing
 a bullet. list.</p>
 </section>
 </main>
diff --git a/docutils/test/functional/expected/standalone_rst_html5.html b/docutils/test/functional/expected/standalone_rst_html5.html
index a935198ba..9b95c17c1 100644
--- a/docutils/test/functional/expected/standalone_rst_html5.html
+++ b/docutils/test/functional/expected/standalone_rst_html5.html
@@ -194,7 +194,7 @@ cross-references (<a class="reference internal" href="#example">example</a>), ex
 (<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
 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">[CIT2002]</a>),
+<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;
 a <em>trimmed heart</em> <span class="docutils literal">(U+2665):</span>♥), and <span class="target" id="inline-hyperlink-targets">inline hyperlink targets</span>
 (see <a class="reference internal" href="#targets">Targets</a> below for a reference back to here).  Character-level
@@ -509,13 +509,15 @@ nonexistent footnote: <a href="#system-message-2"><span class="problematic" id="
 </section>
 <section id="citations">
 <h3><a class="toc-backref" href="#toc-entry-18"><span class="sectnum">2.12</span> Citations</a></h3>
-<aside class="citation" id="cit2002" role="note">
+<div role="list" class="citation-list">
+<div class="citation" id="cit2002" role="doc-biblioentry">
 <span class="label"><span class="fn-bracket">[</span>CIT2002<span class="fn-bracket">]</span></span>
 <span class="backrefs">(<a role="doc-backlink" href="#citation-reference-1">1</a>,<a role="doc-backlink" href="#citation-reference-2">2</a>)</span>
 <p>Citations are text-labeled footnotes. They may be
 rendered separately and differently from footnotes.</p>
-</aside>
-<p>Here's a reference to the above, <a class="citation-reference" href="#cit2002" id="citation-reference-2">[CIT2002]</a>, and a <a href="#system-message-3"><span class="problematic" id="citation-reference-3">[nonexistent]_</span></a>
+</div>
+</div>
+<p>Here's a reference to the above, <a class="citation-reference" href="#cit2002" id="citation-reference-2" role="doc-biblioref">[CIT2002]</a>, and a <a href="#system-message-3"><span class="problematic" id="citation-reference-3">[nonexistent]_</span></a>
 citation.</p>
 </section>
 <section id="targets">
diff --git a/docutils/test/functional/input/footnotes.txt b/docutils/test/functional/input/footnotes.txt
index 8c4c464e7..aa25055d9 100644
--- a/docutils/test/functional/input/footnotes.txt
+++ b/docutils/test/functional/input/footnotes.txt
@@ -16,7 +16,7 @@ Here's a reference to the above, [CIT2002]_.
 
 .. [5] this footnote is missing in the standard example document.
 
-Footnotes may contain block elements like lists [#list-note]_ [#]_,
+Footnotes may contain block elements like lists  [#]_ [#list-note]_ [#]_,
 admonitions [#]_, or tables [#]_.
 
 .. [#] #. An ordered list