Add a small backwards compatibility script for rst2odt_prepstyles.py.

This way, users can adapt to the new command before the
"tools/*.py" scripts are no longer installed in Docutils 0.21.

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

4 files changed, 59 insertions, 18 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index b1037171d..f71f1d9e3 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -13,6 +13,7 @@
 
 .. contents::
 
+
 Changes since 0.20
 ==================
 
@@ -21,6 +22,12 @@ Changes since 0.20
   - Include tox.ini and docutils.conf in the source package
     (cf. bug #467 and bug #461).
 
+* tools/rst2odt_prepstyles.py
+
+  - Moved to ``docutils/writers/odf_odt/prepstyles.py``.
+    Replaced with a provisional backwards compatibility script.
+
+
 Release 0.20 (2023-05-09)
 =========================
 
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt
index 1b1347974..cebeae99f 100644
--- a/docutils/RELEASE-NOTES.txt
+++ b/docutils/RELEASE-NOTES.txt
@@ -38,15 +38,20 @@ Command line interface
      + docutils --writer=latex --use-latex-abstract FAQ.txt > FAQ.tex
 
   Exceptions:
-    The auxiliary script ``rst2odt_prepstyles.py`` will become
-    available via ``python -m docutils.writers.odf_odt.prepstyles``.
+    The ``rstpep2html.py`` and ``rst2odt_prepstyles.py`` scripts
+    will be retired.
 
-    The ``rstpep2html.py`` script will be retired.
-    Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview
-    (the final rendering is done by a Sphinx-based build system,
-    cf. :PEP:`676`).
+    Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview. [#]_
+
+    Use ``python -m docutils.writers.odf_odt.prepstyles``
+    to `strip the page size`__ from an ODT writer stylesheet.
+
+    __ docs/user/odt.html#page-size
 
   .. [#] Some Linux distributions already use the short names.
+  .. [#] The final rendering is done by a Sphinx-based build system
+         (cf. :PEP:`676`).
+
 
 * The _`command-line usage pattern` will change:
 
@@ -210,6 +215,13 @@ Misc
 .. _buildhtml.py: docs/user/tools.html#buildhtml-py
 .. _csv-table: docs/ref/rst/directives.html#csv-table
 
+
+Release 0.20.1 (unpublished)
+============================
+
+Bugfix release. See HISTORY_ for details.
+
+
 Release 0.20 (2023-05-04)
 =========================
 
diff --git a/docutils/docs/user/odt.txt b/docutils/docs/user/odt.txt
index 19ba63a69..ec7ea0e55 100644
--- a/docutils/docs/user/odt.txt
+++ b/docutils/docs/user/odt.txt
@@ -657,14 +657,13 @@ Why custom stylesheets
 
 Here are a few reasons and ideas:
 
-- The page size is stored in the style sheet.  The default page
-  size is ``Letter``.  You can change the page size (for example,
+- The `page size`_ is stored in the style sheet.  The default page
+  size is ``US Letter``.  You can change the page size (for example,
   to ``A4``) in your custom stylesheet by opening it in
   ``oowriter``, then clicking on menu: ``Format/Page...``, then
   clicking on the ``Page`` tab.
 
 
-
 Defining and using custom style names
 -------------------------------------
 
@@ -1064,12 +1063,12 @@ They cause ``oowriter`` to croak.
 Page size
 ---------
 
-The default page size, in documents generated by ``odtwriter`` is
-``Letter``.  You can change this (for example to ``A4``) by using a
+The default page size, in documents generated by the ODT writer is
+"US Letter".  You can change this (for example to ``A4``) by using a
 custom stylesheet.  See `Defining and using a custom stylesheet`_
 for instructions on how to do this.
 
-On machines which support ``paperconf``, ``odtwriter`` can insert
+On machines which support ``paperconf``, the ODT writer can insert
 the default page size for your locale.  In order for this to work,
 the following conditions must be met:
 
@@ -1077,13 +1076,16 @@ the following conditions must be met:
    ``odtwriter`` uses ``paperconf -s`` to obtain the paper size.
    See ``man paperconf`` for more information.
 
-2. The default page height and width must be removed from the
-   ``styles.odt`` used to generate the document.  A Python script
-   ``rst2odt_prepstyles.py`` is distributed with ``odtwriter`` and
-   is installed in the ``bin`` directory.  You can remove the page
-   height and width with something like the following::
+2. The page height and width settings must be absent from the stylesheet
+   used to generate the document.
+   
+   You can use the Python script ``prepstyles.py`` distributed with
+   Docutils to remove the page height and width settings from a
+   stylesheet file ``STYLES.odt`` with ::
 
-       $ rst2odt_prepstyles.py styles.odt
+       $ python3 -m docutils.writers.odf_odt.prepstyles STYLES.odt
+   
+   (the command changed in Docutils 0.20.1).
 
 .. warning:: If you edit your stylesheet in ``oowriter`` and then
     save it, ``oowriter`` automatically inserts a page height and
diff --git a/docutils/tools/rst2odt_prepstyles.py b/docutils/tools/rst2odt_prepstyles.py
new file mode 100755
index 000000000..d2c5e2d61
--- /dev/null
+++ b/docutils/tools/rst2odt_prepstyles.py
@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+
+# Copyright: This module has been placed in the public domain.
+
+"""
+Adapt a word-processor-generated styles.odt for odtwriter use:
+
+Drop page size specifications from styles.xml in STYLE_FILE.odt.
+See https://docutils.sourceforge.io/docs/user/odt.html#page-size
+
+Provisional backwards compatibility stub (to be removed in Docutils >= 0.21).
+
+The actual code moved to the "docutils" library package and can be started
+with ``python -m docutils.writers.odf_odt.prepstyles``.
+"""
+
+from docutils.writers.odf_odt import prepstyles
+
+if __name__ == '__main__':
+    prepstyles.main()