Small documentation updates and fixes.

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

16 files changed, 158 insertions, 126 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 36eb44226..5e9ea5b6a 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -21,16 +21,13 @@ Version 0.17b1
 
 * General
 
-  - Fix bug #385: Import of language modules.
-  - Use importlib.import_module() to programmatically import modules.
-  - Remove legacy LaTeX stylesheet ``docutils-05-compat.sty``.
   - Installing with ``setup.py`` now requires ``setuptools``.
     Alternatively, install with `pip`_ (or "manually").
-  - Apply patch for bug #399 Fixes in Korean translation.
+  - Use importlib.import_module() to programmatically import modules.
+  - Fix bug #385: Import of language modules.
 
   .. _pip: https://pypi.org/project/pip/
 
-
 * docutils/MANIFEST.in
 
   - Exclude test outputs.
@@ -39,10 +36,11 @@ Version 0.17b1
 
   - VersionInfo: ValueError for invalid values, fix comparison to tuples.
 
-*  docutils/languages/ar.py
-   docutils/parsers/rst/languages/ar.py:
+* docutils/languages/  
+  docutils/parsers/rst/languages/
 
   - Apply patch # 177 Arabic mappings by Shahin.
+  - Apply patch for bug #399 Fixes in Korean translation.
 
 * docutils/nodes.py
 
@@ -55,8 +53,8 @@ Version 0.17b1
 
 * docutils/parsers/recommonmark_wrapper.py
 
-  - New file. An experimental wrapper to integrate the
-    `recommonmark`__ Markdown parser for use with stock Docutils.
+  - New, experimental wrapper to integrate the
+    `recommonmark`__ Markdown parser for use with Docutils.
 
     __ https://pypi.org/project/recommonmark/
 
@@ -67,7 +65,6 @@ Version 0.17b1
 * docutils/parsers/rst/directives/html.py
 
   - Make "meta" elements available for "latex" and "odt".
-    (Basic "odt" support exists, "latex" support is planned.)
 
 * docutils/parsers/rst/directives/misc.py
 
@@ -89,7 +86,7 @@ Version 0.17b1
 
   - Implement feature request #40 `Option to embed images as data URI`.
 
-* docutils/writers/html5_polyglot/
+* docutils/writers/html5_polyglot/__init__.py
 
   - Use the new semantic tags <main>, <section>, <header>,
     <footer>, <aside>, <figure>, and <figcaption>.
@@ -106,11 +103,6 @@ Version 0.17b1
     Use <ins> and <del> if a matching class value
     is found in `inline`, `literal`, or `container` elements.
 
-  - ``minimal.css``:
-      Move non-essential styling from  to ``plain.css``.
-      Support "captionbelow" class value for tables.
-      Small fixes and tweaks.
-
 * docutils/writers/html5_polyglot/responsive.css
 
   - New optional stylesheet that adapts to different screen sizes.
@@ -124,6 +116,22 @@ Version 0.17b1
 * docutils/writers/html5_polyglot/plain.css
 
   - Support numbered figures.
+  - Fix bug #398: properly close link tag to "schema.dcterms".
+
+* docutils/writers/html5_polyglot/responsive.css
+
+  - New optional stylesheet for better readability on different
+    screens.
+
+* docutils/writers/html5_polyglot/minimal.css
+
+  - Move non-essential styling from  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:
 
@@ -138,6 +146,8 @@ Version 0.17b1
 
     __ docs/user/latex.html#custom-interpreted-text-roles
 
+  - Remove legacy LaTeX stylesheet ``docutils-05-compat.sty``.
+  
   - Support the `memoir` LaTeX document class.
     Fixes bugs #390, #391, and #392.
 
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt
index d94242a1c..feb8af170 100644
--- a/docutils/RELEASE-NOTES.txt
+++ b/docutils/RELEASE-NOTES.txt
@@ -94,6 +94,11 @@ Release 0.17
 
 * The generic command line front end ``docutils-cli.py`` allows the
   free selection of reader, parser, and writer components.
+  
+* New, experimental wrapper to integrate the
+  `recommonmark`__ Markdown parser for use with Docutils.
+
+  __ https://pypi.org/project/recommonmark/
 
 * HTML writers: new option to embed images.
 
