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

8 files changed, 68 insertions, 13 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 9f5fb4e97..ef841514b 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -27,6 +27,11 @@ Release 0.20b (unpublished)
     output as binary data in a `bytes` object.
   - New functions `rst2…()` for use as "console_scripts" `entry point`_.
 
+* docutils/frontend.py
+
+  - New setting ``output``. Obsoletes the ``<destination>`` positional
+    argument (cf. "Future changes" in the RELEASE-NOTES).
+
 * docutils/languages/
   docutils/parsers/rst/languages/
 
diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index 2be4d5550..c27e4eeb2 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -420,6 +420,21 @@ Default: English ("en").  Options: ``--language, -l``.
 
 .. _class attribute: ../ref/doctree.html#classes
 
+
+output
+------
+
+The name of the output destination. Use ``-`` for stdout.
+
+Obsoletes the ``<destination>`` positional argument
+(cf. `Future changes`_ in the RELEASE-NOTES).
+
+Default: None (stdout). Option: ``--output``.
+
+New in Docutils 0.20.
+
+.. _Future changes: ../../RELEASE-NOTES.html#future-changes
+
 output_encoding
 ---------------
 
diff --git a/docutils/docutils/core.py b/docutils/docutils/core.py
index d9b62860c..b369a9cfe 100644
--- a/docutils/docutils/core.py
+++ b/docutils/docutils/core.py
@@ -192,9 +192,16 @@ class Publisher:
 
     def set_destination(self, destination=None, destination_path=None):
         if destination_path is None:
-            destination_path = self.settings._destination
-        else:
-            self.settings._destination = destination_path
+            if (self.settings.output and self.settings._destination
+                and self.settings.output != self.settings._destination):
+                raise SystemExit('The positional argument <destination> is '
+                                 'obsoleted by the --output option.  '
+                                 'You cannot use them together.')
+            if self.settings.output == '-':      # means stdout
+                self.settings.output = None
+            destination_path = (self.settings.output
+                                or self.settings._destination)
+        self.settings._destination = destination_path
         self.destination = self.destination_class(
             destination=destination, destination_path=destination_path,
             encoding=self.settings.output_encoding,
@@ -362,8 +369,8 @@ default_description = (
 # TODO: or not to do?  cf. https://clig.dev/#help
 #
 # Display output on success, but keep it brief.
-#
 # Provide a -q option to suppress all non-essential output.
+#
 # Chain several args as input and use --output or redirection for output:
 #   argparser.add_argument('source', nargs='+')
 #
diff --git a/docutils/docutils/frontend.py b/docutils/docutils/frontend.py
index 62769aa30..e9a2e25bc 100644
--- a/docutils/docutils/frontend.py
+++ b/docutils/docutils/frontend.py
@@ -461,8 +461,11 @@ class OptionParser(optparse.OptionParser, docutils.SettingsSpec):
     settings_spec = (
         'General Docutils Options',
         None,
-        (('Specify the document title as metadata.',
-          ['--title'], {}),
+        (('Output destination name. Obsoletes the <destination> '
+          'positional argument. Default: None (stdout).',
+          ['--output'], {'metavar': '<destination>'}),
+         ('Specify the document title as metadata.',
+          ['--title'], {'metavar': '<title>'}),
          ('Include a "Generated by Docutils" credit and link.',
           ['--generator', '-g'], {'action': 'store_true',
                                   'validator': validate_boolean}),
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))