Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[9345] trunk/docutils
|
From: <mi...@us...> - 2023-04-13 14:27:25
|
Revision: 9345
http://sourceforge.net/p/docutils/code/9345
Author: milde
Date: 2023-04-13 14:27:23 +0000 (Thu, 13 Apr 2023)
Log Message:
-----------
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`.
Modified Paths:
--------------
trunk/docutils/docs/user/config.txt
trunk/docutils/docs/user/odt.txt
trunk/docutils/docutils/core.py
trunk/docutils/test/test_publisher.py
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2023-04-12 16:52:19 UTC (rev 9344)
+++ trunk/docutils/docs/user/config.txt 2023-04-13 14:27:23 UTC (rev 9345)
@@ -444,8 +444,10 @@
(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,11 +2001,22 @@
__ `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 @@
no-cloak-email-addresses
~~~~~~~~~~~~~~~~~~~~~~~~
+
Do not obfuscate email addresses.
table-border-thickness
@@ -2060,6 +2074,7 @@
create-links
~~~~~~~~~~~~
+
Create links.
no-links
@@ -2111,9 +2126,7 @@
time, etc" in the `Odt Writer for Docutils`_ document for
details.
-.. _Odt Writer for Docutils: odt.html
-
[pseudoxml writer]
------------------
Modified: trunk/docutils/docs/user/odt.txt
===================================================================
--- trunk/docutils/docs/user/odt.txt 2023-04-12 16:52:19 UTC (rev 9344)
+++ trunk/docutils/docs/user/odt.txt 2023-04-13 14:27:23 UTC (rev 9345)
@@ -1,7 +1,7 @@
.. include:: ../header.txt
=======================
-Odt Writer for Docutils
+ODT Writer for Docutils
=======================
:Author: Dave Kuhlman
@@ -10,8 +10,8 @@
: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,21 +21,14 @@
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`_
+__ https://en.wikipedia.org/wiki/OpenDocument#Software
-- `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`_
-
-
Requirements
============
@@ -57,7 +50,7 @@
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,27 +59,31 @@
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 @@
-
+.. _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
Modified: trunk/docutils/docutils/core.py
===================================================================
--- trunk/docutils/docutils/core.py 2023-04-12 16:52:19 UTC (rev 9344)
+++ trunk/docutils/docutils/core.py 2023-04-13 14:27:23 UTC (rev 9345)
@@ -23,6 +23,7 @@
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 @@
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 @@
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
Modified: trunk/docutils/test/test_publisher.py
===================================================================
--- trunk/docutils/test/test_publisher.py 2023-04-12 16:52:19 UTC (rev 9344)
+++ trunk/docutils/test/test_publisher.py 2023-04-13 14:27:23 UTC (rev 9345)
@@ -64,6 +64,9 @@
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 @@
# 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 @@
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,7 +144,18 @@
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):
settings_default_overrides = {
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
