New responsive style for HTML5.

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

5 files changed, 486 insertions, 10 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index ab63c0933..36eb44226 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -111,9 +111,19 @@ Version 0.17b1
       Support "captionbelow" class value for tables.
       Small fixes and tweaks.
 
-    ``plain.css``: Support numbered figures.
-    
-  - Fix bug #398: properly close link tag to "schema.dcterms".
+* docutils/writers/html5_polyglot/responsive.css
+
+  - New optional stylesheet that adapts to different screen sizes.
+
+* docutils/writers/html5_polyglot/minimal.css
+
+  - Move non-essential styling to ``plain.css``.
+    Support "captionbelow" class value for tables.
+    Small fixes and tweaks.
+
+* docutils/writers/html5_polyglot/plain.css
+
+  - Support numbered figures.
 
 * docutils/writers/latex2e/__init__.py:
 
diff --git a/docutils/docutils.conf b/docutils/docutils.conf
index c7a22a96b..854a62b3a 100644
--- a/docutils/docutils.conf
+++ b/docutils/docutils.conf
@@ -14,7 +14,7 @@ field-name-limit: 20
 

 [html5 writer]

 stylesheet-dirs: docutils/writers/html5_polyglot/

-stylesheet-path: minimal.css, plain.css

+stylesheet-path: minimal.css, responsive.css

 

 # Prevent tools/buildhtml.py from processing certain text files.

 [buildhtml application]

