New general setting "output".

This setting obsoletes the positional argument <destination>.
Cf. the announcement of command line pattern changes in the
RELEASE-NOTES.

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

4 files changed, 32 insertions, 7 deletions

diff --git a/docutils/test/data/help/docutils.txt b/docutils/test/data/help/docutils.txt
index 5b260c333..0811544bf 100644
--- a/docutils/test/data/help/docutils.txt
+++ b/docutils/test/data/help/docutils.txt
@@ -11,7 +11,9 @@ Options
 =======
 General Docutils Options
 ------------------------
---title=TITLE           Specify the document title as metadata.
+--output=<destination>  Output destination name. Obsoletes the <destination>
+                        positional argument. Default: None (stdout).
+--title=<title>         Specify the document title as metadata.
 --generator, -g         Include a "Generated by Docutils" credit and link.
 --no-generator          Do not include a generator credit.
 --date, -d              Include the date at the end of the document (UTC).
diff --git a/docutils/test/data/help/rst2html.txt b/docutils/test/data/help/rst2html.txt
index fc4975991..e51701172 100644
--- a/docutils/test/data/help/rst2html.txt
+++ b/docutils/test/data/help/rst2html.txt
@@ -12,7 +12,9 @@ Options
 =======
 General Docutils Options
 ------------------------
---title=TITLE           Specify the document title as metadata.
+--output=<destination>  Output destination name. Obsoletes the <destination>
+                        positional argument. Default: None (stdout).
+--title=<title>         Specify the document title as metadata.
 --generator, -g         Include a "Generated by Docutils" credit and link.
 --no-generator          Do not include a generator credit.
 --date, -d              Include the date at the end of the document (UTC).
diff --git a/docutils/test/data/help/rst2latex.txt b/docutils/test/data/help/rst2latex.txt
index 12ea0d40c..6153c6096 100644
--- a/docutils/test/data/help/rst2latex.txt
+++ b/docutils/test/data/help/rst2latex.txt
@@ -12,7 +12,9 @@ Options
 =======
 General Docutils Options
 ------------------------
---title=TITLE           Specify the document title as metadata.
+--output=<destination>  Output destination name. Obsoletes the <destination>
+                        positional argument. Default: None (stdout).
+--title=<title>         Specify the document title as metadata.
 --generator, -g         Include a "Generated by Docutils" credit and link.
 --no-generator          Do not include a generator credit.
 --date, -d              Include the date at the end of the document (UTC).
diff --git a/docutils/test/test_publisher.py b/docutils/test/test_publisher.py
index 6177ad6d2..492cdbac1 100755
--- a/docutils/test/test_publisher.py
+++ b/docutils/test/test_publisher.py
@@ -19,7 +19,7 @@ if __name__ == '__main__':
     sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
 import docutils
-from docutils import core, nodes, io
+from docutils import core, nodes
 
 # DATA_ROOT is ./test/data/ from the docutils root
 DATA_ROOT = os.path.join(os.path.abspath(os.path.dirname(__file__)), 'data')
@@ -75,11 +75,30 @@ class PublisherTests(unittest.TestCase):
 
     def test_output_error_handling(self):
         # pass IOErrors to calling application if `traceback` is True
-        with self.assertRaises(io.OutputError):
+        with self.assertRaises(docutils.io.OutputError):
             core.publish_cmdline(argv=[os.path.join(DATA_ROOT, 'include.txt'),
                                        'nonexisting/path'],
                                  settings_overrides={'traceback': True})
 
+    def test_set_destination(self):
+        # Exit if `_destination` and `output` settings conflict.
+        publisher = core.Publisher()
+        publisher.get_settings(output='out_name', _destination='out_name')
+        # no conflict if both have same value:
+        publisher.set_destination()
+        # no conflict if both are overridden:
+        publisher.set_destination(destination_path='winning_dest')
+        # ... also sets _destination to 'winning_dest' -> conflict
+        with self.assertRaises(SystemExit):
+            publisher.set_destination()
+
+    def test_destination_output_conflict(self):
+        # Exit if positional argument and --output option conflict.
+        settings = {'output': 'out_name'}
+        with self.assertRaises(SystemExit):
+            core.publish_cmdline(argv=['-', 'dest_name'],
+                                 settings_overrides=settings)
+
     def test_publish_string(self):
         # Transparently decode `bytes` source (with "input_encoding" setting)
         # default: auto-detect, fallback utf-8
@@ -107,7 +126,7 @@ class PublishDoctreeTestCase(unittest.TestCase, docutils.SettingsSpec):
 
     settings_default_overrides = {
         '_disable_config': True,
-        'warning_stream': io.NullOutput()}
+        'warning_stream': docutils.io.NullOutput()}
 
     def test_publish_doctree(self):
         # Test `publish_doctree` and `publish_from_doctree`.
@@ -144,7 +163,7 @@ class PublishDoctreeTestCase(unittest.TestCase, docutils.SettingsSpec):
 
         # Test publishing parts using document as the source.
         parts = core.publish_parts(
-            reader_name='doctree', source_class=io.DocTreeInput,
+            reader_name='doctree', source_class=docutils.io.DocTreeInput,
             source=doctree, source_path='test', writer_name='html',
             settings_spec=self)
         self.assertTrue(isinstance(parts, dict))