Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[8775] trunk/docutils
|
From: <mi...@us...> - 2021-06-25 20:57:43
|
Revision: 8775
http://sourceforge.net/p/docutils/code/8775
Author: milde
Date: 2021-06-25 20:57:36 +0000 (Fri, 25 Jun 2021)
Log Message:
-----------
HTM5 Use semantic tags for topics, admontions, system-messages, and toc.
<aside> for topics (except abstract and toc), admonitions,
and system messages.
<nav> and DPub Aria role="doc-toc" for the Table of Contents.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docutils/writers/_html_base.py
trunk/docutils/docutils/writers/html5_polyglot/__init__.py
trunk/docutils/docutils/writers/html5_polyglot/minimal.css
trunk/docutils/docutils/writers/html5_polyglot/plain.css
trunk/docutils/docutils/writers/html5_polyglot/responsive.css
trunk/docutils/docutils/writers/html5_polyglot/tuftig.css
trunk/docutils/test/functional/expected/footnotes_html5.html
trunk/docutils/test/functional/expected/standalone_rst_html5.html
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2021-06-25 20:57:05 UTC (rev 8774)
+++ trunk/docutils/HISTORY.txt 2021-06-25 20:57:36 UTC (rev 8775)
@@ -40,7 +40,7 @@
- `Meta` directive class (moved from html.py) inserts `meta`
(instead of `pending`) nodes.
-* docutils/tools/math/math2html, docutils/writers/html5_polyglot/math.css
+* docutils/tools/math/math2html;
- Fix bug #244 Wrong subscript/superscript order with
``--math-output=HTML``.
@@ -62,7 +62,8 @@
they are present also without CSS and when copying text.
Adapt ``minimal.css``.
- - Use semantic tag <aside> for footnote text and citations.
+ - Use semantic tags <aside> and <nav> for footnote text and citations,
+ topics, admonitions, and system-messages.
- Do not add "compound-first", "compound-middle", or "compound-last" to
elements nested in a compound (no change with `html4css1`).
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2021-06-25 20:57:05 UTC (rev 8774)
+++ trunk/docutils/RELEASE-NOTES.txt 2021-06-25 20:57:36 UTC (rev 8775)
@@ -22,10 +22,6 @@
* `html5` writer:
- - Use semantic tags <aside> for topics
- (except abstract), admonitions, and system messages, and <nav> for
- the Table of Contents.
-
- Use <summary> and <details> tags for term and definition of a
definition list with class value "details".
@@ -83,7 +79,9 @@
Write footnote brackets and field term colons to HTML, so that they
are present also without CSS and when copying text.
- Use semantic tag <aside> for footnote text and citations.
+ Use semantic tag <aside> for footnote text and citations,
+ topics (except abstract and toc), admonitions, and system messages
+ Use <nav> for the Table of Contents.
Do not add "compound-first", "compound-middle", or "compound-last" to
elements nested in a compound. Use child selector and "first-child",
Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py 2021-06-25 20:57:05 UTC (rev 8774)
+++ trunk/docutils/docutils/writers/_html_base.py 2021-06-25 20:57:36 UTC (rev 8775)
@@ -520,10 +520,10 @@
self.depart_docinfo_item()
def visit_admonition(self, node):
- self.body.append(self.starttag(node, 'div', classes=['admonition']))
+ self.body.append(self.starttag(node, 'aside', classes=['admonition']))
def depart_admonition(self, node=None):
- self.body.append('</div>\n')
+ self.body.append('</aside>\n')
attribution_formats = {'dash': (u'\u2014', ''),
'parentheses': ('(', ')'),
@@ -1499,7 +1499,7 @@
self.body.append('</sup>')
def visit_system_message(self, node):
- self.body.append(self.starttag(node, 'div', CLASS='system-message'))
+ self.body.append(self.starttag(node, 'aside', CLASS='system-message'))
self.body.append('<p class="system-message-title">')
backref_text = ''
if len(node['backrefs']):
@@ -1525,7 +1525,7 @@
self.encode(node['source']), line, backref_text))
def depart_system_message(self, node):
- self.body.append('</div>\n')
+ self.body.append('</aside>\n')
def visit_table(self, node):
atts = {'classes': self.settings.table_style.replace(',', ' ').split()}
Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2021-06-25 20:57:05 UTC (rev 8774)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2021-06-25 20:57:36 UTC (rev 8775)
@@ -402,14 +402,27 @@
self.body.append('</aside>\n')
self.in_sidebar = False
+ # Use new HTML5 element <aside> or <nav>
# Add class value to <body>, if there is a ToC in the document
- # (see responsive.css how this is used for sidebar navigation).
- # TODO: use the new HTML5 element <aside>?
+ # (see responsive.css how this is used for a navigation sidebar).
def visit_topic(self, node):
- if ('contents' in node['classes']
- and isinstance(node.parent, nodes.document)):
- self.body_prefix[0] = '</head>\n<body class="with-toc">\n'
- self.body.append(self.starttag(node, 'div', CLASS='topic'))
+ atts = {'classes': ['topic']}
+ if 'contents' in node['classes']:
+ node.html_tagname = 'nav'
+ del(atts['classes'])
+ if isinstance(node.parent, nodes.document):
+ atts['role'] = 'doc-toc'
+ self.body_prefix[0] = '</head>\n<body class="with-toc">\n'
+ elif 'abstract' in node['classes']:
+ node.html_tagname = 'div'
+ atts['role'] = 'doc-abstract'
+ elif 'dedication' in node['classes']:
+ node.html_tagname = 'div'
+ atts['role'] = 'doc-dedication'
+ else:
+ node.html_tagname = 'aside'
+ self.body.append(self.starttag(node, node.html_tagname, **atts))
def depart_topic(self, node):
- self.body.append('</div>\n')
+ self.body.append('</%s>\n'%node.html_tagname)
+ del(node.html_tagname)
Modified: trunk/docutils/docutils/writers/html5_polyglot/minimal.css
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/minimal.css 2021-06-25 20:57:05 UTC (rev 8774)
+++ trunk/docutils/docutils/writers/html5_polyglot/minimal.css 2021-06-25 20:57:36 UTC (rev 8775)
@@ -42,8 +42,8 @@
h1 + p.subtitle {
font-size: 1.6em;
}
-h2 + p.section-subtitle, a.toc-backref {
- color: black;
+a.toc-backref {
+ color: inherit;
text-decoration: none;
}
@@ -77,10 +77,8 @@
p:last-child { margin-bottom: 0; }
/* Table of Contents */
-.topic.contents { margin: 0.5em 0; }
-.topic.contents ul.auto-toc {
+.contents ul.auto-toc { /* section numbers present */
list-style-type: none;
- padding-left: 1.5em;
}
/* Enumerated Lists */
@@ -222,16 +220,12 @@
}
/* Text Blocks */
-blockquote,
-div.topic,
-aside.topic {
- margin: 1em 2em;
-}
+.topic { margin: 1em 2em; }
.sidebar,
.admonition,
.system-message {
+ margin: 1em 2em;
border: thin solid;
- margin: 1em 2em;
padding: 0.5em 1em;
}
.sidebar {
Modified: trunk/docutils/docutils/writers/html5_polyglot/plain.css
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/plain.css 2021-06-25 20:57:05 UTC (rev 8774)
+++ trunk/docutils/docutils/writers/html5_polyglot/plain.css 2021-06-25 20:57:36 UTC (rev 8775)
@@ -45,6 +45,15 @@
border: none;
}
+/* Table of Contents */
+ul.auto-toc > li > p {
+ padding-left: 1em;
+ text-indent: -1em;
+}
+nav.contents ul {
+ padding-left: 1em;
+}
+
/* Transitions */
hr.docutils {
width: 80%;
@@ -58,7 +67,6 @@
/* vertical space (parskip) */
p, ol, ul, dl, li,
div.line-block,
-div.topic,
.footnote, .citation,
div > math,
table {
@@ -114,8 +122,8 @@
/* Bibliographic Fields */
-/* generally, bibliographic fields use special definition list dl.docinfo */
-/* but dedication and abstract are placed into "topic" divs */
+/* generally, bibliographic fields use dl.docinfo */
+/* but dedication and abstract are placed into divs */
div.abstract p.topic-title {
text-align: center;
}
@@ -137,14 +145,10 @@
font-family: monospace;
}
-/* Block Quotes */
-blockquote > table,
-div.topic > table {
- margin-top: 0;
- margin-bottom: 0;
-}
+/* Block Quotes and Topics */
+bockquote { margin: 1em 2em; }
blockquote p.attribution,
-div.topic p.attribution {
+.topic p.attribution {
text-align: right;
margin-left: 20%;
}
Modified: trunk/docutils/docutils/writers/html5_polyglot/responsive.css
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/responsive.css 2021-06-25 20:57:05 UTC (rev 8774)
+++ trunk/docutils/docutils/writers/html5_polyglot/responsive.css 2021-06-25 20:57:36 UTC (rev 8775)
@@ -47,7 +47,7 @@
/* Vertical Space (Parskip) */
p, ol, ul, dl, li,
div.line-block,
-div.topic,
+.topic,
.footnote, .citation,
div > math,
table {
@@ -58,14 +58,9 @@
dl > dd {
margin-bottom: 0.5em;
}
-blockquote > table,
-div.topic > table {
- margin-top: 0;
- margin-bottom: 0;
-}
/* Indented Blocks */
-blockquote, figure, div.topic {
+blockquote, figure, .topic {
margin: 1em 2%;
padding-left: 1em;
}
@@ -83,7 +78,7 @@
}
/* Frontmatter */
-div.topic.dedication {
+div.dedication {
padding: 0;
margin: 1.4em 0;
font-style: italic;
@@ -94,39 +89,34 @@
}
blockquote p.attribution,
-div.topic p.attribution {
+.topic p.attribution {
text-align: right;
}
/* Table of Contents */
-nav.contents,
-div.topic.contents {
- padding: 0;
-}
ul.auto-toc > li > p {
padding-left: 1em;
text-indent: -1em;
}
-nav.contents ul,
-div.topic.contents ul {
+nav.contents ul {
padding-left: 1em;
}
-main > div.topic.contents ul:not(.auto-toc) {
+main > nav.contents ul:not(.auto-toc) {
list-style-type: square;
}
-main > div.topic.contents ul ul:not(.auto-toc) {
+main > nav.contents ul ul:not(.auto-toc) {
list-style-type: disc;
}
-main > div.topic.contents ul ul ul:not(.auto-toc) {
+main > nav.contents ul ul ul:not(.auto-toc) {
list-style-type: '\2023\ ';
}
-main > div.topic.contents ul ul ul ul:not(.auto-toc) {
+main > nav.contents ul ul ul ul:not(.auto-toc) {
list-style-type: '\2B29\ ';
}
-main > div.topic.contents ul ul ul ul ul:not(.auto-toc) {
+main > nav.contents ul ul ul ul ul:not(.auto-toc) {
list-style-type: '\00B7\ ';
}
-div.topic.contents ul > li::marker {
+nav.contents ul > li::marker {
color: grey;
}
@@ -277,17 +267,16 @@
.contents a, a.toc-backref, a.citation-reference {
overflow-wrap: inherit;
}
-/* Undecorated Links */
+/* Undecorated Links (see also minimal.css) */
/* a.citation-reference, */
/* .contents a, */
-.citation a.fn-backref,
-a.toc-backref {
+.citation a.fn-backref {
color: inherit;
}
a:link:hover {
text-decoration: underline;}
/* highlight the active ToC entry */
-.topic.contents :target {
+.contents :target {
background-color: #d2e6ec;
}
@@ -392,7 +381,7 @@
padding-left: min(22%, 22rem);
padding-right: 7%;
}
- main > div.topic.contents { /* exclude local ToCs */
+ main > nav.contents { /* global ToC */
position: fixed;
top: 0;
left: 0;
@@ -403,7 +392,7 @@
padding: 1em 2% 0 2%;
overflow: auto;
}
- main > div.topic.contents > * {
+ main > nav.contents > * {
padding-left: 0;
}
}
Modified: trunk/docutils/docutils/writers/html5_polyglot/tuftig.css
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/tuftig.css 2021-06-25 20:57:05 UTC (rev 8774)
+++ trunk/docutils/docutils/writers/html5_polyglot/tuftig.css 2021-06-25 20:57:36 UTC (rev 8775)
@@ -63,15 +63,10 @@
p:last-child {
margin-bottom: 0;
}
-blockquote > table,
-div.topic > table {
- margin-top: 0;
- margin-bottom: 0;
-}
/* Indented Blocks */
blockquote,
-div.topic {
+.topic {
/* background-color: Honeydew; */
margin: 0.5em 2%;
padding-left: 1em;
@@ -138,7 +133,7 @@
}
/* Dedication and Abstract */
-div.topic.dedication {
+div.dedication {
padding: 0;
margin-left: 0;
font-style: italic;
@@ -151,12 +146,12 @@
/* Attribution */
blockquote p.attribution,
-div.topic p.attribution {
+.topic p.attribution {
text-align: right;
}
/* Table of Contents */
-div.topic.contents {
+nav.contents {
padding: 0;
font-style: italic;
}
@@ -164,7 +159,7 @@
padding-left: 1em;
text-indent: -1em;
}
-div.topic.contents ul {
+nav.contents ul {
padding-left: 1em;
}
@@ -517,10 +512,10 @@
/* Fullwidth Elements */
h1.title, p.subtitle,
dl.docinfo,
- div.topic.abstract,
- div.topic.dedication,
- div.topic.contents,
- div.system-message,
+ div.abstract,
+ div.dedication,
+ nav.contents,
+ aside.system-message,
pre,
.fullwidth,
.fullwidth img,
@@ -538,7 +533,7 @@
main, header, footer {
padding-left: 30%;
}
- main > div.topic.contents {
+ main > nav.contents {
position: fixed;
top: 0;
left: 0;
@@ -550,7 +545,7 @@
padding: 5.5em 2%;
overflow: auto;
}
- main > div.topic.contents > * {
+ main > nav.contents > * {
padding-left: 0;
}
}
Modified: trunk/docutils/test/functional/expected/footnotes_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/footnotes_html5.html 2021-06-25 20:57:05 UTC (rev 8774)
+++ trunk/docutils/test/functional/expected/footnotes_html5.html 2021-06-25 20:57:36 UTC (rev 8775)
@@ -98,11 +98,11 @@
</aside>
<aside class="footnote superscript" id="footnote-9" role="note">
<span class="label"><span class="fn-bracket">[</span><a class="fn-backref" href="#footnote-reference-12">9</a><span class="fn-bracket">]</span></span>
-<div class="admonition note">
+<aside class="admonition note">
<p class="admonition-title">Note</p>
<p>This is a note in a note.</p>
-</div>
</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>
<table>
Modified: trunk/docutils/test/functional/expected/standalone_rst_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_html5.html 2021-06-25 20:57:05 UTC (rev 8774)
+++ trunk/docutils/test/functional/expected/standalone_rst_html5.html 2021-06-25 20:57:36 UTC (rev 8775)
@@ -68,11 +68,11 @@
<p>Like this.</p>
</dd>
</dl>
-<div class="dedication topic">
+<div class="topic dedication" role="doc-dedication">
<p class="topic-title">Dedication</p>
<p>For Docutils users & co-developers.</p>
</div>
-<div class="abstract topic">
+<div class="topic abstract" role="doc-abstract">
<p class="topic-title">Abstract</p>
<p>This is a test document, containing at least one example of each
reStructuredText construct.</p>
@@ -82,7 +82,7 @@
<!-- Above is the document title, and below is the subtitle.
They are transformed from section titles after parsing. -->
<!-- bibliographic fields (which also require a transform): -->
-<div class="contents topic" id="table-of-contents">
+<nav class="contents" id="table-of-contents" role="doc-toc">
<p class="topic-title">Table of Contents</p>
<ul class="auto-toc simple">
<li><p><a class="reference internal" href="#structural-elements" id="toc-entry-1"><span class="sectnum">1</span> Structural Elements</a></p>
@@ -159,7 +159,7 @@
</li>
<li><p><a class="reference internal" href="#error-handling" id="toc-entry-52"><span class="sectnum">4</span> Error Handling</a></p></li>
</ul>
-</div>
+</nav>
<section id="structural-elements">
<h2><a class="toc-backref" href="#toc-entry-1"><span class="sectnum">1</span> Structural Elements</a></h2>
<section id="section-title">
@@ -546,7 +546,7 @@
</section>
<section id="directives">
<h3><a class="toc-backref" href="#toc-entry-22"><span class="sectnum">2.14</span> Directives</a></h3>
-<div class="contents local topic" id="contents">
+<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>
@@ -560,7 +560,7 @@
<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>
</ul>
-</div>
+</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"><span class="fn-bracket">[</span>13<span class="fn-bracket">]</span></a>.</p>
<section id="document-parts">
@@ -763,27 +763,27 @@
</section>
<section id="admonitions">
<h4><a class="toc-backref" href="#toc-entry-56"><span class="sectnum">2.14.4</span> Admonitions</a></h4>
-<div class="admonition attention">
+<aside class="admonition attention">
<p class="admonition-title">Attention!</p>
<p>Directives at large.</p>
-</div>
-<div class="admonition caution">
+</aside>
+<aside class="admonition caution">
<p class="admonition-title">Caution!</p>
<p>Don't take any wooden nickels.</p>
-</div>
-<div class="admonition danger">
+</aside>
+<aside class="admonition danger">
<p class="admonition-title">!DANGER!</p>
<p>Mad scientist at work!</p>
-</div>
-<div class="admonition error">
+</aside>
+<aside class="admonition error">
<p class="admonition-title">Error</p>
<p>Does not compute.</p>
-</div>
-<div class="admonition hint">
+</aside>
+<aside class="admonition hint">
<p class="admonition-title">Hint</p>
<p>It's bigger than a bread box.</p>
-</div>
-<div class="admonition important">
+</aside>
+<aside class="admonition important">
<p class="admonition-title">Important</p>
<ul class="simple">
<li><p>Wash behind your ears.</p></li>
@@ -791,24 +791,24 @@
<li><p>Call your mother.</p></li>
<li><p>Back up your data.</p></li>
</ul>
-</div>
-<div class="admonition note">
+</aside>
+<aside class="admonition note">
<p class="admonition-title">Note</p>
<p>This is a note.</p>
-</div>
-<div class="admonition tip">
+</aside>
+<aside class="admonition tip">
<p class="admonition-title">Tip</p>
<p>15% if the service is good.</p>
-</div>
-<div class="admonition warning">
+</aside>
+<aside class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Strong prose may provoke extreme mental exertion.
Reader discretion is strongly advised.</p>
-</div>
-<div class="admonition admonition-and-by-the-way">
+</aside>
+<aside class="admonition admonition-and-by-the-way">
<p class="admonition-title">And, by the way...</p>
<p>You can make up your own admonition too.</p>
-</div>
+</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>
@@ -824,10 +824,10 @@
</aside>
<p>A <em>topic</em> is like a block quote with a title, or a self-contained section
with no subsections.</p>
-<div class="topic">
+<aside class="topic">
<p class="topic-title">Topic Title</p>
<p>This is a topic.</p>
-</div>
+</aside>
<p>A <em>rubric</em> is like an informal heading that doesn't correspond to the
document's structure. It is typically highlighted in red (hence the name).</p>
<p class="rubric">This is a rubric</p>
@@ -994,10 +994,10 @@
<p>a paragraph followed by a comment,</p>
<!-- this is a comment -->
<p>a paragraph, a</p>
-<div class="admonition note">
+<aside class="admonition note">
<p class="admonition-title">Note</p>
<p>with content</p>
-</div>
+</aside>
<p>and the final paragraph of the compound 7.</p>
</div>
</section>
@@ -1779,26 +1779,26 @@
</section>
<section class="system-messages">
<h2>Docutils System Messages</h2>
-<div class="system-message" id="system-message-1">
+<aside class="system-message" id="system-message-1">
<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 99); <em><a href="#problematic-1">backlink</a></em></p>
<p>Undefined substitution referenced: "problematic".</p>
-</div>
-<div class="system-message" id="system-message-2">
+</aside>
+<aside class="system-message" id="system-message-2">
<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 387); <em><a href="#footnote-reference-8">backlink</a></em></p>
<p>Unknown target name: "5".</p>
-</div>
-<div class="system-message" id="system-message-3">
+</aside>
+<aside class="system-message" id="system-message-3">
<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 396); <em><a href="#citation-reference-3">backlink</a></em></p>
<p>Unknown target name: "nonexistent".</p>
-</div>
-<div class="system-message" id="system-message-4">
+</aside>
+<aside class="system-message" id="system-message-4">
<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 423); <em><a href="#problematic-2">backlink</a></em></p>
<p>Unknown target name: "hyperlink reference without a target".</p>
-</div>
-<div class="system-message" id="system-message-5">
+</aside>
+<aside class="system-message" id="system-message-5">
<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 436); <em><a href="#problematic-3">backlink</a></em></p>
<p>Duplicate target name, cannot be used as a unique reference: "duplicate target names".</p>
-</div>
+</aside>
</section>
</main>
<footer>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
