Documentation update

dev/hacking:
  Format example code as script rather than as console log
  (enables easier use via drag-and-drop).
  Hint to the "quicktest" development tool.
  Add links.

user/config:
  Fix legacy-lass-functions default change warning.

user/toos:
  Simplify description of the generic front end.

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

3 files changed, 51 insertions, 47 deletions

diff --git a/docutils/docs/dev/hacking.txt b/docutils/docs/dev/hacking.txt
index 30774c55b..daff6046c 100644
--- a/docutils/docs/dev/hacking.txt
+++ b/docutils/docs/dev/hacking.txt
@@ -70,21 +70,20 @@ Parsing the Document
 
 The **Parser** analyzes the the input document and creates a **node
 tree** representation.  In this case we are using the
-**reStructuredText parser** (``docutils/parsers/rst/__init__.py``).
-To see what that node tree looks like, the below code creates a Docutils
-document and parser to parse our example file without applying any
-tranforms or post-processing.
-
-.. code:: pycon
-
-    >>> from docutils import frontend, utils
-    >>> from docutils.parsers.rst import Parser
-    >>> settings = frontend.get_default_settings(Parser)
-    >>> with open('test.txt', encoding='utf-8') as file:
-    ...     document = utils.new_document(file.name, settings)
-    ...     Parser().parse(file.read(), document)
-    ...
-    >>> print(document.pformat())
+**reStructuredText parser**:
+
+.. code:: python
+
+    from docutils import frontend, utils
+    from docutils.parsers.rst import Parser
+    settings = frontend.get_default_settings(Parser)
+    with open('test.txt', encoding='utf-8') as file:
+        document = utils.new_document(file.name, settings)
+        Parser().parse(file.read(), document)
+
+Let us now examine the node tree.
+With ``print(document.pformat())`` we get::
+
     <document source="test.txt">
         <paragraph>
             My
@@ -96,8 +95,6 @@ tranforms or post-processing.
             .
         <target ids="python" names="python" refuri="https://www.python.org/">
 
-Let us now examine the node tree:
-
 The top-level node is ``document``.  It has a ``source`` attribute
 whose value is ``text.txt``.  There are two children: A ``paragraph``
 node and a ``target`` node.  The ``paragraph`` in turn has children: A
@@ -111,6 +108,13 @@ arranged as a class hierarchy (for example, both ``emphasis`` and
 overview of the node class hierarchy, use epydoc (type ``epydoc
 nodes.py``) and look at the class hierarchy tree.
 
+.. tip:: While rst2pseudoxml_ shows the node tree after `transforming the
+   document`_, the script quicktest.py_ (in the ``tools/dev/`` directory
+   of the Docutils distribution) shows the direct result of parsing a
+   reStructuredText sample.
+
+.. _quicktest.py: https://docutils.sourceforge.io/tools/dev/quicktest.py
+
 
 Transforming the Document
 -------------------------
@@ -126,15 +130,9 @@ Instead, it's done by a **Transform**.  In this case (resolving a
 reference), it's done by the ``ExternalTargets`` transform in
 ``docutils/transforms/references.py``.
 
-In fact, there are quite a lot of Transforms, which do various useful
-things like creating the table of contents, applying substitution
-references or resolving auto-numbered footnotes.
-
 The Transforms are applied after parsing.  To see how the node tree
 has changed after applying the Transforms, we use the
