Do not decode OpenDocument zip packages with `publish_string()`.

The ODF writer produces output in binary format.
Raise an exception if `publish_string()` is called with
this writer and ``auto_encode=False``.

Update documentation, add cross-links.

TODO:
In future, the ODF writer may return a "flat XML" version of the
"OpenDocument Text" document as `str`.

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

4 files changed, 71 insertions, 45 deletions

diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index c27e4eeb2..624bc5f07 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -444,7 +444,9 @@ The "output_encoding" setting may also affect the content of the output
 (e.g. an encoding declaration in HTML or XML or the representation of
 characters as LaTeX macro vs. literal character).
 
-Default: "utf-8".  Options: ``--output-encoding, -o``.
+This setting is ignored by the `ODF/ODT Writer`_
+
+Default: "utf-8".  Options: ``--output-encoding``.
 
 output_encoding_error_handler
 -----------------------------
@@ -1999,10 +2001,21 @@ template__:
   __ `template [latex writers]`_
 
 
+.. _ODF/ODT Writer:
+
 [odf_odt writer]
 ----------------
 
-The following command line options are specific to ``odtwriter``:
+The `ODF/ODT Writer`__ generates documents in the 
+OpenDocument_ Text format (.odt).
+
+The output_encoding_ setting is ignored, the output encoding is
+always "UTF-8".
+
+__
+.. _ODT Writer for Docutils: odt.html
+.. _OpenDocument: https://en.wikipedia.org/wiki/OpenDocument
+
 
 stylesheet
 ~~~~~~~~~~
@@ -2029,6 +2042,7 @@ keeping email links usable with standards-compliant browsers.
 
 no-cloak-email-addresses
 ~~~~~~~~~~~~~~~~~~~~~~~~
+
 Do not obfuscate email addresses.
 
 table-border-thickness
@@ -2060,6 +2074,7 @@ Do not create sections for headers.
 
 create-links
 ~~~~~~~~~~~~
+
 Create links.
 
 no-links
@@ -2111,8 +2126,6 @@ section "Custom header/footers: inserting page numbers, date,
 time, etc" in the `Odt Writer for Docutils`_ document for
 details.
 
-.. _Odt Writer for Docutils: odt.html
-
 
 [pseudoxml writer]
 ------------------
diff --git a/docutils/docs/user/odt.txt b/docutils/docs/user/odt.txt
index cbe6e4ba5..19ba63a69 100644
--- a/docutils/docs/user/odt.txt
+++ b/docutils/docs/user/odt.txt
@@ -1,7 +1,7 @@
 .. include:: ../header.txt
 
 =======================
-Odt Writer for Docutils
+ODT Writer for Docutils
 =======================
 
 :Author: Dave Kuhlman
@@ -10,8 +10,8 @@ Odt Writer for Docutils
 :Date: $Date$
 :Copyright: This document has been placed in the public domain.
 
-:abstract: This document describes the Docutils odtwriter
-    (rst2odt.py).
+:abstract: This document describes the Docutils writer for
+           OpenDocument Text (.odt) documents.
 
 .. sectnum::
 
@@ -21,19 +21,12 @@ Odt Writer for Docutils
 Introduction
 ============
 
-What it does -- ``rst2odt.py`` translates reST
-(reStructuredText) into a Open Document Format ``.odt`` file.  You
-can learn more about the ODF format here:
+The Docutils front end rst2odt.py_ translates reStructuredText_ into an
+`OpenDocument Text`_ (.odt) file.
+OpenDocument files `can be opened by most modern office software`__.
+It is the native file format for LibreOffice_ Writer.
 
-- `OASIS Open Document Format for Office Applications
-  (OpenDocument) TC`_
-
-- `Open Document at Wikipedia`_
-
-You should be able to open documents (.odt files) generated with
-``rst2odt.py`` in ``OpenOffice/oowriter``.
-
-You can learn more about Docutils and reST here: `Docutils`_
+__ https://en.wikipedia.org/wiki/OpenDocument#Software
 
 
 Requirements
@@ -57,7 +50,7 @@ How to Use It
 
 Run it from the command line as follows::
 
-    $ rst2odt.py myinput.txt myoutput.odt
+    $ rst2odt.py myinput.txt > myoutput.odt
 
 To see usage information and to learn about command line options
 that you can use, run the following::
@@ -66,26 +59,30 @@ that you can use, run the following::
 
 Examples::
 
-    $ rst2odt.py -s -g python_comments.txt python_comments.odt
+    $ 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
+        --stylesheet=/myconfigs/styles.odt odtwriter.txt > odtwriter.odt
 
 
 Configuration file
 ------------------
 
-The options described below can also be set in a configuration file.
-Use section ``[odf_odt writer]`` to set options specific to the
+The options described below can also be set in a `configuration file`_.
+Use section `[odf_odt writer]`_ to set options specific to the
 ``odtwriter``.  For example::
 
     [odf_odt writer]
     stylesheet: styles1.odt
 
-See the "Docutils Configuration" document for more information on
+See the `Docutils Configuration`_ document for more information on
 Docutils configuration files, including locations which are
 searched.
 
+.. _Docutils Configuration: config.html
+.. _configuration file: config.html#configuration-files
+.. _[odf_odt writer]: config.html#odf-odt-writer
+
 
 Command line options
 --------------------
