[Docutils-checkins] SF.net SVN: docutils:[9082] trunk/docutils

[<mi...@us...>]

Revision: 9082
          http://sourceforge.net/p/docutils/code/9082
Author:   milde
Date:     2022-06-20 10:06:31 +0000 (Mon, 20 Jun 2022)
Log Message:
-----------
Documentation update.

Add a warning about use of Python's default encoding by "quicktest.py".

Add cross-links, condense.

Modified Paths:
--------------
    trunk/docutils/README.txt
    trunk/docutils/docs/dev/hacking.txt
    trunk/docutils/docs/user/tools.txt

Modified: trunk/docutils/README.txt
===================================================================
--- trunk/docutils/README.txt	2022-06-19 20:23:12 UTC (rev 9081)
+++ trunk/docutils/README.txt	2022-06-20 10:06:31 UTC (rev 9082)
@@ -349,22 +349,15 @@
 two times represents the time required to set up the tests (import
 modules, create data structures, etc.).
 
+A copy of the test output is written to the file ``alltests.out``.
+
 If any of the tests fail, please `open a bug report`_ or `send an email`_
 (see `Bugs <BUGS.html>`_).
 Please include all relevant output, information about your operating
 system, Python version, and Docutils version.  To see the Docutils
-version, use one of the ``rst2*`` front ends or ``tools/quicktest.py``
-with the ``--version`` option, e.g.::
+version, look at the test output or use one of the `front-end scripts`_ 
+with the ``--version`` option.
 
-    cd ../tools
-    ./quicktest.py --version
-
-Windows users type these commands::
-
-    cd ..\tools
-    python quicktest.py --version
-
-
 .. _Docutils Testing: https://docutils.sourceforge.io/docs/dev/testing.html
 .. _open a bug report:
    https://sourceforge.net/p/docutils/bugs/

Modified: trunk/docutils/docs/dev/hacking.txt
===================================================================
--- trunk/docutils/docs/dev/hacking.txt	2022-06-19 20:23:12 UTC (rev 9081)
+++ trunk/docutils/docs/dev/hacking.txt	2022-06-20 10:06:31 UTC (rev 9082)
@@ -71,7 +71,7 @@
 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, we call ``quicktest.py`` (which
+To see what that node tree looks like, we call quicktest.py_ (which
 can be found in the ``tools/`` directory of the Docutils distribution)
 with our example file (``test.txt``) as first parameter (Windows users
 might need to type ``python quicktest.py test.txt``)::
@@ -251,8 +251,8 @@
 
 
 .. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
+.. _quicktest.py: ../user/tools.html#quicktest-py
 
-
 .. |---| unicode:: 8212 .. em-dash
    :trim:
 

Modified: trunk/docutils/docs/user/tools.txt
===================================================================
--- trunk/docutils/docs/user/tools.txt	2022-06-19 20:23:12 UTC (rev 9081)
+++ trunk/docutils/docs/user/tools.txt	2022-06-20 10:06:31 UTC (rev 9082)
@@ -45,7 +45,8 @@
    Tool names, install details and the set of auto-installed tools
    may change in future Docutils versions.
 
-.. [#] The exceptions are buildhtml.py_ and rst2odt_prepstyles.py_.
+.. [#] The exceptions are buildhtml.py_, quicktest.py_ and
+   rst2odt_prepstyles.py_.
 
 Getting Help
 ============
@@ -165,7 +166,9 @@
    (e.g., because you use a custom style sheet or post-processing
    that may break otherwise).
 
+.. _html: html.html#html
 
+
 rst2html4.py
 ------------
 
@@ -196,21 +199,24 @@
 
 ``rst2html.py`` inserts into the generated HTML a cascading stylesheet
 (or a link to a stylesheet, when passing the "``--link-stylesheet``"
-option).  A stylesheet is required for proper rendering.  The default
-stylesheet (``docutils/writers/html4css1/html4css1.css``, located in
-the installation directory) is provided for basic use.  To use
-different stylesheet(s), specify the stylesheets' location(s)
-as comma-separated list with the "``--stylesheet``" (for a URL)
-or "``--stylesheet-path``" (for a local file) command-line option,
-or with `configuration file`_ settings (e.g. ``./docutils.conf``
-or ``~/.docutils``).  To experiment with styles, please see the
+option).  A stylesheet is required for proper rendering.
+The default stylesheet (``docutils/writers/html4css1/html4css1.css``,
+located in the installation directory) is provided for basic use.
+
+To use different stylesheet(s), specify the stylesheets' location(s) as
+comma-separated list with the "`-\-stylesheet`_"
+or "`-\-stylesheet-path`_" options.
+To experiment with styles, please see the
 `guide to writing HTML (CSS) stylesheets for Docutils`__.
 
-__ ../howto/html-stylesheets.html
 .. _html4css1: html.html#html4css1
-.. _html: html.html#html
+.. _link-stylesheet: config.html#embed-stylesheet
+.. _--stylesheet: config.html#stylesheet
+.. _--stylesheet-path: config.html#stylesheet-path
 
+__ ../howto/html-stylesheets.html
 
+
 rst2html5.py
 ------------
 
@@ -525,7 +531,12 @@
 --rawxml  Raw native XML (with or without a stylesheet reference)
 --help    Usage hint and complete list of supported options.
 
+.. Caution:: ``quicktest.py`` uses Python's default encoding.
+   Input and output encoding depend on UTF-8 mode,
+   Python version, locale setting, and operating system
+   (cf. :PEP:`540`, :PEP:`538`, :PEP:`597`, and :PEP:`686`).
 
+
 ---------------
  Customization
 ---------------

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.