SF.net SVN: docutils:[10196 ] trunk/docutils
milde--- via Docutils-checkins <[email protected]> Thu, 07 Aug 2025 06:35:38 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10196
http://sourceforge.net/p/docutils/code/10196
Author: milde
Date: 2025-08-07 06:35:37 +0000 (Thu, 07 Aug 2025)
Log Message:
-----------
More consistent and concise command line help.
Document the short option "-e" as deprecated.
Hide "--*-encoding-error-handler" options.
On the command line, it is more convenient to append the error handler to the
matching "--*-encoding" option.
Use "metavar"s for all option arguments.
Fix typos.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docutils/frontend.py
trunk/docutils/docutils/writers/_html_base.py
trunk/docutils/docutils/writers/html4css1/__init__.py
trunk/docutils/docutils/writers/html5_polyglot/__init__.py
trunk/docutils/docutils/writers/latex2e/__init__.py
trunk/docutils/docutils/writers/odf_odt/__init__.py
trunk/docutils/docutils/writers/xetex/__init__.py
trunk/docutils/test/data/help/docutils.rst
trunk/docutils/test/data/help/rst2html.rst
trunk/docutils/test/data/help/rst2latex.rst
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/HISTORY.rst 2025-08-07 06:35:37 UTC (rev 10196)
@@ -17,9 +17,11 @@
Release 0.23b0 (unpublished)
============================
-...
+* docutils/frontend.py, docutils/writers/
+ - More consistent and concise command line help.
+
Release 0.22 (2026-07-29)
=========================
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/RELEASE-NOTES.rst 2025-08-07 06:35:37 UTC (rev 10196)
@@ -199,6 +199,9 @@
(obsoleted by the `"writer" setting`_ since Docutils 0.18)
in Docutils 2.0.
+* Drop short option ``-e`` in Docutils 2.0.
+ Use the long equivalent ``--error-encoding``.
+
* Remove the "reader_name", "parser_name", and "writer_name" arguments of
`core.Publisher.__init__()` and the `core.publish_*()` convenience
functions as well as the "parser_name" argument of `Reader.__init__()`
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/docs/user/config.rst 2025-08-07 06:35:37 UTC (rev 10196)
@@ -335,7 +335,7 @@
The text encoding [#encodings]_ for error output.
:Default: The encoding reported by ``sys.stderr``, locale encoding, or "ascii".
-:Options: ``--error-encoding``, ``-e``.
+:Options: ``--error-encoding``, ``-e`` (deprecated).
error_encoding_error_handler
@@ -345,8 +345,12 @@
Acceptable values are the `Error Handlers`_ of Python's "codecs" module.
See also output_encoding_error_handler_.
+The error handler may also be appended to the error_encoding_
+setting, delimited by a colon, e.g. ``--error-encoding=ascii:replace``.
+
:Default: "backslashreplace"
-:Options: ``--error-encoding-error-handler``, ``--error-encoding``, ``-e``.
+:Options: ``--error-encoding-error-handler``
+ (hidden, intended mainly for programmatic use).
exit_status_level
@@ -441,8 +445,9 @@
The error handler may also be appended to the input_encoding_
setting, delimited by a colon, e.g. ``--input-encoding=ascii:replace``.
-*Default*: "strict".
-*Options*: ``--input-encoding-error-handler``.
+:Default: "strict".
+:Options: ``--input-encoding-error-handler``
+ (hidden, intended mainly for programmatic use).
language_code
@@ -504,7 +509,7 @@
In non-English documents, also auto-generated labels
may contain non-ASCII characters.
-This setting is ignored by the `ODF/ODT Writer`_ which always usues UTF-8.
+This setting is ignored by the `ODF/ODT Writer`_ which always uses UTF-8.
:Default: "utf-8".
:Option: ``--output-encoding`` (shortcut ``-o`` removed in Docutils 0.22).
@@ -534,8 +539,9 @@
setting using a colon as delimiter, e.g.
``--output-encoding=ascii:xmlcharrefreplace``.
-*Default*: "strict".
-*Options*: ``--output-encoding-error-handler``.
+:Default: "strict".
+:Options: ``--output-encoding-error-handler``
+ (hidden, intended mainly for programmatic use).
record_dependencies
@@ -1366,7 +1372,7 @@
table_style
~~~~~~~~~~~
-Class value(s) added to all tables_.
+Class value(s) assigned to all tables_.
See also `table_style [latex writers]`_.
The default CSS sylesheets define:
Modified: trunk/docutils/docutils/frontend.py
===================================================================
--- trunk/docutils/docutils/frontend.py 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/docutils/frontend.py 2025-08-07 06:35:37 UTC (rev 10196)
@@ -808,9 +808,7 @@
['--input-encoding'],
{'metavar': '<name[:handler]>', 'default': 'utf-8',
'validator': validate_encoding_and_error_handler}),
- ('Specify the error handler for undecodable characters. '
- 'Choices: "strict" (default), "ignore", and "replace".',
- ['--input-encoding-error-handler'],
+ (SUPPRESS_HELP, ['--input-encoding-error-handler'],
{'default': 'strict', 'validator': validate_encoding_error_handler}),
('Specify the text encoding and optionally the error handler for '
'output. Default: utf-8.',
@@ -817,25 +815,19 @@
['--output-encoding'],
{'metavar': '<name[:handler]>', 'default': 'utf-8',
'validator': validate_encoding_and_error_handler}),
- ('Specify error handler for unencodable output characters; '
- '"strict" (default), "ignore", "replace", '
- '"xmlcharrefreplace", "backslashreplace".',
- ['--output-encoding-error-handler'],
+ (SUPPRESS_HELP, ['--output-encoding-error-handler'],
{'default': 'strict', 'validator': validate_encoding_error_handler}),
- ('Specify text encoding and optionally error handler '
- 'for error output. Default: %s.' % default_error_encoding,
+ ('Specify text encoding and optionally the error handler'
+ f' for error output. Default: {default_error_encoding}.',
['--error-encoding', '-e'],
{'metavar': '<name[:handler]>', 'default': default_error_encoding,
'validator': validate_encoding_and_error_handler}),
- ('Specify the error handler for unencodable characters in '
- 'error output. Default: %s.'
- % default_error_encoding_error_handler,
- ['--error-encoding-error-handler'],
+ (SUPPRESS_HELP, ['--error-encoding-error-handler'],
{'default': default_error_encoding_error_handler,
'validator': validate_encoding_error_handler}),
('Specify the language (as BCP 47 language tag). Default: en.',
['--language', '-l'], {'dest': 'language_code', 'default': 'en',
- 'metavar': '<name>'}),
+ 'metavar': '<tag>'}),
('Write output file dependencies to <file>.',
['--record-dependencies'],
{'metavar': '<file>', 'validator': validate_dependency_file,
Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/docutils/writers/_html_base.py 2025-08-07 06:35:37 UTC (rev 10196)
@@ -115,16 +115,16 @@
('Disable compact simple field lists.',
['--no-compact-field-lists'],
{'dest': 'compact_field_lists', 'action': 'store_false'}),
- ('Added to standard table classes. '
+ ('Class value(s) assigned to all tables. '
'Defined styles: borderless, booktabs, '
'align-left, align-center, align-right, '
'colwidths-auto, colwidths-grid.',
['--table-style'],
- {'default': ''}),
+ {'metavar': '<style>', 'default': ''}),
('Math output format (one of "MathML", "HTML", "MathJax", '
'or "LaTeX") and option(s). (default: "MathML")',
['--math-output'],
- {'default': 'MathML',
+ {'metavar': '<format [option(s)]>', 'default': 'MathML',
'validator': frontend.validate_math_output}),
('Prepend an XML declaration. ',
['--xml-declaration'],
Modified: trunk/docutils/docutils/writers/html4css1/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html4css1/__init__.py 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/docutils/writers/html4css1/__init__.py 2025-08-07 06:35:37 UTC (rev 10196)
@@ -74,7 +74,7 @@
'Math output format (one of "MathML", "HTML", "MathJax", or '
'"LaTeX") and option(s). (default: "HTML math.css")',
['--math-output'],
- {'default': 'HTML math.css',
+ {'metavar': '<format [option(s)]>', 'default': 'HTML math.css',
'validator': frontend.validate_math_output}),
xml_declaration=(
'Prepend an XML declaration (default). ',
Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2025-08-07 06:35:37 UTC (rev 10196)
@@ -93,7 +93,7 @@
('Suggest at which point images should be loaded: '
'"embed", "link" (default), or "lazy".',
['--image-loading'],
- {'choices': ('embed', 'link', 'lazy'),
+ {'metavar': '<strategy>', 'choices': ('embed', 'link', 'lazy'),
# 'default': 'link' # default set in _html_base.py
}),
('Append a self-link to section headings.',
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2025-08-07 06:35:37 UTC (rev 10196)
@@ -47,11 +47,11 @@
None,
(('Specify LaTeX documentclass. Default: "article".',
['--documentclass'],
- {'default': 'article', }),
+ {'metavar': '<documentclass>', 'default': 'article'}),
('Specify document options. Multiple options can be given, '
'separated by commas. Default: "a4paper".',
['--documentoptions'],
- {'default': 'a4paper', }),
+ {'metavar': '<options>', 'default': 'a4paper'}),
('Format for footnote references: one of "superscript" or '
'"brackets". Default: "superscript".',
['--footnote-references'],
@@ -105,7 +105,7 @@
('Customization by LaTeX code in the preamble. '
'Default: select PDF standard fonts (Times, Helvetica, Courier).',
['--latex-preamble'],
- {'default': default_preamble}),
+ {'metavar': '<preamble>', 'default': default_preamble}),
('Specify the template file. Default: "%s".' % default_template,
['--template'],
{'default': default_template, 'metavar': '<file>'}),
@@ -139,9 +139,11 @@
'validator': frontend.validate_boolean}),
('Color of any hyperlinks embedded in text. '
'Default: "blue" (use "false" to disable).',
- ['--hyperlink-color'], {'default': 'blue'}),
+ ['--hyperlink-color'],
+ {'metavar': '<color>', 'default': 'blue'}),
('Additional options to the "hyperref" package.',
- ['--hyperref-options'], {'default': ''}),
+ ['--hyperref-options'],
+ {'metavar': '<options>', 'default': ''}),
('Enable compound enumerators for nested enumerated lists '
'(e.g. "1.2.a.ii").',
['--compound-enumerators'],
@@ -166,8 +168,8 @@
('When possible, use the specified environment for literal-blocks. '
'Default: "" (fall back to "alltt").',
['--literal-block-env'],
- {'default': ''}),
- ('Deprecated alias for "--literal-block-env=verbatim".',
+ {'metavar': '<environment>', 'default': ''}),
+ (frontend.SUPPRESS_HELP, # deprecated legacy option
['--use-verbatim-when-possible'],
{'action': 'store_true',
'validator': frontend.validate_boolean}),
@@ -181,22 +183,19 @@
'action': 'append',
'validator': frontend.validate_comma_separated_list,
'choices': table_style_values}),
- ('LaTeX graphicx package option. '
- 'Possible values are "dvipdfmx", "dvips", "dvisvgm", '
- '"luatex", "pdftex", and "xetex".'
- 'Default: "".',
+ ('LaTeX graphicx package option. Default: "".',
['--graphicx-option'],
- {'default': ''}),
+ {'metavar': '<option>', 'default': ''}),
('LaTeX font encoding. '
'Possible values are "", "T1" (default), "OT1", "LGR,T1" or '
'any other combination of options to the `fontenc` package. ',
['--font-encoding'],
- {'default': 'T1'}),
+ {'metavar': '<encoding>', 'default': 'T1'}),
('Per default the latex-writer puts the reference title into '
- 'hyperreferences. Specify "ref*" or "pageref*" to get the section '
+ 'hyperreferences. Specify "ref" or "pageref" to get the section '
'number or the page number.',
['--reference-label'],
- {'default': ''}),
+ {'metavar': '<command name>', 'default': ''}),
('Specify style and database(s) for bibtex, for example '
'"--use-bibtex=unsrt,mydb1,mydb2". Provisional!',
['--use-bibtex'],
Modified: trunk/docutils/docutils/writers/odf_odt/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/odf_odt/__init__.py 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/docutils/writers/odf_odt/__init__.py 2025-08-07 06:35:37 UTC (rev 10196)
@@ -386,10 +386,9 @@
('Specify a stylesheet. '
'Default: "%s"' % default_stylesheet_path,
['--stylesheet'],
- {
- 'default': default_stylesheet_path,
- 'dest': 'stylesheet'
- }),
+ {'default': default_stylesheet_path,
+ 'dest': 'stylesheet',
+ 'metavar': '<filename>'}),
('Specify an ODF-specific configuration/mapping file '
'relative to the current working directory.',
['--odf-config-file'],
Modified: trunk/docutils/docutils/writers/xetex/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/xetex/__init__.py 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/docutils/writers/xetex/__init__.py 2025-08-07 06:35:37 UTC (rev 10196)
@@ -57,7 +57,8 @@
latex_preamble=('Customization by LaTeX code in the preamble. '
'Default: select "Linux Libertine" fonts.',
['--latex-preamble'],
- {'default': default_preamble}),
+ {'metavar': '<preamble>',
+ 'default': default_preamble}),
)
def __init__(self) -> None:
Modified: trunk/docutils/test/data/help/docutils.rst
===================================================================
--- trunk/docutils/test/data/help/docutils.rst 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/test/data/help/docutils.rst 2025-08-07 06:35:37 UTC (rev 10196)
@@ -61,23 +61,13 @@
--input-encoding=<name[:handler]>
Specify the encoding and optionally the error handler
of input text. Default: utf-8.
---input-encoding-error-handler=INPUT_ENCODING_ERROR_HANDLER
- Specify the error handler for undecodable characters.
- Choices: "strict" (default), "ignore", and "replace".
--output-encoding=<name[:handler]>
Specify the text encoding and optionally the error
handler for output. Default: utf-8.
---output-encoding-error-handler=OUTPUT_ENCODING_ERROR_HANDLER
- Specify error handler for unencodable output
- characters; "strict" (default), "ignore", "replace",
- "xmlcharrefreplace", "backslashreplace".
--error-encoding=<name[:handler]>, -e <name[:handler]>
- Specify text encoding and optionally error handler for
- error output. Default: utf-8.
---error-encoding-error-handler=ERROR_ENCODING_ERROR_HANDLER
- Specify the error handler for unencodable characters
- in error output. Default: backslashreplace.
---language=<name>, -l <name>
+ Specify text encoding and optionally the error handler
+ for error output. Default: utf-8.
+--language=<tag>, -l <tag>
Specify the language (as BCP 47 language tag).
Default: en.
--record-dependencies=<file>
@@ -189,11 +179,10 @@
simple field lists. (default)
--no-compact-field-lists
Disable compact simple field lists.
---table-style=TABLE_STYLE
- Added to standard table classes. Defined styles:
+--table-style=<style> Class value(s) assigned to all tables. Defined styles:
borderless, booktabs, align-left, align-center, align-
right, colwidths-auto, colwidths-grid.
---math-output=MATH_OUTPUT
+--math-output=<format [option(s)]>
Math output format (one of "MathML", "HTML",
"MathJax", or "LaTeX") and option(s). (default:
"MathML")
@@ -206,7 +195,7 @@
HTML5 Writer Options
--------------------
---image-loading=IMAGE_LOADING
+--image-loading=<strategy>
Suggest at which point images should be loaded:
"embed", "link" (default), or "lazy".
--section-self-link Append a self-link to section headings.
Modified: trunk/docutils/test/data/help/rst2html.rst
===================================================================
--- trunk/docutils/test/data/help/rst2html.rst 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/test/data/help/rst2html.rst 2025-08-07 06:35:37 UTC (rev 10196)
@@ -62,23 +62,13 @@
--input-encoding=<name[:handler]>
Specify the encoding and optionally the error handler
of input text. Default: utf-8.
---input-encoding-error-handler=INPUT_ENCODING_ERROR_HANDLER
- Specify the error handler for undecodable characters.
- Choices: "strict" (default), "ignore", and "replace".
--output-encoding=<name[:handler]>
Specify the text encoding and optionally the error
handler for output. Default: utf-8.
---output-encoding-error-handler=OUTPUT_ENCODING_ERROR_HANDLER
- Specify error handler for unencodable output
- characters; "strict" (default), "ignore", "replace",
- "xmlcharrefreplace", "backslashreplace".
--error-encoding=<name[:handler]>, -e <name[:handler]>
- Specify text encoding and optionally error handler for
- error output. Default: utf-8.
---error-encoding-error-handler=ERROR_ENCODING_ERROR_HANDLER
- Specify the error handler for unencodable characters
- in error output. Default: backslashreplace.
---language=<name>, -l <name>
+ Specify text encoding and optionally the error handler
+ for error output. Default: utf-8.
+--language=<tag>, -l <tag>
Specify the language (as BCP 47 language tag).
Default: en.
--record-dependencies=<file>
@@ -190,11 +180,10 @@
simple field lists. (default)
--no-compact-field-lists
Disable compact simple field lists.
---table-style=TABLE_STYLE
- Added to standard table classes. Defined styles:
+--table-style=<style> Class value(s) assigned to all tables. Defined styles:
borderless, booktabs, align-left, align-center, align-
right, colwidths-auto, colwidths-grid.
---math-output=MATH_OUTPUT
+--math-output=<format [option(s)]>
Math output format (one of "MathML", "HTML",
"MathJax", or "LaTeX") and option(s). (default: "HTML
math.css")
Modified: trunk/docutils/test/data/help/rst2latex.rst
===================================================================
--- trunk/docutils/test/data/help/rst2latex.rst 2025-08-06 16:42:09 UTC (rev 10195)
+++ trunk/docutils/test/data/help/rst2latex.rst 2025-08-07 06:35:37 UTC (rev 10196)
@@ -62,23 +62,13 @@
--input-encoding=<name[:handler]>
Specify the encoding and optionally the error handler
of input text. Default: utf-8.
---input-encoding-error-handler=INPUT_ENCODING_ERROR_HANDLER
- Specify the error handler for undecodable characters.
- Choices: "strict" (default), "ignore", and "replace".
--output-encoding=<name[:handler]>
Specify the text encoding and optionally the error
handler for output. Default: utf-8.
---output-encoding-error-handler=OUTPUT_ENCODING_ERROR_HANDLER
- Specify error handler for unencodable output
- characters; "strict" (default), "ignore", "replace",
- "xmlcharrefreplace", "backslashreplace".
--error-encoding=<name[:handler]>, -e <name[:handler]>
- Specify text encoding and optionally error handler for
- error output. Default: utf-8.
---error-encoding-error-handler=ERROR_ENCODING_ERROR_HANDLER
- Specify the error handler for unencodable characters
- in error output. Default: backslashreplace.
---language=<name>, -l <name>
+ Specify text encoding and optionally the error handler
+ for error output. Default: utf-8.
+--language=<tag>, -l <tag>
Specify the language (as BCP 47 language tag).
Default: en.
--record-dependencies=<file>
@@ -155,9 +145,9 @@
LaTeX-Specific Options
----------------------
---documentclass=DOCUMENTCLASS
+--documentclass=<documentclass>
Specify LaTeX documentclass. Default: "article".
---documentoptions=DOCUMENTOPTIONS
+--documentoptions=<options>
Specify document options. Multiple options can be
given, separated by commas. Default: "a4paper".
--footnote-references=<format>
@@ -188,7 +178,7 @@
Comma-separated list of directories where stylesheets
are found. Used by --stylesheet-path when expanding
relative path arguments. Default: ".".
---latex-preamble=LATEX_PREAMBLE
+--latex-preamble=<preamble>
Customization by LaTeX code in the preamble. Default:
select PDF standard fonts (Times, Helvetica, Courier).
--template=<file> Specify the template file. Default: "default.tex".
@@ -201,10 +191,10 @@
--topic-abstract Typeset abstract as topic. (default)
--use-latex-abstract Use LaTeX abstract environment for the document's
abstract.
---hyperlink-color=HYPERLINK_COLOR
+--hyperlink-color=<color>
Color of any hyperlinks embedded in text. Default:
"blue" (use "false" to disable).
---hyperref-options=HYPERREF_OPTIONS
+--hyperref-options=<options>
Additional options to the "hyperref" package.
--compound-enumerators Enable compound enumerators for nested enumerated
lists (e.g. "1.2.a.ii").
@@ -222,26 +212,22 @@
Set the separator between section number and
enumerator for compound enumerated lists. Default:
"-".
---literal-block-env=LITERAL_BLOCK_ENV
+--literal-block-env=<environment>
When possible, use the specified environment for
literal-blocks. Default: "" (fall back to "alltt").
---use-verbatim-when-possible
- Deprecated alias for "--literal-block-env=verbatim".
--table-style=<format> Table style. "standard" with horizontal and vertical
lines, "booktabs" (LaTeX booktabs style) only
horizontal lines above and below the table and below
the header, or "borderless". Default: "standard"
---graphicx-option=GRAPHICX_OPTION
- LaTeX graphicx package option. Possible values are
- "dvipdfmx", "dvips", "dvisvgm", "luatex", "pdftex",
- and "xetex".Default: "".
---font-encoding=FONT_ENCODING
+--graphicx-option=<option>
+ LaTeX graphicx package option. Default: "".
+--font-encoding=<encoding>
LaTeX font encoding. Possible values are "", "T1"
(default), "OT1", "LGR,T1" or any other combination of
options to the `fontenc` package.
---reference-label=REFERENCE_LABEL
+--reference-label=<command name>
Per default the latex-writer puts the reference title
- into hyperreferences. Specify "ref*" or "pageref*" to
+ into hyperreferences. Specify "ref" or "pageref" to
get the section number or the page number.
--use-bibtex=<style,bibfile[,bibfile,...]>
Specify style and database(s) for bibtex, for example
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins