[Docutils-checkins] SF.net SVN: docutils:[9327] trunk/docutils

[<mi...@us...>]

Revision: 9327
          http://sourceforge.net/p/docutils/code/9327
Author:   milde
Date:     2023-02-07 14:24:19 +0000 (Tue, 07 Feb 2023)
Log Message:
-----------
Announce command-line usage pattern change.

Cf. [feature-requests:#36].

Modified Paths:
--------------
    trunk/docutils/RELEASE-NOTES.txt
    trunk/docutils/docs/user/tools.txt

Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt	2023-02-06 21:34:19 UTC (rev 9326)
+++ trunk/docutils/RELEASE-NOTES.txt	2023-02-07 14:24:19 UTC (rev 9327)
@@ -65,6 +65,25 @@
 
     __ docs/user/html.html#html
 
+* The command-line usage pattern will change:
+
+  .. code:: diff
+
+       - <toolname> [options] [<source> [<destination>]]
+       + <toolname> [options] source [source2 [source3 [...]]]
+
+  * Remove short options ``-i`` and ``-o`` in Docutils 0.22.
+    Use the long equivalents ``--input-encoding`` and ``--output-encoding``.
+
+  * Stop accepting the `<destination>` positional argument in Docutils 1.0.
+    Use output redirection ``>`` or the option ``--output=<destination>``
+    (available since Docutils 0.20).
+
+  * Accept more than one source document and the short option
+    ``-o`` for ``--output`` in Docutils 2.0
+
+  For the rationale, see https://clig.dev/#arguments-and-flags.
+
 * `Input encoding`_:
 
   - Raise UnicodeError (instead of falling back to the locale encoding)

Modified: trunk/docutils/docs/user/tools.txt
===================================================================
--- trunk/docutils/docs/user/tools.txt	2023-02-06 21:34:19 UTC (rev 9326)
+++ trunk/docutils/docs/user/tools.txt	2023-02-07 14:24:19 UTC (rev 9327)
@@ -14,10 +14,15 @@
 
 .. note::
    Docutils front-end tool names, install details and the set of
-   auto-installed tools will `change in Docutils 0.21`__.
+   auto-installed tools will change in Docutils 0.21.
 
-   __ ../../RELEASE-NOTES.html#future-changes
+   The command line usage pattern will change over the next releases.
 
+   See `Future changes`__ in the RELEASE-NOTES.
+   
+__ RELEASE-NOTES.html#future-changes
+
+
 --------------
  Introduction
 --------------
@@ -49,6 +54,7 @@
 
 .. [#] The exceptions are buildhtml.py_ and rst2odt_prepstyles.py_.
 
+
 Getting Help
 ============
 

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.