@@ -1185,18 +1182,15 @@ pick up the default paper size on platforms where the program
 
 
 
-
+.. _rst2odt.py:
+    tools.html#rst2odt-py
+.. _reStructuredText:
+    ../ref/rst/restructuredtext.html
+.. _`OpenDocument Text`:
+    https://en.wikipedia.org/wiki/OpenDocument
+.. _LibreOffice:
+    https://libreoffice.org/
 .. _`Pygments`:
     https://pygments.org/
-
-.. _`Docutils`:
-    https://docutils.sourceforge.io/
-
 .. _`Python Imaging Library`:
     https://en.wikipedia.org/wiki/Python_Imaging_Library
-
-.. _`Open Document at Wikipedia`:
-    https://en.wikipedia.org/wiki/OpenDocument
-
-.. _`OASIS Open Document Format for Office Applications (OpenDocument) TC`:
-    http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office
diff --git a/docutils/docutils/core.py b/docutils/docutils/core.py
index e19d6cefb..039dde3fe 100644
--- a/docutils/docutils/core.py
+++ b/docutils/docutils/core.py
@@ -23,6 +23,7 @@ import warnings
 
 from docutils import (__version__, __version_details__, SettingsSpec,
                       io, utils, readers, writers)
+import docutils.writers.odf_odt  # noqa:F401
 from docutils.frontend import OptionParser
 from docutils.readers import doctree
 
@@ -203,7 +204,8 @@ class Publisher:
                                 or self.settings._destination)
         self.settings._destination = destination_path
         self.destination = self.destination_class(
-            destination=destination, destination_path=destination_path,
+            destination=destination,
+            destination_path=destination_path,
             encoding=self.settings.output_encoding,
             error_handler=self.settings.output_encoding_error_handler)
 
@@ -723,11 +725,15 @@ def publish_programmatically(source_class, source, source_path,
                           source_class=source_class,
                           destination_class=destination_class)
     publisher.set_components(reader_name, parser_name, writer_name)
+    if isinstance(publisher.writer,
+                  writers.odf_odt.Writer) and not auto_encode:
+        raise ValueError('The ODT writer generates binary output and cannot '
+                         'be used with `auto_encode=False`')
     publisher.process_programmatic_settings(
         settings_spec, settings_overrides, config_section)
     publisher.set_source(source, source_path)
     publisher.set_destination(destination, destination_path)
-    if not auto_encode and isinstance(publisher.destination, io.StringOutput):
+    if isinstance(publisher.destination, io.StringOutput):
         publisher.destination.auto_encode = auto_encode
     output = publisher.publish(enable_exit_status=enable_exit_status)
     return output, publisher
diff --git a/docutils/test/test_publisher.py b/docutils/test/test_publisher.py
index ad4e098db..9911163bf 100755
--- a/docutils/test/test_publisher.py
+++ b/docutils/test/test_publisher.py
@@ -64,6 +64,9 @@ exposed_pseudoxml_output = """\
 
 class PublisherTests(unittest.TestCase):
 
+    settings = {'_disable_config': True,
+                'datestamp': False}
+
     def test_input_error_handling(self):
         # core.publish_cmdline(argv=['nonexisting/path'])
         # exits with a short message, if `traceback` is False,
@@ -104,8 +107,7 @@ class PublisherTests(unittest.TestCase):
         # Transparently decode `bytes` source (with "input_encoding" setting)
         # default: auto-detect, fallback utf-8
         # Output is encoded according to "output_encoding" setting.
-        settings = {'_disable_config': True,
-                    'datestamp': False}
+        settings = dict(self.settings)
         source = 'test → me'
         expected = ('<document source="<string>">\n'
                     '    <paragraph>\n'
@@ -125,16 +127,16 @@ class PublisherTests(unittest.TestCase):
         self.assertTrue(output.endswith('Grüße\n'))
 
     def test_publish_string_output_encoding(self):
-        settings = {'_disable_config': True,
-                    'datestamp': False,
-                    'output_encoding': 'latin1',
-                    'output_encoding_error_handler': 'replace'}
+        settings = dict(self.settings)
+        settings['output_encoding'] = 'latin1'
+        settings['output_encoding_error_handler'] = 'replace'
         source = 'Grüß → dich'
         expected = ('<document source="<string>">\n'
                     '    <paragraph>\n'
                     '        Grüß → dich\n')
         # current default: encode output, return `bytes`
-        output = bytes(core.publish_string(source, settings_overrides=settings))
+        output = bytes(core.publish_string(source,
+                                           settings_overrides=settings))
         self.assertEqual(output, expected.encode('latin1', 'replace'))
         # no encoding if `auto_encode` is False:
         output = core.publish_string(source, settings_overrides=settings,
@@ -142,6 +144,17 @@ class PublisherTests(unittest.TestCase):
         self.assertEqual(output, expected)
         self.assertEqual(output.encoding, 'latin1')
 
+    def test_publish_string_output_encoding_odt(self):
+        """The ODT writer generates a zip archive, not a `str`.
+
+        TODO: return `str` with document as "flat XML" (.fodt).
+        """
+        with self.assertRaises(ValueError) as cm:
+            core.publish_string('test',
+                                writer_name='odt',
+                                auto_encode=False)
+        self.assertIn('ODT writer generates binary output', str(cm.exception))
+
 
 class PublishDoctreeTestCase(unittest.TestCase, docutils.SettingsSpec):