@@ -112,9 +117,9 @@ Release 0.17
     Use <ins> and <del> if a matching class value
     is found in `inline`, `literal`, or `container` elements.
 
-  - Wrap block-level image elements in <p> (except for figures).
-    Move non-essential styling from ``minimal.css`` to ``plain.css``.
-    Support numbered figures in ``plain.css``.
+  - New optional style ``responsive.css``, adapts to different screen
+    sizes.
+
 
   .. _initial_header_level: docs/user/config.html#initial-header-level
   __ https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article
diff --git a/docutils/docs/api/publisher.txt b/docutils/docs/api/publisher.txt
index cd63ef168..a747c60ee 100644
--- a/docutils/docs/api/publisher.txt
+++ b/docutils/docs/api/publisher.txt
@@ -95,8 +95,7 @@ details about individual settings.
 Encodings
 ---------
 
-The default output encoding of Docutils is UTF-8.  If you have any
-non-ASCII in your input text, you may have to do a bit more setup.
+The default output encoding of Docutils is UTF-8.
 Docutils may introduce some non-ASCII text if you use
 `auto-symbol footnotes`_ or the `"contents" directive`_.
 
@@ -130,10 +129,11 @@ _`whole`
     ``parts['whole']`` contains the entire formatted document.
 
 
-.. _HTML writer:
+Parts Provided By the HTML Writers
+----------------------------------
 
-Parts Provided By the HTML Writer
----------------------------------
+HTML4 Writer
+````````````
 
 _`body`
     ``parts['body']`` is equivalent to parts['fragment_'].  It is
@@ -254,20 +254,28 @@ _`title`
     tags.
 
 
-Parts Provided by the PEP/HTML Writer
-`````````````````````````````````````
+PEP/HTML Writer
+```````````````
 
-The PEP/HTML writer provides the same parts as the `HTML writer`_,
+The PEP/HTML writer provides the same parts as the `HTML4 writer`_,
 plus the following:
 
 _`pepnum`
     ``parts['pepnum']`` contains
 
 
-Parts Provided by the S5/HTML Writer
-````````````````````````````````````
+S5/HTML Writer
+``````````````
 
-The S5/HTML writer provides the same parts as the `HTML writer`_.
+The S5/HTML writer provides the same parts as the `HTML4 writer`_.
+
+
+HTML5 Writer
+````````````
+
+The HTML5 writer provides the same parts as the `HTML4 writer`_.
+However, it uses semantic HTML5 elements for the document, header and
+footer.
 
 
 Parts Provided by the LaTeX2e Writer
diff --git a/docutils/docs/dev/distributing.txt b/docutils/docs/dev/distributing.txt
index c60535ee7..eb0be4a11 100644
--- a/docutils/docs/dev/distributing.txt
+++ b/docutils/docs/dev/distributing.txt
@@ -33,17 +33,22 @@ Docutils has the following dependencies:
 
 * Docutils may optionally make use of the PIL (`Python Imaging
   Library`_ or Pillow_).  If PIL is present, it is automatically
-  detected by Docutils.
+  detected by Docutils.  
 
 * Docutils recommends the `Pygments`_ syntax hightlighter. If available, it
   is used for highlighting the content of `code directives`_ and roles as
   well as included source code files (with the "code" option to the include_
   directive).
 
+* Docutils can use the `recommonmark`_ parser to parse input in
+  the Markdown format (new in 0.17).
+
 .. _Python Imaging Library: 
     https://en.wikipedia.org/wiki/Python_Imaging_Library
 .. _Pillow: https://pypi.org/project/Pillow/
 .. _Pygments: http://pygments.org/
+.. _recommonmark: https://pypi.org/project/recommonmark/
+
 .. _code directives: ../ref/rst/directives.html#code
 .. _include: ../ref/rst/directives.html#include
 
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index f34d694d8..76e8839a7 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -211,19 +211,19 @@ General
 * Perhaps the ``Component.supports`` method should deal with
   individual features ("meta" etc.) instead of formats ("html" etc.)?
   Currently, only the `<meta> node`_ requires the framework.
