1 files changed, 70 insertions, 57 deletions
diff --git a/docutils/tools/docutils-cli.py b/docutils/tools/docutils-cli.py
index 0edec1220..94dd2bb27 100755
--- a/docutils/tools/docutils-cli.py
+++ b/docutils/tools/docutils-cli.py
@@ -16,78 +16,91 @@
 A generic front end to the Docutils Publisher.
 """
 
-try:
-    import locale # module missing in Jython
-    locale.setlocale(locale.LC_ALL, '')
-except:
-    pass
-
 import argparse
+import locale
 import sys
 
 import docutils
 from docutils.core import Publisher, publish_cmdline
 
-usage = '%(prog)s [options] [<source> [<destination>]]'
-
-description = ('Convert plaintext documentation into useful formats.\n'
-               'Reads from <source> (default is stdin) '
-               'and writes to <destination> (default is stdout).')
-
-epilog = ('Further optional arguments depend on the selected components. '
-          'See <https://docutils.sourceforge.io/docs/user/config.html> '
-          'for the full reference. The list below adapts to your selection.')
-
 
 class CliSettingsSpec(docutils.SettingsSpec):
-    """Additional runtime settings & command-line options for the CLI."""
+    """Runtime settings & command-line options for the generic CLI."""
 
     settings_spec = (
         'Docutils CLI Options',
         None,
         (# 'help text', [<option strings>], {<keyword arguments>}
-         ('', ['--reader'], {'default': 'standalone'}),
-         ('', ['--parser'], {'default': 'restructuredtext'}),
-         ('', ['--writer'], {'default': 'html'}),
+         ('Reader name (default/current: "%default").',
+          ['--reader'], {'metavar': '<reader>'}),
+         ('Parser name (default/current: "%default").',
+          ['--parser'], {'metavar': '<parser>'}),
+         ('Writer name (default/current: "%default").',
+          ['--writer'], {'metavar': '<writer>'}),
         )
     )
     config_section = 'docutils-cli application'
     config_section_dependencies = ('applications',)
 
-# Get default components from configuration files
-# default to "html5" writer for backwards compatibility
-default_settings = Publisher().get_settings(settings_spec=CliSettingsSpec,
-                                            writer='html5')
-
-
-argparser = argparse.ArgumentParser(
-                usage=usage, description=description, epilog=epilog,
-                formatter_class=argparse.ArgumentDefaultsHelpFormatter,
-                add_help=False,)
-
-argparser.add_argument('--reader', help='reader name',
-                       default=default_settings.reader)
-argparser.add_argument('--parser', help='parser name',
-                       default=default_settings.parser)
-argparser.add_argument('--writer', help='writer name',
-                       default=default_settings.writer)
-
-(args, remainder) = argparser.parse_known_args()
-
-if '-h' in sys.argv or '--help' in sys.argv:
-    print(argparser.format_help())
-
-try:
-    publish_cmdline(reader_name=args.reader,
-                    parser_name=args.parser,
-                    writer_name=args.writer,
-                    config_section=CliSettingsSpec.config_section,
-                    argv=remainder,
-                    usage='',
-                    description='')
-except ImportError as error:
-    print('%s.' % error)
-    if '--traceback' in remainder:
-        raise
-    else:
-        print('Use "--traceback" to show details.')
+
+def main(settings_spec=CliSettingsSpec,
+         reader='standalone', parser='rst', writer='html'):
+    """Generic command line interface for the Docutils Publisher.
+    """
+    locale.setlocale(locale.LC_ALL, '')
+
+    description = ('Convert plaintext documentation into useful formats.  '
+                   'Available options depend on the selected reader, '
+                   'writer, and parser.  '
+                   + docutils.core.default_description)
+
+    default_settings = Publisher().get_settings(settings_spec=settings_spec,
+                                                reader=reader,
+                                                parser=parser,
+                                                writer=writer)
+
+    # Pre-parse the command-line with "argparse" for component-setting options
+    argparser = argparse.ArgumentParser(add_help=False)
+    argparser.add_argument('--reader', default=default_settings.reader)
+    argparser.add_argument('--parser', default=default_settings.parser)
+    argparser.add_argument('--writer', default=default_settings.writer)
+    (args, remainder) = argparser.parse_known_args()
+
+    # TODO: require source ('-' for stdin)
+    # argparser.add_argument('source')
+    # argparser.add_argument('destination', nargs='?')
+    #
+    # print usage if there is no arg
+    # (always or if sys.stdout.isatty() ?)
+    # Alternatively, print a log message to stderr.
+    #
+    # Display output on success, but keep it brief.
+    # provide a -q option to suppress all non-essential output.
+    #
+    # Consider chaining several args as input
+    # and use --output (or redirection) for output
+    # argparser.add_argument('source', nargs='+')
+    #
+    # -- https://clig.dev/#help
+
+    # Update defaults (shown in help):
+    CliSettingsSpec.settings_default_overrides = args.__dict__
+
+    try:
+        publish_cmdline(reader_name=args.reader,
+                        parser_name=args.parser,
+                        writer_name=args.writer,
+                        settings_spec = settings_spec,
+                        description=description,
+                        argv=remainder)
+    except ImportError as error:
+        print('%s.' % error, file=sys.stderr)
+        if '--traceback' in remainder:
+            raise
+        else:
+            print('Use "--traceback" to show details.')
+
+
+if __name__ == '__main__':
+    # backwards compatibility: docutils-cli.py defaults to "html5" writer:
+    main(writer='html5')