-``rst2pseudoxml.py`` tool:
-
-.. parsed-literal::
+rst2pseudoxml_ tool [#]_::
 
     $ rst2pseudoxml.py test.txt
     <document source="test.txt">
@@ -154,9 +152,17 @@ attribute |---| the reference has been resolved.
 
 While this does not look very exciting, transforms are a powerful tool
 to apply any kind of transformation on the node tree.
+In fact, there are quite a lot of Transforms, which do various useful
+things like creating the table of contents, applying substitution
+references or resolving auto-numbered footnotes. For details, see
+`Docutils Transforms`_.
+
+.. [#] You can also get a standard XML representation of the
+       node tree by using rst2xml_ instead of rst2pseudoxml_.
 
-By the way, you can also get a "real" XML representation of the node
-tree by using ``rst2xml.py`` instead of ``rst2pseudoxml.py``.
+.. _Docutils Transforms: ../api/transforms.html
+.. _rst2pseudoxml: ../user/tools.html#rst2pseudoxml
+.. _rst2xml: ../user/tools.html#rst2xml
 
 
 Writing the Document
@@ -257,7 +263,6 @@ covered here.  To find out with which topics we should write about
 first, we are awaiting *your* feedback.  So please ask your questions
 on the Docutils-develop_ mailing list.
 
-
 .. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
 
 .. |---| unicode:: 8212 .. em-dash
diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index 289974647..9b867c838 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -1667,7 +1667,7 @@ comma-separated list of class values as optional argument. If `False`, class
 values are handled with wrappers and admonitions use the ``DUadmonition``
 environment. See `Generating LaTeX with Docutils`__ for details.
 
-Default: False (changed in Docutils 0.18).
+Default: False (since Docutils 0.18).
 Options: ``--legacy-class-functions``, ``--new-class-functions``.
 
 New in Docutils 0.17.
@@ -1686,7 +1686,7 @@ table width and keeps the ratio of specified column widths.
 Custom table and/or column widths can be set with the respective options
 of the `table directive`_. See also `Generating LaTeX with Docutils`__.
 
-Default: True (will change to False in 0.19).
+Default: True (will change to False in Docutils 1.0).
 Options: ``--legacy-column-widths``, ``--new-column-widths``.
 
 New in Docutils 0.18.
diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt
index 13cf42e1f..1ff8d1e51 100644
--- a/docutils/docs/user/tools.txt
+++ b/docutils/docs/user/tools.txt
@@ -36,7 +36,7 @@ to generate a specific data format).
 Most [#]_ front ends have common options and the same command-line usage
 pattern::
 
-    toolname [options] [<source> [<destination>]]
+    <toolname> [options] [<source> [<destination>]]
 
 See `the tools`_ below for concrete examples.
 
@@ -75,34 +75,29 @@ Generic Command Line Front End
 
 :Readers: Standalone (default), PEP
 :Parsers: reStructuredText (default), Markdown (requires 3rd party packages)
-:Writers: html_, html4css1_, html5_ (default), latex__, manpage_,
+:Writers: html_, html4css1_, html5_ (default), latex2e_, manpage_,
           odt_, pep_html_, pseudo-xml_, s5_html_, xelatex_, xml_,
 :Config_: `[docutils application]`_
 
-The generic front end allows combining "reader", "parser", and
-"writer" components from the Docutils package or 3rd party plug-ins.
+Since Docutils 0.19, you can start the generic front end like::
 
-Since Docutils 0.19, it can be called by Python's ``-m`` option,
-the ``docutils`` script installed in the binary PATH, or the
-``docutils-cli.py`` script in the ``tools/`` directory.
+    docutils test.rst test.html
 
+Alternatively, use Python's ``-m`` option, or the ``docutils-cli.py``
+script in the ``tools/`` directory.
+
+The generic front end allows combining "reader", "parser", and
+"writer" components from the Docutils package or 3rd party plug-ins.
 For example, to process a Markdown_ file "``test.md``" into
-Pseudo-XML_ ::
+Pseudo-XML_::
 
-    python3 -m docutils --parser=markdown --writer=pseudoxml\
-      test.md test.txt
+    docutils --parser=markdown --writer=pseudoxml test.md test.txt
 
 Use the "--help" option together with the component-selection options
 to get the correct list of supported command-line options. Example::
 
     docutils --parser=markdown --writer=xml --help
 
-
-
-__
-.. _latex2e:
-.. _Generating LaTeX with Docutils: latex.html
-.. _manpage: manpage.html
 .. _Markdown: https://www.markdownguide.org/
 .. _[docutils application]: config.html#docutils-application
 
@@ -252,11 +247,10 @@ configuration files.
 For example, to process a PEP into HTML::
 
     cd <path-to-docutils>/docs/peps
-    rstpep2html.py pep-0287.txt pep-0287.html
+    ../../tools/rstpep2html.py pep-0287.txt pep-0287.html
 
 The same result can be achieved with the genric front end::
 
-    cd <path-to-docutils>/docs/peps
     docutils --reader=pep --writer=pep_html pep-0287.txt pep-0287.html
 
 The rendering of published PEPs is done by a Sphinx-based build system
@@ -401,6 +395,10 @@ printing or on-screen viewing.
 
 For details see `Generating LaTeX with Docutils`_.
 
+.. _latex2e:
+.. _Generating LaTeX with Docutils: latex.html
+
+
 rst2xetex.py
 ------------
 
@@ -439,6 +437,7 @@ rst2man.py
 The ``rst2man.py`` front end reads standalone reStructuredText source
 files and produces troff_ sources for Unix man pages.
 
+.. _manpage: manpage.html
 .. _troff: https://troff.org/