diff --git a/docutils/docutils/writers/html5_polyglot/responsive.css b/docutils/docutils/writers/html5_polyglot/responsive.css
new file mode 100644
index 000000000..b90640b5a
--- /dev/null
+++ b/docutils/docutils/writers/html5_polyglot/responsive.css
@@ -0,0 +1,446 @@
+/* CSS3_ style sheet for the output of Docutils HTML writers.              */
+/* Generic responsive design for all screen sizes.                         */
+/*                                                                         */
+/* :Author: Günter Milde                                                   */
+/*                                                                         */
+/* :Id: $Id$                                                               */
+/* :Copyright: © 2021 Günter Milde.                                        */
+/* :License: Released under the terms of the `2-Clause BSD license`_,      */
+/*    in short:                                                            */
+/*                                                                         */
+/*    Copying and distribution of this file, with or without modification, */
+/*    are permitted in any medium without royalty provided the copyright   */
+/*    notice and this notice are preserved.                                */
+/*                                                                         */
+/*    This file is offered as-is, without any warranty.                    */
+/*                                                                         */
+/* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause     */
+/* .. _CSS3: http://www.w3.org/TR/CSS3                                     */
+
+
+/* General Settings */
+/* ================ */
+
+
+* { box-sizing: border-box; }
+
+body {
+  background-color: #fafaf6;
+  margin: auto;
+}
+main {
+  counter-reset: figure table;
+}
+main, header, footer {
+  background-color: white;
+  line-height: 1.6;
+  /* smooth transition from 5% to 15% (see media queries below) */
+  padding: 0.5rem calc(25% - 5.8rem);
+}
+
+/* Vertical Space (Parskip) */
+p, ol, ul, dl, li,
+div.line-block,
+div.topic,
+table {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+}
+h1, h2, h3, h4, h5, h6,
+dl > dd {
+  margin-bottom: 0.5em;
+}
+/* exceptions */
+p:first-child {
+  margin-top: 0;
+}
+p:last-child {
+  margin-bottom: 0;
+}
+blockquote > table,
+div.topic > table {
+  margin-top: 0;
+  margin-bottom: 0;
+}
+
+/* Indented Blocks */
+blockquote,
+figure,
+div.topic {
+  margin: 1em 2%;
+  padding-left: 1em;
+}
+div.line-block div.line-block,
+pre, dd, dl.option-list {
+  margin-left: calc(2% + 1em);
+}
+
+/* Object styling */
+/* ============== */
+
+footer, header,
+aside.sidebar, .marginal {
+  font-size: small;
+}
+
+/* Frontmatter */
+blockquote.dedication,
+div.topic.dedication {
+  padding: 0;
+  margin: 1.4em 0;
+  /* text-align: center; */
+  font-style: italic;
+  font-size: large;
+}
+.dedication p.topic-title {
+  display: none;
+}
+
+blockquote p.attribution,
+div.topic p.attribution {
+  text-align: right;
+}
+
+/* Table of Contents */
+div.topic.contents {
+  padding: 0;
+}
+ul.auto-toc > li > p {
+  padding-left: 1em;
+  text-indent: -1em;
+}
+div.topic.contents ul {
+  padding-left: 1em;
+}
+
+/* Transitions */
+hr {
+  margin: 1em 10%;
+}
+
+/* Lists */
+
+ul, ol {
+  padding-left: 1.1em;
+}
+dl.field-list > dd,
+dl.docinfo > dd {
+  margin-left: 6.4em;
+}
+dl.option-list > dd {
+  margin-left: 20%;
+}
+/* run-in: start field-body on same line after long field names */
+dl.field-list.run-in > dd p {
+  display: block;
+}
+/* "description style" like in most dictionaries, encyclopedias etc. */
+dl.description > dt {
+  clear: left;
+  float: left;
+  margin: 0;
+  padding: 0;
+  padding-right: 0.5em;
+  font-weight: bold;
+}
+dl.description > dd:after {
+  display: block;
+  content: "";
+  clear: both;
+}
+/* start lists nested in description/field lists on new line */
+dd > dl:first-child,
+dd > ul:first-child,
+dd > ol:first-child {
+    clear: left;
+}
+
+/* Footnotes and Citations */
+/* TODO: use <aside> */
+dl.footnote {
+  font-size: small;
+  padding-left: 0.5em;
+  border-left: solid;
+  border-left-width: thin;
+}
+
+/* Images, Figures, and Tables */
+img {
+  display: block;
+}
+p > img, p > a > img,
+figure > img, figure > a > img {
+  display: inline;
+}
+
+table tr {
+  text-align: left;
+}
+
+/* th { vertical-align: bottom; } */
+/* "booktabs" style (no vertical lines) */
+table.booktabs {
+  border-top: 2px solid;
+  border-bottom: 2px solid;
+}
+table.booktabs * {
+  border: 0;
+}
+table.booktabs th {
+  border-bottom: thin solid;
+}
+
+figcaption,
+table > caption {
+  /*   font-size: small; */
+  font-style: italic;
+}
+figcaption > .legend {
+  font-size: small;
+  font-style: initial;
+}
+
+figure.numbered > figcaption > p:before {
+  counter-increment: figure;
+  content: "Figure " counter(figure) ": ";
+  font-weight: bold;
+  font-style: initial;
+}
+table.numbered > caption:before {
+  counter-increment: table;
+  content: "Table " counter(table) ": ";
+  font-weight: bold;
+  font-style: initial;
+}
+
+/* Admonitions and System Messages */
+div.admonition,
+div.system-message {
+  border-style: solid;
+  border-color: silver;
+  border-width: thin;
+  margin: 1em 2%;
+  padding: 0.5em;
+}
+div.caution p.admonition-title,
+div.attention p.admonition-title,
+div.danger p.admonition-title,
+div.warning p.admonition-title,
+div.error {
+  color: maroon;
+}
+div.system-message > p > span.literal {
+  overflow-wrap: break-word;
+}
+
+/* Literal and Code */
+pre {
+  font-size: 0.9;
+  /* overflow: auto; */
+}
+pre.code .ln { color: gray; } /* line numbers */
+/* basic highlighting: for a complete scheme, see */
+/* http://docutils.sourceforge.net/sandbox/stylesheets/ */
+pre.code .comment, code .comment { color: #5C6576 }
+pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
+pre.code .literal.string, code .literal.string { color: #0C5404 }
+pre.code .name.builtin, code .name.builtin { color: #352B84 }
+pre.code .deleted, code .deleted { background-color: #DEB0A1}
+pre.code .inserted, code .inserted { background-color: #A3D289}
+
+.sans {
+    font-family: "Gill Sans", "Gill Sans MT", Calibri, "Lucida Sans", "Noto Sans", sans-serif;
+    letter-spacing: .02em;
+}
+
+/* Hyperlink References */
+/* underline that clears descenders */
+a {
+  text-decoration: none;
+  text-decoration-skip-ink: auto; /* nonstandard selector */
+}
+/* Wrap links at any place, if this is the only way to prevent overflow */
+a:link{
+  overflow-wrap: break-word;
+}
+.contents a, a.toc-backref, a.citation-reference {
+  overflow-wrap: inherit;
+}
+
+/* Undecorated Links */
+/* a.footnote-reference, a.fn-backref, .fn-backref a, */
+/* a.citation-reference, */
+.citation a.fn-backref,
+.contents a, a.toc-backref {
+  color: inherit;
+}
+a:link:hover {
+  text-decoration: underline;
+}
+
+/* highlight the active ToC entry */
+.auto-toc :target {
+  background-color: orange;
+}
+
+/* Block Alignment */
+/* Let content flow to the side of aligned images and figures */
+
+/* no floats around this elements */
+dl.footnote, dl.citation, /* errors with internal floats */
+footer, header, hr,
+h1, h2, h3 {
+  clear: both;
+}
+
+img.align-left,
+figure.align-left,
+table.align-left {
+  margin-left: 0;
+  padding-left: 0;
+  margin-right: 0.5em;
+  clear: left;
+  float: left;
+}
+img.align-right,
+figure.align-right,
+table.align-right {
+  margin-left: 0.5em;
+  margin-right: 0;
+  clear: right;
+  float: right;
+}
+
+/* Margin Elements */
+/* see below for screen size dependent rules */
+aside.sidebar,
+.marginal,
+.admonition.marginal {
+  max-width: min(40%, 20rem);
+  background-color: #efefea;
+  margin: 0.5em 0 0.5em 1em;
+  padding: 0.5em;
+  clear: right;
+  float: right;
+}
+aside.sidebar {
+  width: 40%;
+}
+
+/* Adaptive page layout */
+
+/* smaller margins and no floating elements for small screens */
+/* main text less than 40 characters/line */
+@media (max-width: 30em) {
+  main, header, footer {
+    padding: 0.5rem 5%;
+    line-height: 1.4
+  }
+  aside.sidebar,
+  .marginal,
+  .admonition.marginal {
+    width: auto;
+    max-width: 100%;
+    float: none;
+  }
+  dl.option-list,
+  pre {
+    margin-left: 0;
+  }
+  dl.field-list > dd {
+    margin-left: 4em;
+  }
+  dl.field-list.narrow > dd,
+  dl.docinfo > dd,
+  dl.option-list > dd {
+    margin-left: 2.4em;
+  }
+}
+
+/* Move ToC to the left */
+/* Main text width before: 70% ≙ 35em ≙ 75…95 chrs (Dejavu/Times) */
+/*                 after:      ≳ 30em ≙ 54…70 chrs (Dejavu/Times) */
+@media (min-width: 54em) {
+  main, header, footer {
+    margin-left: min(15%, 18rem);
+    padding-left: 15%;
+/*     padding-right: 14%; */
+    padding-right: 7%;
+  }
+  main > div.topic.contents {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: min(25%, 28em);
+    height: 100vh;
+    margin: 0;
+    background-color: #fafaf6;
+    padding: 1em 2% 0 2%;
+    overflow: auto;
+  }
+  main > div.topic.contents > * {
+    padding-left: 0;
+  }
+  main > div.topic.contents ul:not(.auto-toc) {
+    list-style-type: square;
+/*     padding-left: 1em; */
+  }
+  div.topic.contents ul > li::marker {
+    color: grey;
+  }
+}
+
+@media (min-width: 70em) {
+  dl.field-list > dd,
+  dl.docinfo > dd {
+    margin-left: 9em;
+  }
+
+/* limit main text to 50em ≙ 85…100 characters DejaVu rsp. …120 Times */
+@media (min-width: 80em) {
+  main, header, footer {
+    padding-right: calc(70% - 50em);
+  }
+  /* Move marginalia to 6rem from right border */
+  /* TODO: why does this fail ??  	       */
+  /* aside.sidebar,	                       */
+  /* .marginal,		    	               */
+  /* .admonition.marginal { 	               */
+  /*   margin-right: calc(6rem - 15vh);        */
+  /* } 		     	       	 	       */
+}
+
+@media (min-width: 92em) {
+  /* move marginalia into the margin */
+  aside.sidebar,
+  .admonition.marginal,
+  .marginal {
+    margin-right: -12rem;
+  }
+}
+
+@media (min-width: 106em) {
+  /* move marginalia out of main text area */
+  aside.sidebar,
+  .admonition.marginal,
+  .marginal {
+    width: 20rem;
+    /* background-color: inherit; */
+    margin-right: -22rem;
+  }
+}
+
+@media (min-width: 117em) {
+  /* maximal sensible width of main area reached */
+  main, header, footer {
+    width: 98rem;
+    margin-right: 0;
+    padding-left: 18rem;
+    padding-right: 30rem;
+  }
+  aside.sidebar,
+  .marginal,
+  .admonition.marginal {
+    margin-right: -24rem; /* move into the padding, 6rem from border */
+  }
+}
diff --git a/docutils/test/functional/expected/standalone_rst_html5.html b/docutils/test/functional/expected/standalone_rst_html5.html
index 56b143ade..c0da96d80 100644
--- a/docutils/test/functional/expected/standalone_rst_html5.html
+++ b/docutils/test/functional/expected/standalone_rst_html5.html
@@ -12,6 +12,7 @@
 <meta name="dcterms.rights" content="This document has been placed in the public domain. You may do with it as you wish. You may copy, modify, redistribute, reattribute, sell, buy, rent, lease, destroy, or improve it, quote it at length, excerpt, incorporate, collate, fold, staple, or mutilate it, or do anything else to it that your or anyone else's heart desires." />
 <meta content="reStructuredText, test, parser" name="keywords" />
 <meta content="A test document, containing at least one example of each reStructuredText construct." lang="en" name="description" xml:lang="en" />
+<meta content="width=device-width, initial-scale=1" name="viewport" />
 <link rel="schema.dcterms" href="http://purl.org/dc/terms/"/>
 <link rel="stylesheet" href="../input/data/minimal.css" type="text/css" />
 <link rel="stylesheet" href="../input/data/plain.css" type="text/css" />
@@ -855,12 +856,15 @@ allowed (e.g. inside a directive).</p>
 <dd><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>
 </dd>
 <dt class="label" id="footnote-15"><span class="brackets"><a class="fn-backref" href="#footnote-reference-29">15</a></span></dt>
-<dd><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>
+<dd><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>
 </dd>
 <dt class="label" id="footnote-16"><span class="brackets"><a class="fn-backref" href="#footnote-reference-30">16</a></span></dt>
-<dd><p><a class="reference external" href="https://html.spec.whatwg.org/#text-level-semantics">https://html.spec.whatwg.org/#text-level-semantics</a></p>
+<dd><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>
 </dd>
 <dt class="label" id="footnote-17"><span class="brackets"><a class="fn-backref" href="#footnote-reference-31">17</a></span></dt>
+<dd><p><a class="reference external" href="https://html.spec.whatwg.org/#text-level-semantics">https://html.spec.whatwg.org/#text-level-semantics</a></p>
+</dd>
+<dt class="label" id="footnote-18"><span class="brackets"><a class="fn-backref" href="#footnote-reference-32">18</a></span></dt>
 <dd><p><a class="reference external" href="https://html.spec.whatwg.org/multipage/edits.html">https://html.spec.whatwg.org/multipage/edits.html</a></p>
 </dd>
 </dl>
@@ -1254,7 +1258,13 @@ crunchy, now would it?</p></td>
 <ul>
 <li><p>Use only meta keywords recognized by HTML 5.
 Add HTML5-compatible meta tags for docinfo items
-&quot;authors&quot;, &quot;date&quot;, and &quot;copyright&quot;.</p></li>
+&quot;authors&quot;, &quot;date&quot;, and &quot;copyright&quot;.</p>
+<div class="admonition hint">
+<p class="admonition-title">Hint</p>
+<p>Use 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">15</a> to tell mobile browsers
+to use the device-width as viewport.</p>
+</div>
+</li>
 <li><p>Set table column widths with &lt;style=&quot;width: ...&quot;&gt;, not &quot;width&quot; argument.</p></li>
 <li><p>Horizontal alignment of table heads with CSS.</p></li>
 <li><p>Field lists as styled definition lists.</p></li>
@@ -1265,7 +1275,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-15" id="footnote-reference-29">15</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-16" id="footnote-reference-30">16</a>.</p>
 </li>
 <li><p>Use HTML text-level 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
@@ -1501,7 +1511,7 @@ from the <a class="reference external" href="http://tug.ctan.org/tex-archive/mac
 <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>
 <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-16" id="footnote-reference-30">16</a> and their reStructuredText equivalents.</p>
+semantics</a> <a class="footnote-reference brackets" href="#footnote-17" id="footnote-reference-31">17</a> and their reStructuredText equivalents.</p>
 <dl class="description">
 <dt>a</dt>
 <dd><p>Hyperlinks</p>
@@ -1707,7 +1717,7 @@ roles to make sense.</p>
 </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-17" id="footnote-reference-31">17</a> and their
+<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">18</a> and their
 reStructuredText equivalents are:</p>
 <dl class="description">
 <dt>ins</dt>
diff --git a/docutils/test/functional/input/data/html5-features.txt b/docutils/test/functional/input/data/html5-features.txt
index 6c9e5087d..8f6475b08 100644
--- a/docutils/test/functional/input/data/html5-features.txt
+++ b/docutils/test/functional/input/data/html5-features.txt
@@ -5,6 +5,16 @@ Changes to the `html4css1` Writer
   Add HTML5-compatible meta tags for docinfo items
   "authors", "date", and "copyright".
 
+  .. hint::
+  
+    Use a `viewport meta tag`__ to tell mobile browsers
+    to use the device-width as viewport.
+
+    .. meta::
+       :viewport: width=device-width, initial-scale=1
+
+    __ https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag
+
 * Set table column widths with <style="width: ...">, not "width" argument.
 
 * Horizontal alignment of table heads with CSS.