Small documentation updates and fixes.

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

8 files changed, 77 insertions, 75 deletions

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
 --------------