-  
+
   Do we need it at all?  Or rather let the writers just ignore some
   nodes (like we already do for "class" values)?
-  
+
   The current implementation of the framework also leads to bug
   `bug #241`__ "doctree-based publishing != publish_string".
   The "components.Filter" transform is run by publish_doctree(). When
   filtering based on the output format, it should be run by
   publish_from_doctree() instead because only then the writer is
   known.
-  
+
   So we need to either remove or fix the framework.
-  
+
   __ https://sourceforge.net/p/docutils/bugs/241/
 
 
@@ -1211,16 +1211,16 @@ Handle documents only, or objects (images, etc.) also?
 
 At what point should the extensions be substituted?
 
-  Transforms_: 
+  Transforms_:
     Fits well in the `Reader → Transformer → Writer`__ processing framework.
-    
+
     * Filename/URL extension replacement can be done walking over the
       Document tree transforming the document tree from a valid state
       to another valid state.
-    
+
     * Writer-specific configuration is still possible in the
       respective sections of the configuration_ file.
-      
+
     __ ../peps/pep-0258.html#id24
 
   Pre- or post-processing:
@@ -2855,11 +2855,11 @@ Front-End Tools
 * What about if we don't know which Reader and/or Writer we are
   going to use?  If the Reader/Writer is specified on the
   command-line?
-  
+
   The dynamic_ front end ``tools/docutils-cli.py`` (new in 0.17) is an
   implementation of concept d) below. It uses 2-stage argument parsing
   via the `argparse` module's `partial parsing`_. It still needs some
-  polishing.  
+  polishing.
 
   Perhaps have different types of front ends:
 
@@ -2882,8 +2882,8 @@ Front-End Tools
 
   d) _`Dynamic`: Reader and/or Writer are specified by options, with
      defaults if unspecified (e.g. ``publish --writer manpage
-     [options]``). 
-     
+     [options]``).
+
   Allow common options before subcommands, as in CVS?  Or group all
   options together?  In the case of the `fully qualified`_
   front ends, all the options will have to be grouped together
diff --git a/docutils/docs/howto/security.txt b/docutils/docs/howto/security.txt
index a28a65aba..2088f937a 100644
--- a/docutils/docs/howto/security.txt
+++ b/docutils/docs/howto/security.txt
@@ -22,7 +22,7 @@ management systems, and others), several security issues arose and
 have been addressed.  This document provides instructions to help you
 secure the Docutils software in your applications.
 
-Docutils does not come in a through-the-web secure state, because this
+**Docutils does not come in a through-the-web secure state**, because this
 would inconvenience ordinary users.
 
 __ ../../FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt
index 1166f13d8..353e85436 100644
--- a/docutils/docs/ref/rst/directives.txt
+++ b/docutils/docs/ref/rst/directives.txt
@@ -333,7 +333,7 @@ In addition, the following options are recognized:
     Set a `"classes"`_ attribute value on the figure element.  See the
     class_ directive below.
 
-.. _Python Imaging Library: 
+.. _Python Imaging Library:
     https://en.wikipedia.org/wiki/Python_Imaging_Library
 .. _Pillow: https://pypi.org/project/Pillow/
 
@@ -1875,8 +1875,8 @@ dropped by the writer.
 .. note:: Data from some `bibliographic fields`_ is automatically
    extracted and stored in META tags, too. However, Bibliographic
    Fields are also visible in the document's screen rendering or
-   printout. 
-   
+   printout.
+
    For an "invisible" *document title*, see the `metadata document
    title`_ directive below.
 
@@ -1988,7 +1988,7 @@ _`:name:` : text
 
       .. image:: bild.png
 
-    New in Docutils 0.8.
+    (New in Docutils 0.8.)
 
 
 .. _reference name:
diff --git a/docutils/docs/ref/rst/restructuredtext.txt b/docutils/docs/ref/rst/restructuredtext.txt
index 806f7b017..2bdee3834 100644
--- a/docutils/docs/ref/rst/restructuredtext.txt
+++ b/docutils/docs/ref/rst/restructuredtext.txt
@@ -461,10 +461,11 @@ the "document title" can become the document subtitle.  The rest of
 the sections are then lifted up a level or two.  See the `DocTitle
 transform`_ for details.
 
-.. [#] The `title`_ configuration setting can set a document title that does
-   not become part of the document body.
+.. [#] The `title configuration setting`__ and the `title directive`__
+   set a document title that does not become part of the document body.
 
-.. _title: ../../user/config.html#title
+   __ ../../user/config.html#title
+   __ directives.html#metadata-document-title
 
 
 Sections
@@ -3176,6 +3177,7 @@ Markup errors are handled according to the specification in `PEP
 .. _colspec: ../doctree.html#colspec
 .. _thead: ../doctree.html#thead
 .. _tbody: ../doctree.html#tbody
+.. _title: ../doctree.html#title
 .. _row: ../doctree.html#row
 .. _entry: ../doctree.html#entry
 .. _identifier key: ../doctree.html#identifier-keys
diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index c1b5c818b..cf4689ecc 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -710,7 +710,7 @@ are selected according to the language of the current block element (see
 language_code_, smartquotes_locales_, and the `pre-defined quote sets`__).
 
 Also changes consecutive runs of hyphen-minus and full stops (``---``,
-``--``, ``...``) to em-dash, en-dash and ellipsis Unicode characters
+``--``, ``...``) to em-dash, en-dash, and ellipsis Unicode characters
 respectively.
 
 Supported values:
@@ -1573,12 +1573,11 @@ When possible\ [#]_, use the specified environment for `literal blocks`_.
 Default: "" (quoting of whitespace and special chars).
 Option: ``--literal-block-env``.
 
-.. [#] A literal-block element, when processed by a Docutils writer might
-   have it's origin in literal block following "::" or a
-   ``.. parsed-literal::`` directive.
+.. [#] A literal-block element may originate from a `parsed literal`_.
+   A LaTeX verbatim environment is only usable it does not contain
+   inline elements.
 
-   A LaTeX verbatim environment is only usable if there is no other
-   markup contained in the literal-block.
+.. _parsed literal: ../ref/rst/directives.html#parsed-literal
 
 reference_label
 ~~~~~~~~~~~~~~~
diff --git a/docutils/docs/user/html.txt b/docutils/docs/user/html.txt
index 16462cbe5..a426a537f 100644
--- a/docutils/docs/user/html.txt
+++ b/docutils/docs/user/html.txt
@@ -108,7 +108,7 @@ New in Docutils 0.13
 
 .. [#] see also `Benefits of polyglot XHTML5`_
 .. [#safetext] The validity of raw HTML and custom stylesheets must be
-   ensured by the author (e.g. using `safe text content`_).
+   ensured by the author.
 
 .. _rst2html5.py: tools.html#rst2html5-py
 .. _[html5 writer]: config.html#html5-writer
@@ -118,55 +118,27 @@ New in Docutils 0.13
 .. _custom style sheets: ../howto/html-stylesheets.html
 .. _viewable with any browser: http://www.anybrowser.org/campaign
 .. _Benefits of polyglot XHTML5: http://xmlplease.com/xhtml/xhtml5polyglot/
-.. _safe text content:
-     https://www.w3.org/TR/html-polyglot/#dfn-safe-text-content
 
 
 HTML writers in the sandbox
 ---------------------------
 
-There are two more HTML writers in the sandbox_:
+.. _xhtml11:
 
-.. _sandbox: ../dev/policies.html#the-sandbox
-
-xhtml11
-~~~~~~~
-:aliases:   xhtml, html4strict
-:front-end: rst2xhtml.py
-:config:    `[xhtml11 writer]`
-
-`XHTML 1.1`_ is the latest version of the XML based `extensible
-Hypertext Markup Language` with an official DTD.
-
-The `xhtml11 writer`_ lives in the Docutils sandbox_ since 2008. The output
-conforms to the strict requirements of `XHTML 1.1`_.
+There are two more HTML writers in the sandbox_, the `xhtml11 writer`_
+and the `HTML writer for lightweight browsers`_ (_`html4trans`).
 
+.. _sandbox: ../dev/policies.html#the-sandbox
 .. _xhtml11 writer: ../../../sandbox/html4strict/README.html
-
-
-html4trans
-~~~~~~~~~~
-
-:front-end: rst2html_trans.py_
-
-The `HTML writer for lightweight browsers`_ lives in the Docutils sandbox
-(`sandbox/html4trans`_) since 2008. It removes the dependency on CSS. The
-output conforms to `XHTML 1 Transitional`_ and contains sufficient
-formatting information for rendering without style sheet. (Of course, this
-has some drawbacks_.)
-
 .. _HTML writer for lightweight browsers:
    ../../../sandbox/html4trans/README.html
-.. _drawbacks: ../../../sandbox/html4trans/README.html#drawbacks
-.. _sandbox/html4trans: ../../../sandbox/html4trans
-.. _rst2html_trans.py: ../../../sandbox/html4trans/tools/rst2html_trans.py
 
 
 Overview
 --------
 
 =============== =========== ============== ================= ===========
-name            alias(es)   `front-end`_   HTML version      CSS version
+name            aliases     `front-end`_   HTML version      CSS version
 =============== =========== ============== ================= ===========
 html4css1_      html4,      rst2html4.py,  `XHTML 1          `CSS 1`_
                 html_       rst2html.py    Transitional`_
@@ -182,7 +154,7 @@ html5_polyglot_ html5       rst2html5.py   `HTML5`_          `CSS 3`_
 xhtml11_        xhtml,      rst2xhtml.py   `XHTML 1.1`_      `CSS 3`_
                 html4strict
 
-html4trans_ ..              rst2html_trans `XHTML 1          no CSS
+html4trans_     ..          rst2html_trans `XHTML 1          no CSS
                                            Transitional`_    required
 =============== =========== ============== ================= ===========
 
diff --git a/docutils/docs/user/manpage.txt b/docutils/docs/user/manpage.txt
index f886f18ec..246579339 100644
--- a/docutils/docs/user/manpage.txt
+++ b/docutils/docs/user/manpage.txt
@@ -1,5 +1,5 @@
 ==============================
- manpage writer for Docutils_ 
+ manpage writer for Docutils_
 ==============================
 
 :Author: Engelbert Gruber
@@ -8,10 +8,13 @@
 :Date: $Date$
 :Copyright: This document has been placed in the public domain.
 
-This tries to explore the posibilities to generate man-pages from
+This writer explores the posibilities to generate man-pages from
 reStructuredText. Man pages are the way for Unix systems to provide
 help to the user. GNU does this with (TeX)info-pages.
 
+.. contents::
+
+
 Module information
 ''''''''''''''''''
 
@@ -26,17 +29,17 @@ Also man pages have a defined set of sections, that are more or less
 mandatory, see References_.
 
 man pages look like::
-       
+
    man(1)     Man Pager Utils     man(1)
-       
+
    NAME
        man - an interface to the on-line reference manuals
-       
+
    SYNOPSIS
        man [-c|-w|-tZT device] [-adhu7V] [-m system[,...]] [-L locale]
-     
+
 in roff formatting::
-     
+
      .TH man 1 "14 May 2001" "2.3.19" "Manual pager utils"
      .SH NAME
      man \- an interface to the on-line reference manuals
@@ -46,9 +49,9 @@ in roff formatting::
      .RB [\| \-c \||\| \-w \||\| \-tZT
      .IR device \|]
 
-This means we have 
+This means we have
 
-* a title "man" 
+* a title "man"
 * a subtitle "an interface to the on-line reference manuals"
 * a manual section "1"
 * a manual group "Manual pager utils"
@@ -65,7 +68,7 @@ man pages from section 7, ``man`` and ``man-pages``.
 Conventions
 '''''''''''
 
-* man pages have a special structure and organization. From the manpage 
+* man pages have a special structure and organization. From the manpage
   to *man*::
 
     The table below shows the section numbers of the manual followed  by  the
@@ -105,17 +108,17 @@ Conventions
 * new lines in general.
 
   Consecutive blank lines are merged by the viewer but not on printouts.
-  So one has to be cautious. This is most disturbing when printing 
+  So one has to be cautious. This is most disturbing when printing
   postscript.
 
   .. NOTE::
 
     1. Roff requests only work when at line start.
-    2. But consecutive blank lines are merged by the viewer but not on 
+    2. But consecutive blank lines are merged by the viewer but not on
        printouts.
 
-    So try the rule start new lines in ``visit_``-functions, but only if 
-    necessary. E.g. ``field-names`` are already on a new line because of 
+    So try the rule start new lines in ``visit_``-functions, but only if
+    necessary. E.g. ``field-names`` are already on a new line because of
     docutils structure.
 
 * Indentation, left margin:
@@ -150,7 +153,7 @@ Open issues
 * How to write long syntax lines.
 * Line ends around email or web addresses in texts.
   How to distinguish something is inline or not ?
-  
+
 * Images and equations are discouraged.
 * Lists in admonitions are not intended.
 * Encoding declaration ``'\" t -*- coding: ISO-8859-1 -*-``
@@ -159,5 +162,5 @@ Open issues
   BUT if UTF-8 is declared tables are no longer processed.
 
 * Input and output encoding are problematic at least.
- 
+
 .. _Docutils: http://docutils.sourceforge.net/
diff --git a/docutils/docs/user/odt.txt b/docutils/docs/user/odt.txt
index 2e6083dab..aec04da1b 100644
--- a/docutils/docs/user/odt.txt
+++ b/docutils/docs/user/odt.txt
@@ -67,7 +67,8 @@ Examples::
 
     $ rst2odt.py -s -g python_comments.txt python_comments.odt
 
-    $ rst2odt.py --source-url=odtwriter.txt --generator --stylesheet=/myconfigs/styles.odt odtwriter.txt odtwriter.odt
+    $ rst2odt.py --source-url=odtwriter.txt --generator \
+        --stylesheet=/myconfigs/styles.odt odtwriter.txt odtwriter.odt
 
 
 Configuration file
@@ -744,7 +745,8 @@ contain them, do the following:
    using the ``--stylesheet`` option in order to include your
    custom style definitions.  For example::
 
-       rst2odt.py --odf-config-file=mymappingfile.ini --stylesheet=mystyles.odt mydoc.txt mydoc.odt
+       rst2odt.py --odf-config-file=mymappingfile.ini \
+         --stylesheet=mystyles.odt mydoc.txt mydoc.odt
 
 
 Classes
@@ -1013,15 +1015,20 @@ Here is an example::
 
     .. raw:: odt
 
-        <text:p text:style-name="rststyle-textbody">Determining <text:span text:style-name="rststyle-emphasis">which</text:span> namespace a name is in is static.  It can be
-        determined by a lexical scan of the code.  If a variable is assigned a
-        value <text:span text:style-name="rststyle-emphasis">anywhere</text:span> in a scope (specifically within a function or method
-        body), then that variable is local to that scope.  If Python does not
-        find a variable in the local scope, then it looks next in the global
-        scope (also sometimes called the module scope) and then in the
-        built-ins scope.  But, the <text:span text:style-name="rststyle-inlineliteral">global</text:span> statement can be used to force
-        Python to find and use a global variable (a variable defined at top
-        level in a module) rather than create a local one.</text:p>
+        <text:p text:style-name="rststyle-textbody">Determining
+        <text:span text:style-name="rststyle-emphasis">which</text:span>
+        namespace a name is in is static.  It can be determined by a
+        lexical scan of the code.  If a variable is assigned a value
+        <text:span text:style-name="rststyle-emphasis">anywhere</text:span>
+        in a scope (specifically within a function or method body),
+        then that variable is local to that scope.  If Python does
+        not find a variable in the local scope, then it looks next
+        in the global scope (also sometimes called the module scope)
+        and then in the built-ins scope.  But, the
+        <text:span text:style-name="rststyle-inlineliteral">global</text:span>
+        statement can be used to force Python to find and use a global
+        variable (a variable defined at top level in a module) rather
+        than create a local one.</text:p>
 
 
 The meta directive
diff --git a/docutils/docs/user/rst/cheatsheet.txt b/docutils/docs/user/rst/cheatsheet.txt
index 43849b644..1a3f3e27a 100644
--- a/docutils/docs/user/rst/cheatsheet.txt
+++ b/docutils/docs/user/rst/cheatsheet.txt
@@ -100,7 +100,7 @@ sectnum           Automatically number sections, subsections, etc.
 header, footer    Create document decorations [0.3.8]
 target-notes      Create an explicit footnote for each external target
 math              Mathematical notation (input in LaTeX format)
-meta              HTML-specific metadata
+meta              Document metadata
 include           Read an external reST file as if it were inline
 raw               Non-reST data passed untouched to the Writer
 replace           Replacement text for substitution definitions
diff --git a/docutils/docs/user/rst/demo.txt b/docutils/docs/user/rst/demo.txt
index 324234305..3dfb43f35 100644
--- a/docutils/docs/user/rst/demo.txt
+++ b/docutils/docs/user/rst/demo.txt
@@ -517,6 +517,26 @@ Compound Paragraph
 This construct is called a *compound paragraph* and can be produced
 with the "compound" directive.
 
+Meta
+````
+
+The `“meta” directive`__ is used to specify metadata to be stored in,
+e.g., HTML META tags or ODT file properties.
+
+.. hint::
+    Use a `viewport meta tag`__ to tell mobile browsers
+    to use the device-width as viewport.
+
+.. meta::
+   :keywords: reStructuredText, test, parser
+   :description lang=en: A test document, containing at least one
+       example of each reStructuredText construct.
+   :viewport: width=device-width, initial-scale=1
+
+__ https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata
+__ https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag
+
+
 Substitution Definitions
 ------------------------
 
diff --git a/docutils/docs/user/smartquotes.txt b/docutils/docs/user/smartquotes.txt
index 50677b840..260f3073e 100644
--- a/docutils/docs/user/smartquotes.txt
+++ b/docutils/docs/user/smartquotes.txt
@@ -88,6 +88,8 @@ current block element and the value of the `"smart_quotes" setting`_.\
 [#x-altquot]_
 There is built-in support for the following languages:\ [#smartquotes-locales]_
 
+.. class:: run-in
+
 :af: .. class:: language-af
 
     "'Afrikaans' quotes"
@@ -142,8 +144,7 @@ There is built-in support for the following languages:\ [#smartquotes-locales]_
 
 :en-uk-x-altquot: .. class:: language-en-uk-x-altquot
 
-    "'British' alternative quotes"
-    (swaps single and double quotes: ``"`` → ‘ and ``'`` → “)
+    "'British' alternative quotes" (swaps single and double quotes)
 
 :eo: .. class:: language-eo
 
@@ -262,7 +263,7 @@ There is built-in support for the following languages:\ [#smartquotes-locales]_
 
     "'Dutch' alternative quotes"
 
-.. # 'nl-x-altquot2': u'””’’',
+    .. # 'nl-x-altquot2': u'””’’',
 
 :pl: .. class:: language-pl
 
diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt
index 8a75a48f3..b82f62fb2 100644
--- a/docutils/docs/user/tools.txt
+++ b/docutils/docs/user/tools.txt
@@ -78,7 +78,7 @@ buildhtml.py
 
 :Readers: Standalone, PEP
 :Parser: reStructuredText
-:Writers: html_, pep_html_
+:Writers: html_, html5_, pep_html_
 
 Use ``buildhtml.py`` to generate ``*.html`` from all the ``*.txt`` files
 (including PEPs) in each <directory> given, and their subdirectories
@@ -178,7 +178,7 @@ rst2html5.py
 
 :Reader: Standalone
 :Parser: reStructuredText
-:Writer: _`html5` (html5_polyglot_)
+:Writer: html5_
 
 The ``rst2html5.py`` front end reads standalone reStructuredText source
 files and produces `HTML 5`_ output.
@@ -186,7 +186,7 @@ Correct rendering of elements not directly supported by HTML depends on a
 CSS style sheet. The provided style sheets ``minimal.css`` and ``plain.css``
 define required and optional styling rules respectively.
 
-.. _html5_polyglot: html.html#html5-polyglot
+.. _html5: html.html#html5-polyglot
 
 rstpep2html.py
 --------------