Menu
▾
▴
docutils-checkins
|
From: <mi...@us...> - 2022-12-02 17:14:08
|
Revision: 9302
http://sourceforge.net/p/docutils/code/9302
Author: milde
Date: 2022-12-02 17:14:05 +0000 (Fri, 02 Dec 2022)
Log Message:
-----------
Simplify error message if recommonmark is missing.
As we provide a mock Sphinx package, there is no need to emphasise
recommonmark's dependency on Sphinx.
Wrap error message. Adapt the test case.
Modified Paths:
--------------
trunk/docutils/docutils/parsers/recommonmark_wrapper.py
trunk/docutils/test/test_parsers/test_get_parser_class.py
Modified: trunk/docutils/docutils/parsers/recommonmark_wrapper.py
===================================================================
--- trunk/docutils/docutils/parsers/recommonmark_wrapper.py 2022-12-02 17:13:54 UTC (rev 9301)
+++ trunk/docutils/docutils/parsers/recommonmark_wrapper.py 2022-12-02 17:14:05 UTC (rev 9302)
@@ -45,9 +45,8 @@
from recommonmark.parser import CommonMarkParser
except ImportError as err:
raise ImportError(
- 'Parsing "recommonmark" Markdown flavour requires the '
- 'package https://pypi.org/project/recommonmark which '
- 'in turn depends on https://pypi.org/project/sphinx.'
+ 'Parsing "recommonmark" Markdown flavour requires the\n'
+ ' package https://pypi.org/project/recommonmark.'
) from err
else:
if recommonmark.__version__ < '0.6.0':
Modified: trunk/docutils/test/test_parsers/test_get_parser_class.py
===================================================================
--- trunk/docutils/test/test_parsers/test_get_parser_class.py 2022-12-02 17:13:54 UTC (rev 9301)
+++ trunk/docutils/test/test_parsers/test_get_parser_class.py 2022-12-02 17:14:05 UTC (rev 9302)
@@ -49,7 +49,7 @@
def test_missing_parser_message(self):
with self.assertRaisesRegex(ImportError,
- 'requires the package .*recommonmark'):
+ 'requires the.*package .* recommonmark'):
publish_string('test data', parser_name='recommonmark')
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2022-12-02 23:07:36
|
Revision: 9303
http://sourceforge.net/p/docutils/code/9303
Author: milde
Date: 2022-12-02 23:07:33 +0000 (Fri, 02 Dec 2022)
Log Message:
-----------
Allow empty string as encoding value (to re-activate default).
Value `None` cannot be specified on the command line.
Use ``--input-encoding=""`` go back to Docutil's default behaviur
(use encoding indicated in the file or fallbacks)
if a config file sets "input_encoding" to another value.
Modified Paths:
--------------
trunk/docutils/docutils/frontend.py
trunk/docutils/test/test_io.py
Modified: trunk/docutils/docutils/frontend.py
===================================================================
--- trunk/docutils/docutils/frontend.py 2022-12-02 17:14:05 UTC (rev 9302)
+++ trunk/docutils/docutils/frontend.py 2022-12-02 23:07:33 UTC (rev 9303)
@@ -92,6 +92,8 @@
def validate_encoding(setting, value, option_parser,
config_parser=None, config_section=None):
+ if value == '':
+ return None # allow overwriting a config file value
try:
codecs.lookup(value)
except LookupError:
Modified: trunk/docutils/test/test_io.py
===================================================================
--- trunk/docutils/test/test_io.py 2022-12-02 17:14:05 UTC (rev 9302)
+++ trunk/docutils/test/test_io.py 2022-12-02 23:07:33 UTC (rev 9303)
@@ -70,8 +70,9 @@
self.assertEqual(io.check_encoding(io.FileInput(), 'ascii'), None)
# stream.encoding does not exist:
self.assertEqual(io.check_encoding(BBuf, 'ascii'), None)
- # encoding is None:
+ # encoding is None or empty string:
self.assertEqual(io.check_encoding(mock_stdout, None), None)
+ self.assertEqual(io.check_encoding(mock_stdout, ''), None)
# encoding is invalid
self.assertEqual(io.check_encoding(mock_stdout, 'UTF-9'), None)
@@ -142,6 +143,7 @@
def test_heuristics_no_utf8(self):
# if no encoding is given and decoding with 'utf-8' fails,
# use either the locale encoding (if specified) or 'latin-1':
+ # Provisional: the second fallback 'latin-1' will be dropped
probed_encodings = (io._locale_encoding, 'latin-1') # noqa
input = io.FileInput(
source_path=os.path.join(DATA_ROOT, 'latin1.txt'))
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2022-12-13 21:45:25
|
Revision: 9308
http://sourceforge.net/p/docutils/code/9308
Author: milde
Date: 2022-12-13 21:45:23 +0000 (Tue, 13 Dec 2022)
Log Message:
-----------
Update test documentation. Set executable bit on test scripts.
Don't mention the "nose" test framework.
(It is unmaintained, deprecated, and fails to find all test cases.)
Hint to a possible future dependency on "pytest".
Two recently added test scripts missed the executable bit.
Modified Paths:
--------------
trunk/docutils/docs/dev/testing.txt
trunk/docutils/test/test_parsers/test_get_parser_class.py
trunk/docutils/test/test_parsers/test_parser.py
Property Changed:
----------------
trunk/docutils/test/test_parsers/test_get_parser_class.py
trunk/docutils/test/test_parsers/test_parser.py
Modified: trunk/docutils/docs/dev/testing.txt
===================================================================
--- trunk/docutils/docs/dev/testing.txt 2022-12-09 12:31:29 UTC (rev 9307)
+++ trunk/docutils/docs/dev/testing.txt 2022-12-13 21:45:23 UTC (rev 9308)
@@ -40,15 +40,15 @@
.. note::
The ``alltests.py`` test runner is based on the standard library's unittest_
framework.
- Since Docutils 0.19, running ``python -m unittest``, the pytest_, and the
- nose_ frameworks no longer result in spurious failures (cf. `bug #270`_).
- However, there are differences in the reported number of tests and in
- test coverage.
+ Since Docutils 0.19, running ``python -m unittest`` and the pytest_
+ framework no longer result in spurious failures (cf. `bug #270`_).
+ However, there are differences in the reported number of tests
+ (``alltests.py`` also counts sub-tests).
+ In future, running the test suite may require pytest_.
__ policies.html#check-ins
.. _unittest: https://docs.python.org/3/library/unittest.html
.. _pytest: https://pypi.org/project/pytest
-.. _nose: https://pypi.org/project/nose
.. _`bug #270`: https://sourceforge.net/p/docutils/bugs/270/
@@ -93,9 +93,8 @@
python3.11 -u alltests.py
.. note::
- When using the `Python launcher for Windows`__, make sure to
- specify a Python version, e.g., ``py -3.9 -u alltests.py`` for
- Python 3.9.
+ When using the `Python launcher for Windows`__, specify the Python version
+ as option, e.g., ``py -3.9 -u alltests.py`` for Python 3.9.
.. cf. https://sourceforge.net/p/docutils/bugs/434/
__ https://docs.python.org/3/using/windows.html#python-launcher-for-windows
@@ -107,6 +106,7 @@
__ https://docs.python.org/3/whatsnew/3.11.html
+
.. _supported versions:
.. _supported Python versions: ../../README.html#requirements
.. _pyenv: https://github.com/yyuu/pyenv
Index: trunk/docutils/test/test_parsers/test_get_parser_class.py
===================================================================
--- trunk/docutils/test/test_parsers/test_get_parser_class.py 2022-12-09 12:31:29 UTC (rev 9307)
+++ trunk/docutils/test/test_parsers/test_get_parser_class.py 2022-12-13 21:45:23 UTC (rev 9308)
Property changes on: trunk/docutils/test/test_parsers/test_get_parser_class.py
___________________________________________________________________
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Index: trunk/docutils/test/test_parsers/test_parser.py
===================================================================
--- trunk/docutils/test/test_parsers/test_parser.py 2022-12-09 12:31:29 UTC (rev 9307)
+++ trunk/docutils/test/test_parsers/test_parser.py 2022-12-13 21:45:23 UTC (rev 9308)
Property changes on: trunk/docutils/test/test_parsers/test_parser.py
___________________________________________________________________
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2022-12-17 12:17:35
|
Revision: 9310
http://sourceforge.net/p/docutils/code/9310
Author: milde
Date: 2022-12-17 12:17:32 +0000 (Sat, 17 Dec 2022)
Log Message:
-----------
Fix [bugs:#463]. Spurious comma in deprecation warning.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/docutils/nodes.py
trunk/docutils/test/test_nodes.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2022-12-13 21:45:32 UTC (rev 9309)
+++ trunk/docutils/HISTORY.txt 2022-12-17 12:17:32 UTC (rev 9310)
@@ -34,6 +34,7 @@
- Fix `previous_sibling()` method that led to invalid HTML in some cases
(cf. patch #195).
+ - Fix bug #463. Spurious comma in deprecation warning.
* docutils/parsers/recommonmark_wrapper.py
@@ -67,8 +68,8 @@
Changes to the HTML output (no space character before closing tag of
XML declaration, order of metadata elements)
don't affect the HTML semantics, styling, and rendering.
-
- - Wrap definition lists with "details" class argument in a <div>
+
+ - Wrap definition lists with "details" class argument in a <div>
with the "id" and "class" values of the list node.
- Use dpub-ARIA role "doc-footnote" (instead of ARIA role "note")
@@ -4150,7 +4151,7 @@
.. _view_mode: docs/user/config.html#view-mode
-
+
..
Local Variables:
mode: indented-text
Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py 2022-12-13 21:45:32 UTC (rev 9309)
+++ trunk/docutils/docutils/nodes.py 2022-12-17 12:17:32 UTC (rev 9310)
@@ -1068,7 +1068,7 @@
def set_class(self, name):
"""Add a new class to the "classes" attribute."""
warnings.warn('docutils.nodes.Element.set_class() is deprecated; '
- ' and will be removed in Docutils 0.21 or later.',
+ ' and will be removed in Docutils 0.21 or later.'
"Append to Element['classes'] list attribute directly",
DeprecationWarning, stacklevel=2)
assert ' ' not in name
Modified: trunk/docutils/test/test_nodes.py
===================================================================
--- trunk/docutils/test/test_nodes.py 2022-12-13 21:45:32 UTC (rev 9309)
+++ trunk/docutils/test/test_nodes.py 2022-12-17 12:17:32 UTC (rev 9310)
@@ -352,7 +352,12 @@
node = nodes.Element('Möhren', nodes.Text('Möhren'))
self.assertEqual(str(node), '<Element>Möhren</Element>')
+ def test_set_class_deprecation_warning(self):
+ node = nodes.Element('test node')
+ with self.assertWarns(DeprecationWarning):
+ node.set_class('parrot')
+
class MiscTests(unittest.TestCase):
def test_node_class_names(self):
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2022-12-19 20:43:10
|
Revision: 9312
http://sourceforge.net/p/docutils/code/9312
Author: milde
Date: 2022-12-19 20:43:08 +0000 (Mon, 19 Dec 2022)
Log Message:
-----------
Fix [bugs:#384]: allow omission of citations with "use_bibtex" setting.
If the "use_bibtex" LaTeX writer setting is active (i.e. not empty),
citations are added by LaTeX/BibTeX from a database for all citation references
in the document.
The reference resolver transform now skips `citation_reference` nodes instead of
expecting matching `citation` nodes in this case.
"use_bibtex" content is now transformed to a list by the
`frontend.validate_comma_separated_list()` validator.
As BibTeX works only with "LaTeX citations", the "use_latex_citations" setting
is set to True whenever "use_bibtex" is not empty.
Update documentation.
The test function, added in the last commit, now passes.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docutils/transforms/references.py
trunk/docutils/docutils/writers/latex2e/__init__.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2022-12-19 20:42:55 UTC (rev 9311)
+++ trunk/docutils/HISTORY.txt 2022-12-19 20:43:08 UTC (rev 9312)
@@ -45,6 +45,12 @@
- `Transformer.populate_from_components()` now silently ignores
components that are not instances of `docutils.TransformSpec`.
+* docutils/transforms/references.py
+
+ - Ignore `citation_reference` nodes if the "use_bibex" setting is
+ active. In this case, citations are provided by LaTeX/BibTeX.
+ Fixes bug #384.
+
* docutils/utils/__init__.py
- New utility function `xml_declaration()`.
@@ -79,6 +85,7 @@
- Do not insert ``\usepackage[utf8]{inputenc}`` into UTF-8 encoded
LaTeX sources. UTF-8 is the default encoding for LaTeX2e since 2018.
+ - Fix handling of the "use_bibtex" setting.
* docutils/writers/latex2e/titlepage.tex
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2022-12-19 20:42:55 UTC (rev 9311)
+++ trunk/docutils/docs/user/config.txt 2022-12-19 20:43:08 UTC (rev 9312)
@@ -100,8 +100,9 @@
List values can be comma- or colon-delimited.
-strip_classes_, strip_elements_with_classes_, stylesheet, and
-stylesheet_path use the comma as delimiter,
+strip_classes_, strip_elements_with_classes_, smartquotes_locales_,
+stylesheet, stylesheet_dirs, stylesheet_path, legacy_class_functions_,
+and use_bibtex_ use the comma as delimiter,
whitespace around list values is stripped. ::
strip-classes: ham,eggs,
@@ -1849,14 +1850,17 @@
Default: writer dependent (see `[latex2e writer]`_, `[xetex writer]`_).
Option: ``--template``.
-
use_bibtex
~~~~~~~~~~
-Specify style and database for the experimental `BibTeX` support, for
-example::
- --use-bibtex=mystyle,mydb1,mydb2
+Provisional, name, values, and behaviour may change in future versions
+or the option may be removed.
+A comma-separated list of style and database(s) for the experimental
+`BibTeX` support, for example::
+
+ --use-bibtex=unsrt,mydb1,mydb2
+
Default: "" (don't use BibTeX). Option ``--use-bibtex``.
use_latex_abstract
Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py 2022-12-19 20:42:55 UTC (rev 9311)
+++ trunk/docutils/docutils/transforms/references.py 2022-12-19 20:43:08 UTC (rev 9312)
@@ -893,6 +893,11 @@
if resolver_function(node):
break
else:
+ if (getattr(self.document.settings, 'use_bibtex', False)
+ and isinstance(node, nodes.citation_reference)):
+ # targets added from BibTeX database by LaTeX
+ node.resolved = True
+ return
if refname in self.document.nameids:
msg = self.document.reporter.error(
'Duplicate target name, cannot be used as a unique '
@@ -899,7 +904,7 @@
'reference: "%s".' % (node['refname']), base_node=node)
else:
msg = self.document.reporter.error(
- 'Unknown target name: "%s".' % (node['refname']),
+ f'Unknown target name: "{node["refname"]}".',
base_node=node)
msgid = self.document.set_id(msg)
prb = nodes.problematic(
@@ -914,6 +919,6 @@
del node['refname']
node['refid'] = id
self.document.ids[id].note_referenced_by(id=id)
- node.resolved = 1
+ node.resolved = True
visit_footnote_reference = visit_citation_reference = visit_reference
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2022-12-19 20:42:55 UTC (rev 9311)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2022-12-19 20:43:08 UTC (rev 9312)
@@ -199,10 +199,12 @@
'number or the page number.',
['--reference-label'],
{'default': ''}),
- ('Specify style and database for bibtex, for example '
- '"--use-bibtex=mystyle,mydb1,mydb2".',
+ ('Specify style and database(s) for bibtex, for example '
+ '"--use-bibtex=unsrt,mydb1,mydb2". Provisional!',
['--use-bibtex'],
- {'default': ''}),
+ {'default': '',
+ 'metavar': '<style,bibfile[,bibfile,...]>',
+ 'validator': frontend.validate_comma_separated_list}),
('Use legacy functions with class value list for '
'\\DUtitle and \\DUadmonition.',
['--legacy-class-functions'],
@@ -1162,7 +1164,7 @@
# ~~~~~~~~
self.settings = settings = document.settings
# warn of deprecated settings and changing defaults:
- if settings.use_latex_citations is None:
+ if settings.use_latex_citations is None and not settings.use_bibtex:
settings.use_latex_citations = False
warnings.warn('The default for the setting "use_latex_citations" '
'will change to "True" in Docutils 1.0.',
@@ -1202,11 +1204,9 @@
elif settings.use_verbatim_when_possible:
self.literal_block_env = 'verbatim'
- if self.settings.use_bibtex:
- self.bibtex = self.settings.use_bibtex.split(',', 1)
- # TODO avoid errors on not declared citations.
- else:
- self.bibtex = None
+ if settings.use_bibtex:
+ self.use_latex_citations = True
+ self.bibtex = settings.use_bibtex
# language module for Docutils-generated text
# (labels, bibliographic_fields, and author_separators)
self.language_module = languages.get_language(settings.language_code,
@@ -1213,7 +1213,7 @@
document.reporter)
self.babel = babel_class(settings.language_code, document.reporter)
self.author_separator = self.language_module.author_separators[0]
- d_options = [self.settings.documentoptions]
+ d_options = [settings.documentoptions]
if self.babel.language not in ('english', ''):
d_options.append(self.babel.language)
self.documentoptions = ','.join(filter(None, d_options))
@@ -1220,11 +1220,11 @@
self.d_class = DocumentClass(settings.documentclass,
settings.use_part_section)
# graphic package options:
- if self.settings.graphicx_option == '':
+ if settings.graphicx_option == '':
self.graphicx_package = r'\usepackage{graphicx}'
else:
self.graphicx_package = (r'\usepackage[%s]{graphicx}' %
- self.settings.graphicx_option)
+ settings.graphicx_option)
# footnotes: TODO: implement LaTeX footnotes
self.docutils_footnotes = settings.docutils_footnotes
@@ -1234,7 +1234,7 @@
# Document parts
self.head_prefix = [r'\documentclass[%s]{%s}' %
(self.documentoptions,
- self.settings.documentclass)]
+ settings.documentclass)]
self.requirements = SortableDict() # made a list in depart_document()
self.requirements['__static'] = r'\usepackage{ifthen}'
self.latex_preamble = [settings.latex_preamble]
@@ -1329,7 +1329,7 @@
if self.fallback_stylesheet:
stylesheet_list = [sheet for sheet in stylesheet_list
if sheet != 'docutils']
- if self.settings.legacy_class_functions:
+ if settings.legacy_class_functions:
# docutils.sty is incompatible with legacy functions
self.fallback_stylesheet = False
else:
@@ -1806,6 +1806,8 @@
self.out.append('\\end{figure}\n')
def visit_citation_reference(self, node):
+ if self.bibtex:
+ self._bibitems.append([node.astext()])
if self.use_latex_citations:
if not self.inside_citation_reference_label:
self.out.append(r'\cite{')
@@ -2037,24 +2039,23 @@
# * bibliography
# TODO insertion point of bibliography should be configurable.
- if self.use_latex_citations and len(self._bibitems) > 0:
- if not self.bibtex:
- widest_label = ''
- for bi in self._bibitems:
- if len(widest_label) < len(bi[0]):
- widest_label = bi[0]
- self.out.append('\n\\begin{thebibliography}{%s}\n' %
- widest_label)
- for bi in self._bibitems:
- # cite_key: underscores must not be escaped
- cite_key = bi[0].replace(r'\_', '_')
- self.out.append('\\bibitem[%s]{%s}{%s}\n' %
- (bi[0], cite_key, bi[1]))
- self.out.append('\\end{thebibliography}\n')
- else:
- self.out.append('\n\\bibliographystyle{%s}\n' %
- self.bibtex[0])
- self.out.append('\\bibliography{%s}\n' % self.bibtex[1])
+ if self.bibtex and self._bibitems:
+ self.out.append('\n\\bibliographystyle{%s}\n' % self.bibtex[0])
+ self.out.append('\\bibliography{%s}\n' % ','.join(self.bibtex[1:]))
+ elif self.use_latex_citations and self._bibitems:
+ # TODO: insert citations at point of definition.
+ widest_label = ''
+ for bibitem in self._bibitems:
+ if len(widest_label) < len(bibitem[0]):
+ widest_label = bibitem[0]
+ self.out.append('\n\\begin{thebibliography}{%s}\n' %
+ widest_label)
+ for bibitem in self._bibitems:
+ # cite_key: underscores must not be escaped
+ cite_key = bibitem[0].replace(r'\_', '_')
+ self.out.append('\\bibitem[%s]{%s}{%s}\n' %
+ (bibitem[0], cite_key, bibitem[1]))
+ self.out.append('\\end{thebibliography}\n')
# * make sure to generate a toc file if needed for local contents:
if 'minitoc' in self.requirements and not self.has_latex_toc:
self.out.append('\n\\faketableofcontents % for local ToCs\n')
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-01-10 13:13:19
|
Revision: 9314
http://sourceforge.net/p/docutils/code/9314
Author: milde
Date: 2023-01-10 13:13:17 +0000 (Tue, 10 Jan 2023)
Log Message:
-----------
`locale.getdefaultlocale()` is deprecated in Python 0.11
Let `smartquotes.py` to use `locale.getlocale` instead.
(Only used if this module is called as standalone application.)
Suppress warning in `docutils.io`:
* Don't change current behaviour without advance warning.
* The deprecated function is called inside a try-block with catchall,
so this will not lead to errors once it is removed
(if we were to keep the code until then).
Fixes [bugs:#464].
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/docutils/io.py
trunk/docutils/docutils/utils/smartquotes.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2023-01-10 08:58:28 UTC (rev 9313)
+++ trunk/docutils/HISTORY.txt 2023-01-10 13:13:17 UTC (rev 9314)
@@ -158,6 +158,7 @@
- Use "utf-8-sig" instead of Python's default encoding if the
`input_encoding`_ setting is None.
- Fix error when reading of UTF-16 encoded source without trailing newline.
+ - Suppress deprecation warning (fixes bug #464).
* docutils/parsers/__init__.py
Modified: trunk/docutils/docutils/io.py
===================================================================
--- trunk/docutils/docutils/io.py 2023-01-10 08:58:28 UTC (rev 9313)
+++ trunk/docutils/docutils/io.py 2023-01-10 13:13:17 UTC (rev 9314)
@@ -27,8 +27,11 @@
# before importing this module
try:
# Return locale encoding also in UTF-8 mode
- _locale_encoding = locale.getlocale()[1] or locale.getdefaultlocale()[1]
- _locale_encoding = _locale_encoding.lower()
+ with warnings.catch_warnings():
+ warnings.simplefilter("ignore")
+ _locale_encoding = (locale.getlocale()[1]
+ or locale.getdefaultlocale()[1])
+ _locale_encoding = _locale_encoding.lower()
except ValueError as error: # OS X may set UTF-8 without language code
# See https://bugs.python.org/issue18378 fixed in 3.8
# and https://sourceforge.net/p/docutils/bugs/298/.
Modified: trunk/docutils/docutils/utils/smartquotes.py
===================================================================
--- trunk/docutils/docutils/utils/smartquotes.py 2023-01-10 08:58:28 UTC (rev 9313)
+++ trunk/docutils/docutils/utils/smartquotes.py 2023-01-10 13:13:17 UTC (rev 9314)
@@ -897,7 +897,7 @@
import locale
try:
locale.setlocale(locale.LC_ALL, '') # set to user defaults
- defaultlanguage = locale.getdefaultlocale()[0]
+ defaultlanguage = locale.getlocale()[0]
except: # noqa catchall
defaultlanguage = 'en'
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-01-16 09:19:11
|
Revision: 9316
http://sourceforge.net/p/docutils/code/9316
Author: milde
Date: 2023-01-16 09:19:08 +0000 (Mon, 16 Jan 2023)
Log Message:
-----------
Always use POSIX path in macros loading stylesheets.
Thanks to Alan G. Isaac for reporting the bug and proposing a patch.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docutils/writers/latex2e/__init__.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2023-01-15 19:27:55 UTC (rev 9315)
+++ trunk/docutils/HISTORY.txt 2023-01-16 09:19:08 UTC (rev 9316)
@@ -56,7 +56,7 @@
- New utility function `xml_declaration()`.
- `DependencyList.add()` accepts `pathlib.Path` instances.
- `find_file_in_dirs()` now returns a POSIX path also on Windows;
- `get_stylesheet_list()` no longer converts "\" to "/".
+ `get_stylesheet_list()` no longer converts ``\`` to ``/``.
* docutils/utils/math/latex2mathml.py
@@ -86,6 +86,7 @@
- Do not insert ``\usepackage[utf8]{inputenc}`` into UTF-8 encoded
LaTeX sources. UTF-8 is the default encoding for LaTeX2e since 2018.
- Fix handling of the "use_bibtex" setting.
+ - Use POSIX paths in stylesheet loading macros [report Alan G. Isaac].
* docutils/writers/latex2e/titlepage.tex
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2023-01-15 19:27:55 UTC (rev 9315)
+++ trunk/docutils/docs/user/config.txt 2023-01-16 09:19:08 UTC (rev 9316)
@@ -1760,6 +1760,8 @@
~~~~~~~~~~
A comma-separated list_ of style files.
+Used without path adaption (cf. `stylesheet_path [latex writers]`_).
+Under Windows, path separators are normalized to forward slashes (``/``).
See also `stylesheet [html writers]`_.
Overrides also stylesheet_path__. [#override]_
@@ -1811,7 +1813,7 @@
the output file.
See also `stylesheet_path [html writers]`_.
-The stylesheet__ option is preferred for files in the `TeX input path`_.
+For files in the `TeX input path`_, the stylesheet__ option is recommended.
Also overrides stylesheet__. [#override]_
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2023-01-15 19:27:55 UTC (rev 9315)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2023-01-16 09:19:08 UTC (rev 9316)
@@ -256,8 +256,8 @@
writers.Writer.__init__(self)
self.translator_class = LaTeXTranslator
- # Override parent method to add latex-specific transforms
def get_transforms(self):
+ # Override parent method to add latex-specific transforms
return super().get_transforms() + [
# Convert specific admonitions to generic one
writer_aux.Admonitions,
@@ -1327,8 +1327,7 @@
stylesheet_list = utils.get_stylesheet_list(settings)
self.fallback_stylesheet = 'docutils' in stylesheet_list
if self.fallback_stylesheet:
- stylesheet_list = [sheet for sheet in stylesheet_list
- if sheet != 'docutils']
+ stylesheet_list.remove('docutils')
if settings.legacy_class_functions:
# docutils.sty is incompatible with legacy functions
self.fallback_stylesheet = False
@@ -1403,12 +1402,10 @@
self.document.reporter.error(msg)
return '% ' + msg.replace('\n', '\n% ')
else:
- self.settings.record_dependencies.add(path)
+ self.settings.record_dependencies.add(path.as_posix())
if is_package:
# allow '@' in macro names:
- content = (r'\makeatletter'
- f'\n{content}\n'
- r'\makeatother')
+ content = (f'\\makeatletter\n{content}\n\\makeatother')
return (f'% embedded stylesheet: {path.as_posix()}\n'
f'{content}')
# Link to style file:
@@ -1419,8 +1416,8 @@
cmd = r'\input{%s}'
if self.settings.stylesheet_path:
# adapt path relative to output (cf. config.html#stylesheet-path)
- path = utils.relative_path(self.settings._destination, path)
- return cmd % path
+ return cmd % utils.relative_path(self.settings._destination, path)
+ return cmd % path.as_posix()
def to_latex_encoding(self, docutils_encoding):
"""Translate docutils encoding name into LaTeX's.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-01-17 15:40:47
|
Revision: 9322
http://sourceforge.net/p/docutils/code/9322
Author: milde
Date: 2023-01-17 15:40:43 +0000 (Tue, 17 Jan 2023)
Log Message:
-----------
More user-friendly DocInfo transform.
More detailled feedback when extracting data from a bibliographic field fails.
In bibliographic fields expecting a single paragraph (e.g. "author"),
restore enumerated lists originating in ambiguous markup like
"A. Einstein" (name with initial): in the given context, an we know that this
should not be an enumeration, so fixing is better than throwing an error.
Fix some cases of "ersatz" Boolean values from pre Python 2.3 times.
Modified Paths:
--------------
trunk/docutils/docs/ref/rst/restructuredtext.txt
trunk/docutils/docutils/transforms/frontmatter.py
trunk/docutils/test/test_transforms/test_docinfo.py
Modified: trunk/docutils/docs/ref/rst/restructuredtext.txt
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.txt 2023-01-17 15:40:27 UTC (rev 9321)
+++ trunk/docutils/docs/ref/rst/restructuredtext.txt 2023-01-17 15:40:43 UTC (rev 9322)
@@ -764,12 +764,19 @@
A. Einstein was a really smart dude.
-If a single-line paragraph begins with text identical to an enumerator
-("A.", "1.", "(b)", "I)", etc.), the first character will have to be
-escaped in order to have the line parsed as an ordinary paragraph::
+.. Caution::
+ If a single-line paragraph begins with text identical to an enumerator
+ ("A.", "1.", "(b)", "I)", etc.), the first character will have to be
+ escaped in order to have the line parsed as an ordinary paragraph::
+
+ \A. Einstein was a really smart dude.
+
+ Alternatively, you can escape the delimiter ::
+
+ A\. Einstein was a really smart dude.
+
+ or use a literal NO-BREAK SPACE after the initial.
- \A. Einstein was a really smart dude.
-
Examples of nested enumerated lists::
1. Item 1 initial text.
Modified: trunk/docutils/docutils/transforms/frontmatter.py
===================================================================
--- trunk/docutils/docutils/transforms/frontmatter.py 2023-01-17 15:40:27 UTC (rev 9321)
+++ trunk/docutils/docutils/transforms/frontmatter.py 2023-01-17 15:40:43 UTC (rev 9322)
@@ -23,7 +23,7 @@
import re
-from docutils import nodes, utils
+from docutils import nodes, parsers, utils
from docutils.transforms import TransformError, Transform
@@ -451,24 +451,42 @@
def check_empty_biblio_field(self, field, name):
if len(field[-1]) < 1:
field[-1] += self.document.reporter.warning(
- 'Cannot extract empty bibliographic field "%s".' % name,
+ f'Cannot extract empty bibliographic field "{name}".',
base_node=field)
- return None
- return 1
+ return False
+ return True
def check_compound_biblio_field(self, field, name):
- if len(field[-1]) > 1:
- field[-1] += self.document.reporter.warning(
- 'Cannot extract compound bibliographic field "%s".' % name,
- base_node=field)
- return None
- if not isinstance(field[-1][0], nodes.paragraph):
- field[-1] += self.document.reporter.warning(
- 'Cannot extract bibliographic field "%s" containing '
- 'anything other than a single paragraph.' % name,
- base_node=field)
- return None
- return 1
+ # Check that the `field` body contains a single paragraph
+ # (i.e. it must *not* be a compound element).
+ f_body = field[-1]
+ if len(f_body) == 1 and isinstance(f_body[0], nodes.paragraph):
+ return True
+ # Restore single author name with initial (E. Xampl) parsed as
+ # enumerated list
+ # https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists
+ if (isinstance(f_body[0], nodes.enumerated_list)
+ and '\n' not in f_body.rawsource):
+ # parse into a dummy document and use created nodes
+ _document = utils.new_document('*DocInfo transform*',
+ field.document.settings)
+ parser = parsers.rst.Parser()
+ parser.parse('\\'+f_body.rawsource, _document)
+ if (len(_document.children) == 1
+ and isinstance(_document.children[0], nodes.paragraph)):
+ f_body.children = _document.children
+ return True
+ # Check failed, add a warning
+ content = [f'<{e.tagname}>' for e in f_body.children]
+ if len(content) > 1:
+ content = '[' + ', '.join(content) + ']'
+ else:
+ content = 'a ' + content[0]
+ f_body += self.document.reporter.warning(
+ f'Bibliographic field "{name}"\nmust contain '
+ f'a single <paragraph>, not {content}.',
+ base_node=field)
+ return False
rcs_keyword_substitutions = [
(re.compile(r'\$' r'Date: (\d\d\d\d)[-/](\d\d)[-/](\d\d)[ T][\d:]+'
Modified: trunk/docutils/test/test_transforms/test_docinfo.py
===================================================================
--- trunk/docutils/test/test_transforms/test_docinfo.py 2023-01-17 15:40:27 UTC (rev 9321)
+++ trunk/docutils/test/test_transforms/test_docinfo.py 2023-01-17 15:40:43 UTC (rev 9322)
@@ -74,7 +74,7 @@
It is automatically moved to the end of the other bibliographic elements.
-:Author: Me
+:Author: E. *Xample*
:Version: 1
:Date: 2001-08-11
:Parameter i: integer
@@ -83,7 +83,9 @@
<document source="test data">
<docinfo>
<author>
- Me
+ E. \n\
+ <emphasis>
+ Xample
<version>
1
<date>
@@ -178,7 +180,8 @@
must be a paragraph
<system_message level="2" line="1" source="test data" type="WARNING">
<paragraph>
- Cannot extract bibliographic field "Author" containing anything other than a single paragraph.
+ Bibliographic field "Author"
+ must contain a single <paragraph>, not a <bullet_list>.
<status>
a \n\
<emphasis>
@@ -194,7 +197,8 @@
paragraph.
<system_message level="2" line="3" source="test data" type="WARNING">
<paragraph>
- Cannot extract compound bibliographic field "Date".
+ Bibliographic field "Date"
+ must contain a single <paragraph>, not [<paragraph>, <paragraph>].
<field classes="version">
<field_name>
Version
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-01-17 17:20:14
|
Revision: 9323
http://sourceforge.net/p/docutils/code/9323
Author: milde
Date: 2023-01-17 17:20:12 +0000 (Tue, 17 Jan 2023)
Log Message:
-----------
Fix test case under Windows, add HISTORY entry for last commit.
Thanks to Alan Isaac for test and report.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/test/test_utils.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2023-01-17 15:40:43 UTC (rev 9322)
+++ trunk/docutils/HISTORY.txt 2023-01-17 17:20:12 UTC (rev 9323)
@@ -45,6 +45,14 @@
- `Transformer.populate_from_components()` now silently ignores
components that are not instances of `docutils.TransformSpec`.
+* docutils/transforms/frontmatter.py
+
+ - `DocInfo` now accepts author names with initial like "A. Einstein"
+ (that are `parsed as enumerated list`__) in "author" fields
+ instead of rising an error.
+
+ __ docs/ref/rst/restructuredtext.html#enumerated-lists
+
* docutils/transforms/references.py
- Ignore `citation_reference` nodes if the "use_bibex" setting is
Modified: trunk/docutils/test/test_utils.py
===================================================================
--- trunk/docutils/test/test_utils.py 2023-01-17 15:40:43 UTC (rev 9322)
+++ trunk/docutils/test/test_utils.py 2023-01-17 17:20:12 UTC (rev 9323)
@@ -351,15 +351,16 @@
dirs = (os.path.join(TEST_ROOT, 'nonex'),
TEST_ROOT,
os.path.join(TEST_ROOT, '..'))
- found = utils.find_file_in_dirs('HISTORY.txt', dirs)
- self.assertEqual(found, (TEST_ROOT / '..' / 'HISTORY.txt').as_posix())
- # normalize
- found = os.path.relpath(found, TEST_ROOT).replace('\\', '/')
- self.assertTrue(found.startswith('..'),
+ result = utils.find_file_in_dirs('alltests.py', dirs)
+ expected = os.path.join(TEST_ROOT, 'alltests.py').replace('\\', '/')
+ self.assertEqual(result, expected)
+ result = utils.find_file_in_dirs('HISTORY.txt', dirs)
+ expected = (TEST_ROOT / '..' / 'HISTORY.txt').as_posix()
+ self.assertEqual(result, expected)
+ # normalize for second check
+ self.assertTrue(os.path.relpath(result, TEST_ROOT).startswith('..'),
'HISTORY.txt not found in "..".')
# Return `path` if the file exists in the cwd or if there is no match
- self.assertEqual(utils.find_file_in_dirs('alltests.py', dirs),
- os.path.join(TEST_ROOT, 'alltests.py'))
self.assertEqual(utils.find_file_in_dirs('gibts/nicht.txt', dirs),
'gibts/nicht.txt')
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-01-21 13:13:12
|
Revision: 9324
http://sourceforge.net/p/docutils/code/9324
Author: milde
Date: 2023-01-21 13:13:11 +0000 (Sat, 21 Jan 2023)
Log Message:
-----------
LaTeX writer: outsourcing of some code from `depart_document()`.
Move parts of the spaghetti code in `LaTeXTranslator.depart_document()
to new auxiliary methods `LaTeXTranslator.make_title()` and
`LaTeXTranslator.append_bibliography()`.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/docutils/writers/latex2e/__init__.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2023-01-17 17:20:12 UTC (rev 9323)
+++ trunk/docutils/HISTORY.txt 2023-01-21 13:13:11 UTC (rev 9324)
@@ -94,7 +94,9 @@
- Do not insert ``\usepackage[utf8]{inputenc}`` into UTF-8 encoded
LaTeX sources. UTF-8 is the default encoding for LaTeX2e since 2018.
- Fix handling of the "use_bibtex" setting.
- - Use POSIX paths in stylesheet loading macros [report Alan G. Isaac].
+ - Outsource parts of `depart_document()` to new auxiliary methods
+ `make_title()` and `append_bibliography()`.
+ - Ensure POSIX paths in stylesheet loading macros.
* docutils/writers/latex2e/titlepage.tex
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2023-01-17 17:20:12 UTC (rev 9323)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2023-01-21 13:13:11 UTC (rev 9324)
@@ -1994,7 +1994,7 @@
protect=protect)
def depart_document(self, node):
- # Complete header with information gained from walkabout
+ # Complete "parts" with information gained from walkabout
# * language setup
if (self.babel.otherlanguages
or self.babel.language not in ('', 'english')):
@@ -2010,36 +2010,54 @@
self.pdfinfo.append(' pdfauthor={%s}' % authors)
if self.pdfinfo:
self.pdfsetup += [r'\hypersetup{'] + self.pdfinfo + ['}']
- # Complete body
- # * document title (with "use_latex_docinfo" also
- # 'author', 'organization', 'contact', 'address' and 'date')
- if self.title or (
- self.use_latex_docinfo and (self.author_stack or self.date)):
- # \title (empty \title prevents error with \maketitle)
- title = [''.join(self.title)]
- if self.title:
- title += self.title_labels
- if self.subtitle:
- title += [r'\\',
+ # * title (including author(s) and date if using "latex_docinfo")
+ if self.title or (self.use_latex_docinfo
+ and (self.author_stack or self.date)):
+ self.make_title() # see below
+ # * bibliography
+ if self._bibitems:
+ self.append_bibliogaphy() # see below
+ # * make sure to generate a toc file if needed for local contents:
+ if 'minitoc' in self.requirements and not self.has_latex_toc:
+ self.out.append('\n\\faketableofcontents % for local ToCs\n')
+
+ def make_title(self):
+ # Auxiliary function called by `self.depart_document()`.
+ #
+ # Append ``\title``, ``\author``, and ``\date`` to "titledata".
+ # (We need all three, even if empty, to prevent errors
+ # and/or automatic display of the current date by \maketitle.)
+ # Append ``\maketitle`` to "body_pre_docinfo" parts.
+ #
+ # \title
+ title_arg = [''.join(self.title)] # ensure len == 1
+ if self.title:
+ title_arg += self.title_labels
+ if self.subtitle:
+ title_arg += [r'\\',
r'\DUdocumentsubtitle{%s}' % ''.join(self.subtitle),
] + self.subtitle_labels
- self.titledata.append(r'\title{%s}' % '%\n '.join(title))
- # \author (empty \author prevents warning with \maketitle)
- authors = ['\\\\\n'.join(author_entry)
- for author_entry in self.author_stack]
- self.titledata.append(r'\author{%s}' %
- ' \\and\n'.join(authors))
- # \date (empty \date prevents defaulting to \today)
- self.titledata.append(r'\date{%s}' % ', '.join(self.date))
- # \maketitle in the body formats title with LaTeX
- self.body_pre_docinfo.append('\\maketitle\n')
+ self.titledata.append(r'\title{%s}' % '%\n '.join(title_arg))
+ # \author
+ author_arg = ['\\\\\n'.join(author_entry)
+ for author_entry in self.author_stack]
+ self.titledata.append(r'\author{%s}' %
+ ' \\and\n'.join(author_arg))
+ # \date
+ self.titledata.append(r'\date{%s}' % ', '.join(self.date))
+ # \maketitle
+ # Must be in the document body. We add it to `body_pre_docinfo`
+ # to allow templates to put `titledata` into the document preamble.
+ self.body_pre_docinfo.append('\\maketitle\n')
- # * bibliography
- # TODO insertion point of bibliography should be configurable.
- if self.bibtex and self._bibitems:
+ def append_bibliogaphy(self):
+ # Add bibliography at end of document.
+ # TODO insertion point should be configurable.
+ # Auxiliary function called by `depart_document`.
+ if self.bibtex:
self.out.append('\n\\bibliographystyle{%s}\n' % self.bibtex[0])
self.out.append('\\bibliography{%s}\n' % ','.join(self.bibtex[1:]))
- elif self.use_latex_citations and self._bibitems:
+ elif self.use_latex_citations:
# TODO: insert citations at point of definition.
widest_label = ''
for bibitem in self._bibitems:
@@ -2053,9 +2071,6 @@
self.out.append('\\bibitem[%s]{%s}{%s}\n' %
(bibitem[0], cite_key, bibitem[1]))
self.out.append('\\end{thebibliography}\n')
- # * make sure to generate a toc file if needed for local contents:
- if 'minitoc' in self.requirements and not self.has_latex_toc:
- self.out.append('\n\\faketableofcontents % for local ToCs\n')
def visit_emphasis(self, node):
self.out.append('\\emph{')
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-02-06 21:04:04
|
Revision: 9325
http://sourceforge.net/p/docutils/code/9325
Author: milde
Date: 2023-02-06 21:04:00 +0000 (Mon, 06 Feb 2023)
Log Message:
-----------
New functions for use as `rst2*` "console_scripts entry points".
The new functions allow the installation of `rst2*` command line scripts
via standard `entry points`__ instead of the current "scripts" list in
``setup.py`` after a transition period (cf. [feature-requests:#88]).
+ Works also for Windows.
+ Allows shorter command names (drop the extension), already in use
in Debian and Ubuntu.
__ https://packaging.python.org/en/latest/specifications/entry-points/
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/user/tools.txt
trunk/docutils/docutils/core.py
trunk/docutils/test/test_CLI.py
Added Paths:
-----------
trunk/docutils/test/data/help/rst2html.txt
trunk/docutils/test/data/help/rst2latex.txt
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2023-01-21 13:13:11 UTC (rev 9324)
+++ trunk/docutils/HISTORY.txt 2023-02-06 21:04:00 UTC (rev 9325)
@@ -24,6 +24,7 @@
- Added new `publish_bytes()` function to explicitly return
output as binary data in a `bytes` object.
+ - New functions `rst2…()` for use as "console_scripts" `entry point`_.
* docutils/languages/
docutils/parsers/rst/languages/
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2023-01-21 13:13:11 UTC (rev 9324)
+++ trunk/docutils/RELEASE-NOTES.txt 2023-02-06 21:04:00 UTC (rev 9325)
@@ -22,11 +22,13 @@
* Usage:
- - The ``rst2*.py`` `front end tools`_ will be renamed to ``rst2*``
- (dropping the ``.py`` extension). [#]_
- You may use ``docutils`` [#]_ as a future-proof command name,
- for example:
+ - Docutils 0.21 will provide ``rst2*`` `"console_scripts" entry
+ points`_ (without the ``.py`` extension) instead of installing the
+ ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_
+ You may use the `generic command line front end tool`_ as a
+ future-proof command, for example:
+
.. code:: diff
- rst2latex.py --use-latex-abstract FAQ.txt > FAQ.tex
@@ -37,18 +39,21 @@
available via ``python -m docutils.writers.odf_odt.prepstyles``.
The ``rstpep2html.py`` script will be retired.
- Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview. [#]_
+ Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview
+ (the final rendering is done by a Sphinx-based build system,
+ cf. :PEP:`676`).
+
.. [#] Some Linux distributions already use the short names.
- .. [#] The `generic command line front end tool`_.
- .. [#] The final rendering is done by a Sphinx-based build system
- (see :PEP:`676`).
+ .. _"console_scripts" entry points:
+ https://packaging.python.org/en/latest/specifications/entry-points/
- - The `default HTML writer`__ will change in Docutils 2.0.
+ - The `default HTML writer`__ will change in Docutils 2.0:
- * The rst2html_ front end and ``get_writer_by_name('html')`` select
- "html4css1" now and will select "html5" in Docutils 2.0 and later.
+ The rst2html_ front end and ``get_writer_by_name('html')`` select
+ "html4css1" now and will select "html5" in Docutils 2.0 and later.
+
* Use rst2html4_, ``docutils --writer=html4``, or
``get_writer_by_name('html4')`` if you depend on stability of the
generated HTML code, e.g. because you use a custom style sheet or
Modified: trunk/docutils/docs/user/tools.txt
===================================================================
--- trunk/docutils/docs/user/tools.txt 2023-01-21 13:13:11 UTC (rev 9324)
+++ trunk/docutils/docs/user/tools.txt 2023-02-06 21:04:00 UTC (rev 9325)
@@ -13,11 +13,9 @@
.. contents::
.. note::
- Docutils front-end tool support is currently `under discussion`__.
- Tool names, install details and the set of auto-installed tools
- will `change in future Docutils versions`__.
+ Docutils front-end tool names, install details and the set of
+ auto-installed tools will `change in Docutils 0.21`__.
- __ https://sourceforge.net/p/docutils/feature-requests/88/
__ ../../RELEASE-NOTES.html#future-changes
--------------
@@ -73,11 +71,12 @@
Generic Command Line Front End
==============================
-:Readers: Standalone (default), PEP
-:Parsers: reStructuredText (default), Markdown (requires 3rd party packages)
-:Writers: html_, html4css1_, html5_ (default), latex2e_, manpage_,
- odt_, pep_html_, pseudo-xml_, s5_html_, xelatex_, xml_,
-:Config_: `[docutils application]`_
+:CLI name: ``docutils``
+:Readers: Standalone (default), PEP
+:Parsers: reStructuredText (default), Markdown (requires 3rd party packages)
+:Writers: html_, html4css1_, html5_ (default), latex2e_, manpage_,
+ odt_, pep_html_, pseudo-xml_, s5_html_, xelatex_, xml_,
+:Config_: `[docutils application]`_
Since Docutils 0.19, you can start the generic front end like::
Modified: trunk/docutils/docutils/core.py
===================================================================
--- trunk/docutils/docutils/core.py 2023-01-21 13:13:11 UTC (rev 9324)
+++ trunk/docutils/docutils/core.py 2023-02-06 21:04:00 UTC (rev 9325)
@@ -15,6 +15,7 @@
__docformat__ = 'reStructuredText'
+import locale
import pprint
import os
import sys
@@ -227,7 +228,7 @@
output = self.writer.write(self.document, self.destination)
self.writer.assemble_parts()
except SystemExit as error:
- exit = 1
+ exit = True
exit_status = error.code
except Exception as error:
if not self.settings: # exception too early to report nicely
@@ -757,3 +758,60 @@
publisher.set_destination(destination, destination_path)
output = publisher.publish(enable_exit_status=enable_exit_status)
return output, publisher
+
+
+# "Entry points" with functionality of the "tools/rst2*.py" scripts
+# cf. https://packaging.python.org/en/latest/specifications/entry-points/
+
+def rst2something(writer, documenttype, doc_path=''):
+ # Helper function for the common parts of rst2...
+ # writer: writer name
+ # documenttype: output document type
+ # doc_path: documentation path (relative to the documentation root)
+ description = (
+ f'Generate {documenttype} documents '
+ 'from standalone reStructuredText sources '
+ f'<https://docutils.sourceforge.io/docs/{doc_path}>. '
+ + default_description)
+ locale.setlocale(locale.LC_ALL, '')
+ publish_cmdline(writer_name=writer, description=description)
+
+
+def rst2html():
+ rst2something('html', 'HTML', 'user/html.html#html')
+
+
+def rst2html4():
+ rst2something('html4', 'XHTML 1.1', 'user/html.html#html4css1')
+
+
+def rst2html5():
+ rst2something('html5', 'HTML5', 'user/html.html#html5-polyglot')
+
+
+def rst2latex():
+ rst2something('latex', 'LaTeX', 'user/latex.html')
+
+
+def rst2man():
+ rst2something('manpage', 'Unix manual (troff)', 'user/manpage.html')
+
+
+def rst2odt():
+ rst2something('odt', 'OpenDocument text (ODT)', 'user/odt.html')
+
+
+def rst2pseudoxml():
+ rst2something('pseudoxml', 'pseudo-XML (test)', 'ref/doctree.html')
+
+
+def rst2s5():
+ rst2something('s5', 'S5 HTML slideshow', 'user/slide-shows.html')
+
+
+def rst2xetex():
+ rst2something('xetex', 'LaTeX (XeLaTeX/LuaLaTeX)', 'user/latex.html')
+
+
+def rst2xml():
+ rst2something('xml', 'Docutils-native XML', 'ref/doctree.html')
Added: trunk/docutils/test/data/help/rst2html.txt
===================================================================
--- trunk/docutils/test/data/help/rst2html.txt (rev 0)
+++ trunk/docutils/test/data/help/rst2html.txt 2023-02-06 21:04:00 UTC (rev 9325)
@@ -0,0 +1,211 @@
+Usage
+=====
+ rst2html [options] [<source> [<destination>]]
+
+Generate HTML documents from standalone reStructuredText sources
+<https://docutils.sourceforge.io/docs/user/html.html#html>. Reads from
+<source> (default is stdin) and writes to <destination> (default is stdout).
+See https://docutils.sourceforge.io/docs/user/config.html for a detailed
+settings reference.
+
+Options
+=======
+General Docutils Options
+------------------------
+--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).
+--time, -t Include the time & date (UTC).
+--no-datestamp Do not include a datestamp of any kind.
+--source-link, -s Include a "View document source" link.
+--source-url=<URL> Use <URL> for a source link; implies --source-link.
+--no-source-link Do not include a "View document source" link.
+--toc-entry-backlinks Link from section headers to TOC entries. (default)
+--toc-top-backlinks Link from section headers to the top of the TOC.
+--no-toc-backlinks Disable backlinks to the table of contents.
+--footnote-backlinks Link from footnotes/citations to references. (default)
+--no-footnote-backlinks
+ Disable backlinks from footnotes and citations.
+--section-numbering Enable section numbering by Docutils. (default)
+--no-section-numbering Disable section numbering by Docutils.
+--strip-comments Remove comment elements from the document tree.
+--leave-comments Leave comment elements in the document tree. (default)
+--strip-elements-with-class=<class>
+ Remove all elements with classes="<class>" from the
+ document tree. Warning: potentially dangerous; use
+ with caution. (Multiple-use option.)
+--strip-class=<class> Remove all classes="<class>" attributes from elements
+ in the document tree. Warning: potentially dangerous;
+ use with caution. (Multiple-use option.)
+--report=<level>, -r <level>
+ Report system messages at or higher than <level>:
+ "info" or "1", "warning"/"2" (default), "error"/"3",
+ "severe"/"4", "none"/"5"
+--verbose, -v Report all system messages. (Same as "--report=1".)
+--quiet, -q Report no system messages. (Same as "--report=5".)
+--halt=<level> Halt execution at system messages at or above <level>.
+ Levels as in --report. Default: 4 (severe).
+--strict Halt at the slightest problem. Same as "--halt=info".
+--exit-status=<level> Enable a non-zero exit status for non-halting system
+ messages at or above <level>. Default: 5 (disabled).
+--debug Enable debug-level system messages and diagnostics.
+--no-debug Disable debug output. (default)
+--warnings=<file> Send the output of system messages to <file>.
+--traceback Enable Python tracebacks when Docutils is halted.
+--no-traceback Disable Python tracebacks. (default)
+--input-encoding=<name[:handler]>, -i <name[:handler]>
+ Specify the encoding and optionally the error handler
+ of input text. Default: <auto-detect>:strict.
+--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]>, -o <name[:handler]>
+ Specify the text encoding and optionally the error
+ handler for output. Default: utf-8:strict.
+--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:backslashreplace.
+--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 the language (as BCP 47 language tag).
+ Default: en.
+--record-dependencies=<file>
+ Write output file dependencies to <file>.
+--config=<file> Read configuration settings from <file>, if it exists.
+--version, -V Show this program's version number and exit.
+--help, -h Show this help message and exit.
+
+Generic Parser Options
+----------------------
+--no-file-insertion Disable directives that insert the contents of an
+ external file; replaced with a "warning" system
+ message.
+--file-insertion-enabled
+ Enable directives that insert the contents of an
+ external file. (default)
+--no-raw Disable the "raw" directive; replaced with a "warning"
+ system message.
+--raw-enabled Enable the "raw" directive. (default)
+--line-length-limit=<length>
+ Maximal number of characters in an input line. Default
+ 10 000.
+
+reStructuredText Parser Options
+-------------------------------
+--pep-references Recognize and link to standalone PEP references (like
+ "PEP 258").
+--pep-base-url=<URL> Base URL for PEP references (default
+ "https://peps.python.org/").
+--pep-file-url-template=<URL>
+ Template for PEP file part of URL. (default
+ "pep-%04d")
+--rfc-references Recognize and link to standalone RFC references (like
+ "RFC 822").
+--rfc-base-url=<URL> Base URL for RFC references (default
+ "https://tools.ietf.org/html/").
+--tab-width=<width> Set number of spaces for tab expansion (default 8).
+--trim-footnote-reference-space
+ Remove spaces before footnote references.
+--leave-footnote-reference-space
+ Leave spaces before footnote references.
+--syntax-highlight=<format>
+ Token name set for parsing code with Pygments: one of
+ "long", "short", or "none" (no parsing). Default is
+ "long".
+--smart-quotes=<yes/no/alt>
+ Change straight quotation marks to typographic form:
+ one of "yes", "no", "alt[ernative]" (default "no").
+--smartquotes-locales=<language:quotes[,language:quotes,...]>
+ Characters to use as "smart quotes" for <language>.
+--word-level-inline-markup
+ Inline markup recognized at word boundaries only
+ (adjacent to punctuation or whitespace). Force
+ character-level inline markup recognition with "\ "
+ (backslash + space). Default.
+--character-level-inline-markup
+ Inline markup recognized anywhere, regardless of
+ surrounding characters. Backslash-escapes must be used
+ to avoid unwanted markup recognition. Useful for East
+ Asian languages. Experimental.
+
+Standalone Reader Options
+-------------------------
+--no-doc-title Disable the promotion of a lone top-level section
+ title to document title (and subsequent section title
+ to document subtitle promotion; enabled by default).
+--no-doc-info Disable the bibliographic field list transform
+ (enabled by default).
+--section-subtitles Activate the promotion of lone subsection titles to
+ section subtitles (disabled by default).
+--no-section-subtitles Deactivate the promotion of lone subsection titles.
+
+HTML Writer Options
+-------------------
+--template=<file> Template file. (UTF-8 encoded, default: [...])
+--stylesheet=<URL[,URL,...]>
+ Comma separated list of stylesheet URLs. Overrides
+ previous --stylesheet and --stylesheet-path settings.
+--stylesheet-path=<file[,file,...]>
+ Comma separated list of stylesheet paths. Relative
+ paths are expanded if a matching file is found in the
+ --stylesheet-dirs. With --link-stylesheet, the path is
+ rewritten relative to the output HTML file. (default:
+ "html4css1.css")
+--stylesheet-dirs=<dir[,dir,...]>
+ Comma-separated list of directories where stylesheets
+ are found. Used by --stylesheet-path when expanding
+ relative path arguments. (default: [...])
+--embed-stylesheet Embed the stylesheet(s) in the output HTML file. The
+ stylesheet files must be accessible during processing.
+ (default)
+--link-stylesheet Link to the stylesheet(s) in the output HTML file.
+--initial-header-level=<level>
+ Specify the initial header level. Does not affect
+ document title & subtitle (see --no-doc-title).
+ (default: 1 for "<h1>")
+--footnote-references=<format>
+ Format for footnote references: one of "superscript"
+ or "brackets". (default: "brackets")
+--attribution=<format> Format for block quote attributions: one of "dash"
+ (em-dash prefix), "parentheses"/"parens", or "none".
+ (default: "dash")
+--compact-lists Remove extra vertical whitespace between items of
+ "simple" bullet lists and enumerated lists. (default)
+--no-compact-lists Disable compact simple bullet and enumerated lists.
+--compact-field-lists Remove extra vertical whitespace between items of
+ simple field lists. (default)
+--no-compact-field-lists
+ Disable compact simple field lists.
+--table-style=TABLE_STYLE
+ Added to standard table classes. Defined styles:
+ borderless, booktabs, align-left, align-center, align-
+ right, colwidths-auto, colwidths-grid.
+--math-output=MATH_OUTPUT
+ Math output format (one of "MathML", "HTML",
+ "MathJax", or "LaTeX") and option(s). (default: "HTML
+ math.css")
+--xml-declaration Prepend an XML declaration (default).
+--no-xml-declaration Omit the XML declaration.
+--cloak-email-addresses
+ Obfuscate email addresses to confuse harvesters while
+ still keeping email links usable with standards-
+ compliant browsers.
+
+HTML4 Writer Options
+--------------------
+--field-name-limit=<level>
+ Specify the maximum width (in characters) for one-
+ column field names. Longer field names will span an
+ entire row of the table used to render the field list.
+ Default is 14 characters. Use 0 for "no limit".
+--option-limit=<level> Specify the maximum width (in characters) for options
+ in option lists. Longer options will span an entire
+ row of the table used to render the option list.
+ Default is 14 characters. Use 0 for "no limit".
Property changes on: trunk/docutils/test/data/help/rst2html.txt
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:keywords
## -0,0 +1 ##
+Author Date Id Revision
\ No newline at end of property
Added: trunk/docutils/test/data/help/rst2latex.txt
===================================================================
--- trunk/docutils/test/data/help/rst2latex.txt (rev 0)
+++ trunk/docutils/test/data/help/rst2latex.txt 2023-02-06 21:04:00 UTC (rev 9325)
@@ -0,0 +1,253 @@
+Usage
+=====
+ rst2latex [options] [<source> [<destination>]]
+
+Generate LaTeX documents from standalone reStructuredText sources
+<https://docutils.sourceforge.io/docs/user/latex.html>. Reads from <source>
+(default is stdin) and writes to <destination> (default is stdout). See
+https://docutils.sourceforge.io/docs/user/config.html for a detailed settings
+reference.
+
+Options
+=======
+General Docutils Options
+------------------------
+--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).
+--time, -t Include the time & date (UTC).
+--no-datestamp Do not include a datestamp of any kind.
+--source-link, -s Include a "View document source" link.
+--source-url=<URL> Use <URL> for a source link; implies --source-link.
+--no-source-link Do not include a "View document source" link.
+--toc-entry-backlinks Link from section headers to TOC entries. (default)
+--toc-top-backlinks Link from section headers to the top of the TOC.
+--no-toc-backlinks Disable backlinks to the table of contents.
+--footnote-backlinks Link from footnotes/citations to references. (default)
+--no-footnote-backlinks
+ Disable backlinks from footnotes and citations.
+--section-numbering Enable section numbering by Docutils. (default)
+--no-section-numbering Disable section numbering by Docutils.
+--strip-comments Remove comment elements from the document tree.
+--leave-comments Leave comment elements in the document tree. (default)
+--strip-elements-with-class=<class>
+ Remove all elements with classes="<class>" from the
+ document tree. Warning: potentially dangerous; use
+ with caution. (Multiple-use option.)
+--strip-class=<class> Remove all classes="<class>" attributes from elements
+ in the document tree. Warning: potentially dangerous;
+ use with caution. (Multiple-use option.)
+--report=<level>, -r <level>
+ Report system messages at or higher than <level>:
+ "info" or "1", "warning"/"2" (default), "error"/"3",
+ "severe"/"4", "none"/"5"
+--verbose, -v Report all system messages. (Same as "--report=1".)
+--quiet, -q Report no system messages. (Same as "--report=5".)
+--halt=<level> Halt execution at system messages at or above <level>.
+ Levels as in --report. Default: 4 (severe).
+--strict Halt at the slightest problem. Same as "--halt=info".
+--exit-status=<level> Enable a non-zero exit status for non-halting system
+ messages at or above <level>. Default: 5 (disabled).
+--debug Enable debug-level system messages and diagnostics.
+--no-debug Disable debug output. (default)
+--warnings=<file> Send the output of system messages to <file>.
+--traceback Enable Python tracebacks when Docutils is halted.
+--no-traceback Disable Python tracebacks. (default)
+--input-encoding=<name[:handler]>, -i <name[:handler]>
+ Specify the encoding and optionally the error handler
+ of input text. Default: <auto-detect>:strict.
+--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]>, -o <name[:handler]>
+ Specify the text encoding and optionally the error
+ handler for output. Default: utf-8:strict.
+--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:backslashreplace.
+--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 the language (as BCP 47 language tag).
+ Default: en.
+--record-dependencies=<file>
+ Write output file dependencies to <file>.
+--config=<file> Read configuration settings from <file>, if it exists.
+--version, -V Show this program's version number and exit.
+--help, -h Show this help message and exit.
+
+Generic Parser Options
+----------------------
+--no-file-insertion Disable directives that insert the contents of an
+ external file; replaced with a "warning" system
+ message.
+--file-insertion-enabled
+ Enable directives that insert the contents of an
+ external file. (default)
+--no-raw Disable the "raw" directive; replaced with a "warning"
+ system message.
+--raw-enabled Enable the "raw" directive. (default)
+--line-length-limit=<length>
+ Maximal number of characters in an input line. Default
+ 10 000.
+
+reStructuredText Parser Options
+-------------------------------
+--pep-references Recognize and link to standalone PEP references (like
+ "PEP 258").
+--pep-base-url=<URL> Base URL for PEP references (default
+ "https://peps.python.org/").
+--pep-file-url-template=<URL>
+ Template for PEP file part of URL. (default
+ "pep-%04d")
+--rfc-references Recognize and link to standalone RFC references (like
+ "RFC 822").
+--rfc-base-url=<URL> Base URL for RFC references (default
+ "https://tools.ietf.org/html/").
+--tab-width=<width> Set number of spaces for tab expansion (default 8).
+--trim-footnote-reference-space
+ Remove spaces before footnote references.
+--leave-footnote-reference-space
+ Leave spaces before footnote references.
+--syntax-highlight=<format>
+ Token name set for parsing code with Pygments: one of
+ "long", "short", or "none" (no parsing). Default is
+ "long".
+--smart-quotes=<yes/no/alt>
+ Change straight quotation marks to typographic form:
+ one of "yes", "no", "alt[ernative]" (default "no").
+--smartquotes-locales=<language:quotes[,language:quotes,...]>
+ Characters to use as "smart quotes" for <language>.
+--word-level-inline-markup
+ Inline markup recognized at word boundaries only
+ (adjacent to punctuation or whitespace). Force
+ character-level inline markup recognition with "\ "
+ (backslash + space). Default.
+--character-level-inline-markup
+ Inline markup recognized anywhere, regardless of
+ surrounding characters. Backslash-escapes must be used
+ to avoid unwanted markup recognition. Useful for East
+ Asian languages. Experimental.
+
+Standalone Reader Options
+-------------------------
+--no-doc-title Disable the promotion of a lone top-level section
+ title to document title (and subsequent section title
+ to document subtitle promotion; enabled by default).
+--no-doc-info Disable the bibliographic field list transform
+ (enabled by default).
+--section-subtitles Activate the promotion of lone subsection titles to
+ section subtitles (disabled by default).
+--no-section-subtitles Deactivate the promotion of lone subsection titles.
+
+LaTeX-Specific Options
+----------------------
+--documentclass=DOCUMENTCLASS
+ Specify LaTeX documentclass. Default: "article".
+--documentoptions=DOCUMENTOPTIONS
+ Specify document options. Multiple options can be
+ given, separated by commas. Default: "a4paper".
+--footnote-references=<format>
+ Format for footnote references: one of "superscript"
+ or "brackets". Default: "superscript".
+--use-latex-citations Use \cite command for citations. (future default)
+--figure-citations Use figure floats for citations (might get mixed with
+ real figures). (provisional default)
+--attribution=<format> Format for block quote attributi...
[truncated message content] |
|
From: <mi...@us...> - 2023-02-06 21:34:23
|
Revision: 9326
http://sourceforge.net/p/docutils/code/9326
Author: milde
Date: 2023-02-06 21:34:19 +0000 (Mon, 06 Feb 2023)
Log Message:
-----------
Update documentation on planned changes.
Announce target versions for imminent changes.
Announce raise of required minimal Python version to 3.9.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/user/config.txt
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2023-02-06 21:04:00 UTC (rev 9325)
+++ trunk/docutils/HISTORY.txt 2023-02-06 21:34:19 UTC (rev 9326)
@@ -13,12 +13,13 @@
.. contents::
-Changes Since 0.19
-==================
+Release 0.20b (unpublished)
+===========================
* General
- - Support Python 3.11 (patch #198 by Hugo van Kemenade).
+ - Docutils 0.20 is the last version supporting Python 3.7 and 3.8.
+ - Support Python 3.11 (patch #198 by Hugo van Kemenade).
* docutils/core.py
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2023-02-06 21:04:00 UTC (rev 9325)
+++ trunk/docutils/RELEASE-NOTES.txt 2023-02-06 21:34:19 UTC (rev 9326)
@@ -20,6 +20,8 @@
Future changes
==============
+Drop support for Python 2.7 and 2.8 in Docutils 0.21.
+
* Usage:
- Docutils 0.21 will provide ``rst2*`` `"console_scripts" entry
@@ -67,15 +69,20 @@
- Raise UnicodeError (instead of falling back to the locale encoding)
if decoding the source with the default encoding (UTF-8) fails and
- Python is started in `UTF-8 mode`_.
+ Python is started in `UTF-8 mode`_. (Docutils 0.21)
Raise UnicodeError (instead of falling back to "latin1") if both,
- default and locale encoding, fail.
+ default and locale encoding, fail. (Docutils 0.21)
- Only remove BOM (U+FEFF ZWNBSP at start of data), no other ZWNBSPs.
Only remove BOM with `input_encoding`_ values None, '', 'utf-8-sig',
- 'utf-16', and 'utf-32'.
+ 'utf-16', and 'utf-32'. (Docutils 0.21)
+ - Change the default input encoding from ``None`` (auto-detect) to
+ "utf-8" in Docutils 0.22.
+
+ - Remove the input encoding auto-detection code in Docutils 1.0.
+
* "html5" writer:
- Stop setting the "footnote-reference" class value for footnote
@@ -113,7 +120,8 @@
* Drop support for `old-format configuration files`_ in Docutils 2.0.
-* Remove file ``install.py``. See README.txt__ for alternatives.
+* Remove file ``install.py`` in Docutils 0.21.
+ See README.txt__ for alternatives.
__ README.html#installation
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2023-02-06 21:04:00 UTC (rev 9325)
+++ trunk/docutils/docs/user/config.txt 2023-02-06 21:34:19 UTC (rev 9326)
@@ -100,7 +100,7 @@
List values can be comma- or colon-delimited.
-strip_classes_, strip_elements_with_classes_, smartquotes_locales_,
+strip_classes_, strip_elements_with_classes_, smartquotes_locales_,
stylesheet, stylesheet_dirs, stylesheet_path, legacy_class_functions_,
and use_bibtex_ use the comma as delimiter,
whitespace around list values is stripped. ::
@@ -371,8 +371,10 @@
The text encoding for input (use the empty string to restore the default).
-Default: auto-detect_ (None). Options: ``--input-encoding, -i``.
+Default: auto-detect_ (None). [#]_ Options: ``--input-encoding, -i``.
+.. [#] The default will change to "utf-8" in Docutils 0.22.
+
.. _auto-detect: ../api/publisher.html#encodings
input_encoding_error_handler
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-02-07 14:24:22
|
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.
|
|
From: <mi...@us...> - 2023-02-07 14:24:39
|
Revision: 9328
http://sourceforge.net/p/docutils/code/9328
Author: milde
Date: 2023-02-07 14:24:37 +0000 (Tue, 07 Feb 2023)
Log Message:
-----------
New general setting "output".
This setting obsoletes the positional argument <destination>.
Cf. the announcement of command line pattern changes in the
RELEASE-NOTES.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docutils/core.py
trunk/docutils/docutils/frontend.py
trunk/docutils/test/data/help/docutils.txt
trunk/docutils/test/data/help/rst2html.txt
trunk/docutils/test/data/help/rst2latex.txt
trunk/docutils/test/test_publisher.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2023-02-07 14:24:19 UTC (rev 9327)
+++ trunk/docutils/HISTORY.txt 2023-02-07 14:24:37 UTC (rev 9328)
@@ -27,6 +27,11 @@
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/
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2023-02-07 14:24:19 UTC (rev 9327)
+++ trunk/docutils/docs/user/config.txt 2023-02-07 14:24:37 UTC (rev 9328)
@@ -420,6 +420,21 @@
.. _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
---------------
Modified: trunk/docutils/docutils/core.py
===================================================================
--- trunk/docutils/docutils/core.py 2023-02-07 14:24:19 UTC (rev 9327)
+++ trunk/docutils/docutils/core.py 2023-02-07 14:24:37 UTC (rev 9328)
@@ -192,9 +192,16 @@
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 @@
# 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.
#
-# 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='+')
#
Modified: trunk/docutils/docutils/frontend.py
===================================================================
--- trunk/docutils/docutils/frontend.py 2023-02-07 14:24:19 UTC (rev 9327)
+++ trunk/docutils/docutils/frontend.py 2023-02-07 14:24:37 UTC (rev 9328)
@@ -461,8 +461,11 @@
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}),
Modified: trunk/docutils/test/data/help/docutils.txt
===================================================================
--- trunk/docutils/test/data/help/docutils.txt 2023-02-07 14:24:19 UTC (rev 9327)
+++ trunk/docutils/test/data/help/docutils.txt 2023-02-07 14:24:37 UTC (rev 9328)
@@ -11,7 +11,9 @@
=======
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).
Modified: trunk/docutils/test/data/help/rst2html.txt
===================================================================
--- trunk/docutils/test/data/help/rst2html.txt 2023-02-07 14:24:19 UTC (rev 9327)
+++ trunk/docutils/test/data/help/rst2html.txt 2023-02-07 14:24:37 UTC (rev 9328)
@@ -12,7 +12,9 @@
=======
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).
Modified: trunk/docutils/test/data/help/rst2latex.txt
===================================================================
--- trunk/docutils/test/data/help/rst2latex.txt 2023-02-07 14:24:19 UTC (rev 9327)
+++ trunk/docutils/test/data/help/rst2latex.txt 2023-02-07 14:24:37 UTC (rev 9328)
@@ -12,7 +12,9 @@
=======
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).
Modified: trunk/docutils/test/test_publisher.py
===================================================================
--- trunk/docutils/test/test_publisher.py 2023-02-07 14:24:19 UTC (rev 9327)
+++ trunk/docutils/test/test_publisher.py 2023-02-07 14:24:37 UTC (rev 9328)
@@ -19,7 +19,7 @@
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 @@
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 @@
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 @@
# 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))
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-02-07 14:24:49
|
Revision: 9329
http://sourceforge.net/p/docutils/code/9329
Author: milde
Date: 2023-02-07 14:24:46 +0000 (Tue, 07 Feb 2023)
Log Message:
-----------
Avoid ambiguous module name `io`.
There are standard `io` and `docutils.io`.
Avoid ambiguity by not using ``from docutils import io``.
Modified Paths:
--------------
trunk/docutils/test/test_io.py
trunk/docutils/tools/buildhtml.py
Modified: trunk/docutils/test/test_io.py
===================================================================
--- trunk/docutils/test/test_io.py 2023-02-07 14:24:37 UTC (rev 9328)
+++ trunk/docutils/test/test_io.py 2023-02-07 14:24:46 UTC (rev 9329)
@@ -19,7 +19,7 @@
# so we import the local `docutils` package.
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-from docutils import io
+from docutils import io as du_io
# DATA_ROOT is ./test/data/ from the docutils root
DATA_ROOT = os.path.join(os.path.abspath(os.path.dirname(__file__)), 'data')
@@ -54,27 +54,28 @@
def test_check_encoding_true(self):
"""Return `True` if lookup returns the same codec"""
- self.assertEqual(io.check_encoding(mock_stdout, 'utf-8'), True)
- self.assertEqual(io.check_encoding(mock_stdout, 'utf_8'), True)
- self.assertEqual(io.check_encoding(mock_stdout, 'utf8'), True)
- self.assertEqual(io.check_encoding(mock_stdout, 'UTF-8'), True)
+ self.assertEqual(du_io.check_encoding(mock_stdout, 'utf-8'), True)
+ self.assertEqual(du_io.check_encoding(mock_stdout, 'utf_8'), True)
+ self.assertEqual(du_io.check_encoding(mock_stdout, 'utf8'), True)
+ self.assertEqual(du_io.check_encoding(mock_stdout, 'UTF-8'), True)
def test_check_encoding_false(self):
"""Return `False` if lookup returns different codecs"""
- self.assertEqual(io.check_encoding(mock_stdout, 'ascii'), False)
- self.assertEqual(io.check_encoding(mock_stdout, 'latin-1'), False)
+ self.assertEqual(du_io.check_encoding(mock_stdout, 'ascii'), False)
+ self.assertEqual(du_io.check_encoding(mock_stdout, 'latin-1'), False)
def test_check_encoding_none(self):
"""Cases where the comparison fails."""
# stream.encoding is None:
- self.assertEqual(io.check_encoding(io.FileInput(), 'ascii'), None)
+ self.assertEqual(du_io.check_encoding(du_io.FileInput(), 'ascii'),
+ None)
# stream.encoding does not exist:
- self.assertEqual(io.check_encoding(BBuf, 'ascii'), None)
+ self.assertEqual(du_io.check_encoding(BBuf, 'ascii'), None)
# encoding is None or empty string:
- self.assertEqual(io.check_encoding(mock_stdout, None), None)
- self.assertEqual(io.check_encoding(mock_stdout, ''), None)
+ self.assertEqual(du_io.check_encoding(mock_stdout, None), None)
+ self.assertEqual(du_io.check_encoding(mock_stdout, ''), None)
# encoding is invalid
- self.assertEqual(io.check_encoding(mock_stdout, 'UTF-9'), None)
+ self.assertEqual(du_io.check_encoding(mock_stdout, 'UTF-9'), None)
def test_error_string(self):
us = '\xfc' # bytes(us) fails
@@ -81,11 +82,11 @@
bs = b'\xc3\xbc' # str(bs) returns repr(bs)
self.assertEqual('Exception: spam',
- io.error_string(Exception('spam')))
+ du_io.error_string(Exception('spam')))
self.assertEqual('IndexError: ' + str(bs),
- io.error_string(IndexError(bs)))
+ du_io.error_string(IndexError(bs)))
self.assertEqual('ImportError: %s' % us,
- io.error_string(ImportError(us)))
+ du_io.error_string(ImportError(us)))
class InputTests(unittest.TestCase):
@@ -92,17 +93,17 @@
def test_bom(self):
# Provisional:
- input = io.StringInput(source=b'\xef\xbb\xbf foo \xef\xbb\xbf bar')
+ input = du_io.StringInput(source=b'\xef\xbb\xbf foo \xef\xbb\xbf bar')
# Assert BOM is gone.
# TODO: only remove BOM (ZWNBSP at start of data)
self.assertEqual(input.read(), ' foo bar')
# Unicode input is left unchanged:
- input = io.StringInput(source='\ufeff foo \ufeff bar')
+ input = du_io.StringInput(source='\ufeff foo \ufeff bar')
# Assert ZWNBSPs are still there.
self.assertEqual(input.read(), '\ufeff foo \ufeff bar')
def test_coding_slug(self):
- input = io.StringInput(source=b"""\
+ input = du_io.StringInput(source=b"""\
.. -*- coding: ascii -*-
data
blah
@@ -109,7 +110,7 @@
""")
data = input.read() # noqa: F841
self.assertEqual(input.successful_encoding, 'ascii')
- input = io.StringInput(source=b"""\
+ input = du_io.StringInput(source=b"""\
#! python
# -*- coding: ascii -*-
print("hello world")
@@ -116,7 +117,7 @@
""")
data = input.read() # noqa: F841
self.assertEqual(input.successful_encoding, 'ascii')
- input = io.StringInput(source=b"""\
+ input = du_io.StringInput(source=b"""\
#! python
# extraneous comment; prevents coding slug from being read
# -*- coding: ascii -*-
@@ -127,15 +128,15 @@
def test_bom_detection(self):
source = '\ufeffdata\nblah\n'
expected = 'data\nblah\n'
- input = io.StringInput(source=source.encode('utf-16-be'))
+ input = du_io.StringInput(source=source.encode('utf-16-be'))
self.assertEqual(input.read(), expected)
- input = io.StringInput(source=source.encode('utf-16-le'))
+ input = du_io.StringInput(source=source.encode('utf-16-le'))
self.assertEqual(input.read(), expected)
- input = io.StringInput(source=source.encode('utf-8'))
+ input = du_io.StringInput(source=source.encode('utf-8'))
self.assertEqual(input.read(), expected)
def test_readlines(self):
- input = io.FileInput(
+ input = du_io.FileInput(
source_path=os.path.join(DATA_ROOT, 'include.txt'))
data = input.readlines()
self.assertEqual(data, ['Some include text.\n'])
@@ -144,8 +145,8 @@
# if no encoding is given and decoding with 'utf-8' fails,
# use either the locale encoding (if specified) or 'latin-1':
# Provisional: the second fallback 'latin-1' will be dropped
- probed_encodings = (io._locale_encoding, 'latin-1') # noqa
- input = io.FileInput(
+ probed_encodings = (du_io._locale_encoding, 'latin-1') # noqa
+ input = du_io.FileInput(
source_path=os.path.join(DATA_ROOT, 'latin1.txt'))
data = input.read()
if input.successful_encoding not in probed_encodings:
@@ -157,7 +158,7 @@
def test_decode_unicode(self):
# With the special value "unicode" or "Unicode":
- uniinput = io.Input(encoding='unicode')
+ uniinput = du_io.Input(encoding='unicode')
# keep unicode instances as-is
self.assertEqual(uniinput.decode('ja'), 'ja')
# raise AssertionError if data is not an unicode string
@@ -178,14 +179,14 @@
"""Stub of sys.stdout under Python 3"""
def test_write_unicode(self):
- fo = io.FileOutput(destination=self.udrain, encoding='unicode',
- autoclose=False)
+ fo = du_io.FileOutput(destination=self.udrain, encoding='unicode',
+ autoclose=False)
fo.write(self.udata)
self.assertEqual(self.udrain.getvalue(), self.udata)
def test_write_utf8(self):
- fo = io.FileOutput(destination=self.udrain, encoding='utf-8',
- autoclose=False)
+ fo = du_io.FileOutput(destination=self.udrain, encoding='utf-8',
+ autoclose=False)
fo.write(self.udata)
self.assertEqual(self.udrain.getvalue(), self.udata)
@@ -192,13 +193,13 @@
def test_FileOutput_hande_io_errors_deprection_warning(self):
with self.assertWarnsRegex(DeprecationWarning,
'"handle_io_errors" is ignored'):
- io.FileOutput(handle_io_errors=True)
+ du_io.FileOutput(handle_io_errors=True)
# With destination in binary mode, data must be binary string
# and is written as-is:
def test_write_bytes(self):
- fo = io.FileOutput(destination=self.bdrain, encoding='utf-8',
- mode='wb', autoclose=False)
+ fo = du_io.FileOutput(destination=self.bdrain, encoding='utf-8',
+ mode='wb', autoclose=False)
fo.write(self.bdata)
self.assertEqual(self.bdrain.getvalue(), self.bdata)
@@ -205,14 +206,14 @@
def test_write_bytes_to_stdout(self):
# try writing data to `destination.buffer`, if data is
# instance of `bytes` and writing to `destination` fails:
- fo = io.FileOutput(destination=self.mock_stdout)
+ fo = du_io.FileOutput(destination=self.mock_stdout)
fo.write(self.bdata)
self.assertEqual(self.mock_stdout.buffer.getvalue(),
self.bdata)
def test_encoding_clash_resolved(self):
- fo = io.FileOutput(destination=self.mock_stdout,
- encoding='latin1', autoclose=False)
+ fo = du_io.FileOutput(destination=self.mock_stdout,
+ encoding='latin1', autoclose=False)
fo.write(self.udata)
self.assertEqual(self.mock_stdout.buffer.getvalue(),
self.udata.encode('latin1'))
@@ -219,19 +220,19 @@
def test_encoding_clash_nonresolvable(self):
del self.mock_stdout.buffer
- fo = io.FileOutput(destination=self.mock_stdout,
- encoding='latin1', autoclose=False)
+ fo = du_io.FileOutput(destination=self.mock_stdout,
+ encoding='latin1', autoclose=False)
self.assertRaises(ValueError, fo.write, self.udata)
class ErrorOutputTests(unittest.TestCase):
def test_defaults(self):
- e = io.ErrorOutput()
+ e = du_io.ErrorOutput()
self.assertEqual(e.destination, sys.stderr)
def test_bbuf(self):
buf = BBuf() # buffer storing byte string
- e = io.ErrorOutput(buf, encoding='ascii')
+ e = du_io.ErrorOutput(buf, encoding='ascii')
# write byte-string as-is
e.write(b'b\xfc')
self.assertEqual(buf.getvalue(), b'b\xfc')
@@ -250,7 +251,7 @@
def test_ubuf(self):
buf = UBuf() # buffer only accepting unicode string
# decode of binary strings
- e = io.ErrorOutput(buf, encoding='ascii')
+ e = du_io.ErrorOutput(buf, encoding='ascii')
e.write(b'b\xfc')
# use REPLACEMENT CHARACTER
self.assertEqual(buf.getvalue(), 'b\ufffd')
@@ -275,7 +276,7 @@
def test_bom_utf_8(self):
"""Drop optional BOM from utf-8 encoded files.
"""
- source = io.FileInput(
+ source = du_io.FileInput(
source_path=os.path.join(DATA_ROOT, 'utf-8-sig.txt'))
self.assertTrue(source.read().startswith('Grüße'))
@@ -283,7 +284,7 @@
"""Drop BOM from utf-16 encoded files, use correct encoding.
"""
# Assert correct decoding, BOM is gone.
- source = io.FileInput(
+ source = du_io.FileInput(
source_path=os.path.join(DATA_ROOT, 'utf-16-le-sig.txt'))
self.assertTrue(source.read().startswith('Grüße'))
@@ -290,17 +291,17 @@
def test_coding_slug(self):
"""Use self-declared encoding.
"""
- source = io.FileInput(
+ source = du_io.FileInput(
source_path=os.path.join(DATA_ROOT, 'latin2.txt'))
self.assertTrue(source.read().endswith('škoda\n'))
def test_fallback_utf8(self):
"""Try 'utf-8', if encoding is not specified in the source."""
- source = io.FileInput(
+ source = du_io.FileInput(
source_path=os.path.join(DATA_ROOT, 'utf8.txt'))
self.assertEqual(source.read(), 'Grüße\n')
- @unittest.skipIf(io._locale_encoding in (None, 'utf-8', 'utf8'),
+ @unittest.skipIf(du_io._locale_encoding in (None, 'utf-8', 'utf8'),
'locale encoding not set or UTF-8')
def test_fallback_no_utf8(self):
# if decoding with 'utf-8' fails, use the locale encoding
@@ -308,8 +309,8 @@
# provisional: behaviour details will change in future
# TODO: don't fall back to latin1
# TODO: use `locale.getpreferredlocale()` (honour UTF-8 mode)?
- probed_encodings = (io._locale_encoding, 'latin-1') # noqa
- source = io.FileInput(
+ probed_encodings = (du_io._locale_encoding, 'latin-1') # noqa
+ source = du_io.FileInput(
source_path=os.path.join(DATA_ROOT, 'latin1.txt'))
data = source.read()
self.assertTrue(source.successful_encoding in probed_encodings)
Modified: trunk/docutils/tools/buildhtml.py
===================================================================
--- trunk/docutils/tools/buildhtml.py 2023-02-07 14:24:37 UTC (rev 9328)
+++ trunk/docutils/tools/buildhtml.py 2023-02-07 14:24:46 UTC (rev 9329)
@@ -28,8 +28,8 @@
import warnings
import docutils
-from docutils import ApplicationError
-from docutils import core, frontend, io, utils
+import docutils.io
+from docutils import core, frontend, utils, ApplicationError
from docutils.parsers import rst
from docutils.readers import standalone, pep
from docutils.writers import html4css1, html5_polyglot, pep_html
@@ -226,7 +226,7 @@
def visit(self, directory, names, subdirectories):
settings = self.get_settings('', directory)
- errout = io.ErrorOutput(encoding=settings.error_encoding)
+ errout = docutils.io.ErrorOutput(encoding=settings.error_encoding)
if settings.prune and (os.path.abspath(directory) in settings.prune):
errout.write('/// ...Skipping directory (pruned): %s\n' %
directory)
@@ -253,7 +253,7 @@
else:
publisher = self.initial_settings.writer
settings = self.get_settings(publisher, directory)
- errout = io.ErrorOutput(encoding=settings.error_encoding)
+ errout = docutils.io.ErrorOutput(encoding=settings.error_encoding)
pub_struct = self.publishers[publisher]
settings._source = os.path.normpath(os.path.join(directory, name))
settings._destination = settings._source[:-4] + '.html'
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-04-06 18:41:15
|
Revision: 9336
http://sourceforge.net/p/docutils/code/9336
Author: milde
Date: 2023-04-06 18:41:10 +0000 (Thu, 06 Apr 2023)
Log Message:
-----------
Add "auto_encode" argument to `publish_string()`
Add "auto_encode" argument to publish_string() and
publish_programmatically() to give the user an option to select the
output type (`bytes` or `OutString`) in a way that does not interfere
with the intended encoding of the output
(the problem with the "dummy" output encoding name ``unicode``).
The default will change from ``False`` to ``True`` in Docutils 0.22
New class for `io.StringOutput`: `io.OutString` adds "encoding"
and "errors" attributes to `str`.
Allows storing the "output_encoding" and "output_encoding_error_handler"
settings in a transparent and easy to process way.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docutils/core.py
trunk/docutils/docutils/io.py
trunk/docutils/test/test_io.py
trunk/docutils/test/test_publisher.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2023-04-06 18:40:57 UTC (rev 9335)
+++ trunk/docutils/HISTORY.txt 2023-04-06 18:41:10 UTC (rev 9336)
@@ -25,6 +25,8 @@
- Added new `publish_bytes()` function to explicitly return
output as binary data in a `bytes` object.
+ - New argument "auto_encode" for `publish_string()` and
+ `publish_programmatically()`.
- New functions `rst2…()` for use as "console_scripts" `entry point`_.
* docutils/frontend.py
@@ -32,6 +34,11 @@
- New setting ``output``. Obsoletes the ``<destination>`` positional
argument (cf. "Future changes" in the RELEASE-NOTES).
+* docutils/io.py
+
+ - New `str` sub-class `io.OutString` with "encoding" and "errors"
+ attributes.
+
* docutils/languages/
docutils/parsers/rst/languages/
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2023-04-06 18:40:57 UTC (rev 9335)
+++ trunk/docutils/RELEASE-NOTES.txt 2023-04-06 18:41:10 UTC (rev 9336)
@@ -131,6 +131,10 @@
- Remove ``use_verbatim_when_possible`` setting
(use literal_block_env_: verbatim) in Docutils 2.0.
+* The default value of the `auto_encode` argument of
+ `core.publish_str()` and `core.publish_programmatically()`
+ will change to ``False`` in Docutils 0.22.
+
* Remove the "rawsource" argument from `nodes.Text.__init__()`
(deprecated and ignored since Docutils 0.18) in Docutils 2.0.
@@ -188,6 +192,11 @@
.. _[latex writers]: docs/user/config.html#latex-writers
+* The new function argument `auto_encode` for `core.publish_string()` and
+ `core.publish_programmatically()` selects whether the output document is
+ encoded and returned as `bytes` instance. The default will change to
+ ``False`` in Docutils 0.22.
+
* Bugfixes and improvements (see HISTORY_).
Modified: trunk/docutils/docutils/core.py
===================================================================
--- trunk/docutils/docutils/core.py 2023-04-06 18:40:57 UTC (rev 9335)
+++ trunk/docutils/docutils/core.py 2023-04-06 18:41:10 UTC (rev 9336)
@@ -435,27 +435,25 @@
writer=None, writer_name='pseudoxml',
settings=None, settings_spec=None,
settings_overrides=None, config_section=None,
- enable_exit_status=False):
+ enable_exit_status=False,
+ auto_encode=True):
"""
Set up & run a `Publisher` for programmatic use with string I/O.
Accepts a `bytes` or `str` instance as `source`.
- The output is encoded according to the "output_encoding" setting;
- the return value is a `bytes` instance (unless `output_encoding`_
- is "unicode", see below).
- To get Docutils output as `str` instance, use `publish_parts()`::
+ If `auto_encode` is True, the output is encoded according to the
+ `output_encoding`_ setting; the return value is a `bytes` instance
+ (unless `output_encoding`_ is "unicode",
+ cf. `docutils.io.StringOutput.write()`).
- output = publish_parts(...)['whole']
+ If `auto_encode` is False, the output is an instance of a `str`
+ sub-class with "output_encoding" and "output_encoding_error_handler"
+ settings stored as `encoding` and `errors` attributes.
- or set `output_encoding`_ to the pseudo encoding name "unicode", e.g.::
+ The default value of `auto_encode` will change to ``False`` in
+ Docutils 0.22.
- publish_string(..., settings_overrides={'output_encoding': 'unicode'})
-
- Beware that the `output_encoding`_ setting may affect the content
- of the output (e.g. an encoding declaration in HTML or XML or the
- representation of characters as LaTeX macro vs. literal character).
-
Parameters: see `publish_programmatically()`.
.. _output_encoding:
@@ -471,7 +469,8 @@
settings=settings, settings_spec=settings_spec,
settings_overrides=settings_overrides,
config_section=config_section,
- enable_exit_status=enable_exit_status)
+ enable_exit_status=enable_exit_status,
+ auto_encode=auto_encode)
return output
@@ -662,7 +661,8 @@
writer, writer_name,
settings, settings_spec,
settings_overrides, config_section,
- enable_exit_status):
+ enable_exit_status,
+ auto_encode=True):
"""
Set up & run a `Publisher` for custom programmatic use.
@@ -754,6 +754,10 @@
defined by `settings_spec`. Used only if no `settings` specified.
* `enable_exit_status`: Boolean; enable exit status at end of processing?
+
+ * `auto_encode`: Boolean; encode string output and return `bytes`?
+ Ignored with `io.FileOutput`.
+ The default value will change to ``False`` in Docutils 0.22.
"""
publisher = Publisher(reader, parser, writer, settings=settings,
source_class=source_class,
@@ -763,6 +767,8 @@
settings_spec, settings_overrides, config_section)
publisher.set_source(source, source_path)
publisher.set_destination(destination, destination_path)
+ if not auto_encode and isinstance(publisher.destination, io.StringOutput):
+ publisher.destination.auto_encode = auto_encode
output = publisher.publish(enable_exit_status=enable_exit_status)
return output, publisher
Modified: trunk/docutils/docutils/io.py
===================================================================
--- trunk/docutils/docutils/io.py 2023-04-06 18:40:57 UTC (rev 9335)
+++ trunk/docutils/docutils/io.py 2023-04-06 18:41:10 UTC (rev 9336)
@@ -74,6 +74,57 @@
return f'{err.__class__.__name__}: {err}'
+class OutString(str):
+ """Return a string representation of `object` with known encoding.
+
+ Differences to `str()`:
+
+ If the `encoding` is given, both `str` instances and byte-like objects
+ are stored as text string, the latter decoded with `encoding` and
+ `errors` (defaulting to 'strict').
+
+ The encoding is never guessed. If `encoding` is None (the default),
+ an informal string representation is used, also if `errors` are given.
+
+ The original or intended encoding and error handler are stored in the
+ attributes `encoding` and `errors`.
+ Typecasting to `bytes` uses the stored values.
+ """
+
+ def __new__(cls, object, encoding=None, errors='strict'):
+ """Return a new OutString object.
+
+ Provisional.
+ """
+ try:
+ # decode bytes-like objects if encoding is known
+ return super().__new__(cls, object, encoding, errors)
+ except TypeError:
+ return super().__new__(cls, object)
+
+ def __init__(self, object, encoding=None, errors='strict'):
+ """Set "encoding" and "errors" attributes."""
+ self.encoding = encoding
+ self.errors = errors
+
+ def __bytes__(self):
+ try:
+ return super().encode(self.encoding, self.errors)
+ except TypeError:
+ raise TypeError('OutString instance without known encoding')
+
+ def __repr__(self):
+ if self.errors != 'strict':
+ errors_arg = f', errors={self.errors!r}'
+ else:
+ errors_arg = ''
+ return (f'{self.__class__.__name__}({super().__repr__()}, '
+ f'encoding={self.encoding!r}{errors_arg})')
+
+ def encode(self, encoding=None, errors=None):
+ return super().encode(encoding or self.encoding, errors or self.errors)
+
+
class Input(TransformSpec):
"""
Abstract base class for input wrappers.
@@ -264,7 +315,8 @@
raise NotImplementedError
def encode(self, data):
- """Encode and return `data`.
+ """
+ Encode and return `data`.
If `data` is a `bytes` instance, it is returned unchanged.
Otherwise it is encoded with `self.encoding`.
@@ -271,7 +323,6 @@
If `self.encoding` is set to the pseudo encoding name "unicode",
`data` must be a `str` instance and is returned unchanged.
-
"""
if self.encoding and self.encoding.lower() == 'unicode':
assert isinstance(data, str), ('output encoding is "unicode" '
@@ -616,14 +667,39 @@
default_destination_path = '<string>'
+ def __init__(self, destination=None, destination_path=None,
+ encoding=None, error_handler='strict', auto_encode=True):
+ self.auto_encode = auto_encode
+ """Let `write()` encode the output document and return `bytes`."""
+ super().__init__(destination, destination_path,
+ encoding, error_handler)
+
def write(self, data):
- """Encode `data`, store it in `self.destination`, and return it.
+ """Store `data` in `self.destination`, and return it.
+ If `self.auto_encode` is False, store and return a `str`
+ sub-class instance with "encoding" and "errors" attributes
+ set to `self.encoding` and `self.error_handler`.
+
+ If `self.auto_encode` is True, encode `data` with `self.encoding`
+ and `self.error_handler` and store/return a `bytes` instance.
+ Exception:
If `self.encoding` is set to the pseudo encoding name "unicode",
`data` must be a `str` instance and is returned unchanged
(cf. `Output.encode`).
+ Beware that the `output_encoding`_ setting may affect the content
+ of the output (e.g. an encoding declaration in HTML or XML or the
+ representation of characters as LaTeX macro vs. literal character).
"""
- self.destination = self.encode(data)
+ if self.auto_encode:
+ self.destination = self.encode(data)
+ return self.destination
+
+ if not self.encoding or self.encoding.lower() == 'unicode':
+ encoding = None
+ else:
+ encoding = self.encoding
+ self.destination = OutString(data, encoding, self.error_handler)
return self.destination
Modified: trunk/docutils/test/test_io.py
===================================================================
--- trunk/docutils/test/test_io.py 2023-04-06 18:40:57 UTC (rev 9335)
+++ trunk/docutils/test/test_io.py 2023-04-06 18:41:10 UTC (rev 9336)
@@ -190,6 +190,19 @@
fo.write(self.udata)
self.assertEqual(self.udrain.getvalue(), self.udata)
+ def test_write_auto_encode_false(self):
+ so = du_io.StringOutput(encoding='latin1', error_handler='replace',
+ auto_encode=False)
+ output = so.write(self.udata)
+ # store output in self.destination and also return it
+ self.assertEqual(output, self.udata)
+ self.assertEqual(so.destination, self.udata)
+ # store also encoding and encoding error handler ...
+ self.assertEqual(output.encoding, 'latin1')
+ self.assertEqual(output.errors, 'replace')
+ # ... to allow easy conversion to `bytes`:
+ self.assertEqual(bytes(output), self.bdata)
+
def test_FileOutput_hande_io_errors_deprection_warning(self):
with self.assertWarnsRegex(DeprecationWarning,
'"handle_io_errors" is ignored'):
@@ -225,6 +238,52 @@
self.assertRaises(ValueError, fo.write, self.udata)
+class OutStringTests(unittest.TestCase):
+
+ def test__init__defaults(self):
+ """Test `__new__()` and `__init__()` with default values."""
+
+ os = du_io.OutString('Grüße')
+ self.assertEqual(str(os), 'Grüße')
+ self.assertEqual(os.encoding, None)
+ self.assertEqual(os.errors, 'strict')
+ # converting to `bytes` fails if the encoding is not known:
+ with self.assertRaises(TypeError):
+ self.assertEqual(bytes(os), 'Grüße')
+ # without known encoding, `bytes` and other incompatible types
+ # are converted to their string representation ...
+ bos = du_io.OutString(b'gut')
+ self.assertEqual(str(bos), "b'gut'")
+ bos_e = du_io.OutString('Grüße'.encode('latin1'), errors='ignore')
+ self.assertEqual(str(bos_e), r"b'Gr\xfc\xdfe'")
+ bos = du_io.OutString(b'gut', encoding=None)
+ self.assertEqual(str(bos), "b'gut'")
+
+ def test__init__custom_attributes(self):
+ """Test `__new__()` and `__init__()` with custom encoding."""
+ os8 = du_io.OutString('Grüße', encoding='utf-8')
+ self.assertEqual(str(os8), 'Grüße')
+ self.assertEqual(bytes(os8), b'Gr\xc3\xbc\xc3\x9fe')
+ self.assertEqual(repr(os8), "OutString('Grüße', encoding='utf-8')")
+ # With known encoding, "bytes-like" objects are decoded
+ bos1 = du_io.OutString(b'Gr\xfc\xdfe', encoding='latin1')
+ self.assertEqual(str(bos1), 'Grüße')
+ self.assertEqual(bytes(bos1), b'Gr\xfc\xdfe')
+ # Invalid encodings (including the empty string) raise an error
+ with self.assertRaises(LookupError):
+ du_io.OutString(b'Gr\xfc\xdfe', encoding='')
+
+ def test__init__custom_errors(self):
+ """Test `__new__()` and `__init__()` with custom `errors`."""
+ ts8_r = du_io.OutString('Grüße', encoding='utf-8', errors='replace')
+ # Encoding uses the stored error handler:
+ self.assertEqual(ts8_r.encode('ascii'), b'Gr??e')
+ # Initialization with a `bytes` object uses the error handler, too:
+ bts8_r = du_io.OutString(b'Gr\xfc\xdfe', encoding='utf-8',
+ errors='replace')
+ self.assertEqual(str(bts8_r), 'Gr��e')
+
+
class ErrorOutputTests(unittest.TestCase):
def test_defaults(self):
e = du_io.ErrorOutput()
Modified: trunk/docutils/test/test_publisher.py
===================================================================
--- trunk/docutils/test/test_publisher.py 2023-04-06 18:40:57 UTC (rev 9335)
+++ trunk/docutils/test/test_publisher.py 2023-04-06 18:41:10 UTC (rev 9336)
@@ -99,7 +99,8 @@
core.publish_cmdline(argv=['-', 'dest_name'],
settings_overrides=settings)
- def test_publish_string(self):
+ def test_publish_string_input_encoding(self):
+ """Test handling of encoded input."""
# Transparently decode `bytes` source (with "input_encoding" setting)
# default: auto-detect, fallback utf-8
# Output is encoded according to "output_encoding" setting.
@@ -121,7 +122,25 @@
settings_overrides=settings)
self.assertTrue(output.endswith('Grüße\n'))
+ def test_publish_string_output_encoding(self):
+ settings = {'_disable_config': True,
+ 'datestamp': False,
+ 'output_encoding': 'latin1',
+ 'output_encoding_error_handler': 'replace'}
+ source = 'Grüß → dich'
+ expected = ('<document source="<string>">\n'
+ ' <paragraph>\n'
+ ' Grüß → dich\n')
+ # current default: encode output, return `bytes`
+ output = core.publish_string(source, settings_overrides=settings)
+ self.assertEqual(output, expected.encode('latin1', 'replace'))
+ # no encoding if `auto_encode` is False:
+ output = core.publish_string(source, settings_overrides=settings,
+ auto_encode=False)
+ self.assertEqual(output, expected)
+ # self.assertEqual(output.encoding, 'latin1')
+
class PublishDoctreeTestCase(unittest.TestCase, docutils.SettingsSpec):
settings_default_overrides = {
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-04-08 21:08:54
|
Revision: 9338
http://sourceforge.net/p/docutils/code/9338
Author: milde
Date: 2023-04-08 21:08:47 +0000 (Sat, 08 Apr 2023)
Log Message:
-----------
LaTeX to MathML: fix ``\mspace``.
LaTeX width unit "mu" (mathematical unit) must be converted for MathML.
Typo in the code resulted in wrong "width" argument for `<mspace>`.
Modified Paths:
--------------
trunk/docutils/docs/ref/rst/mathematics.txt
trunk/docutils/docutils/utils/math/latex2mathml.py
trunk/docutils/docutils/writers/html5_polyglot/plain.css
trunk/docutils/docutils/writers/html5_polyglot/responsive.css
Modified: trunk/docutils/docs/ref/rst/mathematics.txt
===================================================================
--- trunk/docutils/docs/ref/rst/mathematics.txt 2023-04-06 20:31:09 UTC (rev 9337)
+++ trunk/docutils/docs/ref/rst/mathematics.txt 2023-04-08 21:08:47 UTC (rev 9338)
@@ -652,7 +652,7 @@
====================== ======== ===================== ==================
.. [#] Whitespace characters are ignored in LaTeX math mode.
-.. [#] Unit must be 'mu' (1 mu = 1/18em).
+.. [#] In LaTeX, unit must be 'mu' (1 mu = 1/18em).
Negative spacing does not work with MathML (in Firefox 78).
Modified: trunk/docutils/docutils/utils/math/latex2mathml.py
===================================================================
--- trunk/docutils/docutils/utils/math/latex2mathml.py 2023-04-06 20:31:09 UTC (rev 9337)
+++ trunk/docutils/docutils/utils/math/latex2mathml.py 2023-04-08 21:08:47 UTC (rev 9338)
@@ -206,16 +206,16 @@
spaces = {'qquad': '2em', # two \quad
'quad': '1em', # 18 mu
'thickspace': '0.2778em', # 5mu = 5/18em
+ ';': '0.2778em', # 5mu thickspace
+ ' ': '0.25em', # inter word space
'medspace': '0.2222em', # 4mu = 2/9em
+ ':': '0.2222em', # 4mu medspace
'thinspace': '0.1667em', # 3mu = 1/6em
+ ',': '0.1667em', # 3mu thinspace
'negthinspace': '-0.1667em', # -3mu = -1/6em
+ '!': '-0.1667em', # negthinspace
'negmedspace': '-0.2222em', # -4mu = -2/9em
'negthickspace': '-0.2778em', # -5mu = -5/18em
- ' ': '0.25em', # inter word space
- ';': '0.2778em', # 5mu thickspace
- ':': '0.2222em', # 4mu medspace
- ',': '0.1667em', # 3mu thinspace
- '!': '-0.1667em', # negthinspace
}
# accents -> <mover stretchy="false">
@@ -1101,7 +1101,8 @@
if name in ('hspace', 'mspace'):
arg, string = tex_group(string)
- if arg.endswith('m'):
+ if arg.endswith('mu'):
+ # unit "mu" (1mu=1/18em) not supported by MathML
arg = '%sem' % (float(arg[:-2])/18)
node = node.append(mspace(width='%s'%arg))
return node, string
Modified: trunk/docutils/docutils/writers/html5_polyglot/plain.css
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/plain.css 2023-04-06 20:31:09 UTC (rev 9337)
+++ trunk/docutils/docutils/writers/html5_polyglot/plain.css 2023-04-08 21:08:47 UTC (rev 9338)
@@ -281,7 +281,8 @@
font-weight: bold;
}
mstyle.mathscr, mi.mathscr {
- font-family: STIX;
+ font-family: STIX, XITSMathJax_Script, rsfs10,
+ "Asana Math", Garamond, cursive;
}
/* Epigraph */
Modified: trunk/docutils/docutils/writers/html5_polyglot/responsive.css
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/responsive.css 2023-04-06 20:31:09 UTC (rev 9337)
+++ trunk/docutils/docutils/writers/html5_polyglot/responsive.css 2023-04-08 21:08:47 UTC (rev 9338)
@@ -17,8 +17,8 @@
/* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */
/* .. _CSS3: https://www.w3.org/Style/CSS/ */
-/* Note: */
-/* This style sheet is provisional: */
+/* Note: */
+/* This style sheet is provisional: */
/* the API is not settled and may change with any minor Docutils version. */
@@ -357,7 +357,8 @@
font-weight: bold;
}
mstyle.mathscr, mi.mathscr {
- font-family: STIX;
+ font-family: STIX, XITSMathJax_Script, rsfs10,
+ "Asana Math", Garamond, cursive;
}
/* Adaptive page layout */
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-04-08 21:09:05
|
Revision: 9339
http://sourceforge.net/p/docutils/code/9339
Author: milde
Date: 2023-04-08 21:08:59 +0000 (Sat, 08 Apr 2023)
Log Message:
-----------
Revert introduction of `core.publish_bytes()` and `io.BytesOutput`.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/docutils/core.py
trunk/docutils/docutils/io.py
trunk/docutils/test/test_writers/test_docutils_xml.py
trunk/docutils/test/test_writers/test_html4css1_misc.py
trunk/docutils/test/test_writers/test_html5_polyglot_misc.py
trunk/docutils/test/test_writers/test_odt.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2023-04-08 21:08:47 UTC (rev 9338)
+++ trunk/docutils/HISTORY.txt 2023-04-08 21:08:59 UTC (rev 9339)
@@ -23,8 +23,6 @@
* docutils/core.py
- - Added new `publish_bytes()` function to explicitly return
- output as binary data in a `bytes` object.
- New argument "auto_encode" for `publish_string()` and
`publish_programmatically()`.
- New functions `rst2…()` for use as "console_scripts" `entry point`_.
Modified: trunk/docutils/docutils/core.py
===================================================================
--- trunk/docutils/docutils/core.py 2023-04-08 21:08:47 UTC (rev 9338)
+++ trunk/docutils/docutils/core.py 2023-04-08 21:08:59 UTC (rev 9339)
@@ -474,43 +474,6 @@
return output
-def publish_bytes(source, source_path=None, destination_path=None,
- reader=None, reader_name='standalone',
- parser=None, parser_name='restructuredtext',
- writer=None, writer_name='pseudoxml',
- settings=None, settings_spec=None,
- settings_overrides=None, config_section=None,
- enable_exit_status=False):
- """
- Set up & run a `Publisher` for programmatic use with string I/O. Return
- the encoded bytes.
-
- Be sure to set the 'output_encoding' setting to the desired encoding.::
-
- publish_bytes(..., settings_overrides={'output_encoding': 'latin1'})
-
- Similarly for bytes input (`source`)::
-
- publish_bytes(..., settings_overrides={'input_encoding': 'latin1'})
-
- Parameters: see `publish_programmatically()`.
-
- Provisional.
- """
- output, publisher = publish_programmatically(
- source_class=io.StringInput, source=source, source_path=source_path,
- destination_class=io.BytesOutput,
- destination=None, destination_path=destination_path,
- reader=reader, reader_name=reader_name,
- parser=parser, parser_name=parser_name,
- writer=writer, writer_name=writer_name,
- settings=settings, settings_spec=settings_spec,
- settings_overrides=settings_overrides,
- config_section=config_section,
- enable_exit_status=enable_exit_status)
- return output
-
-
def publish_parts(source, source_path=None, source_class=io.StringInput,
destination_path=None,
reader=None, reader_name='standalone',
Modified: trunk/docutils/docutils/io.py
===================================================================
--- trunk/docutils/docutils/io.py 2023-04-08 21:08:47 UTC (rev 9338)
+++ trunk/docutils/docutils/io.py 2023-04-08 21:08:59 UTC (rev 9339)
@@ -629,26 +629,6 @@
mode = 'wb'
-class BytesOutput(Output):
-
- """
- Direct binary output.
- Provisional.
- """
-
- default_destination_path = '<bytes>'
-
- def write(self, data):
- """Encode `data`, store it in `self.destination`, and return it."""
- self.destination = self.encode(data)
- return self.destination
-
- def encode(self, data):
- if isinstance(data, bytes):
- return data
- return str(data).encode(self.encoding, self.error_handler)
-
-
class StringInput(Input):
"""Input from a `str` or `bytes` instance."""
Modified: trunk/docutils/test/test_writers/test_docutils_xml.py
===================================================================
--- trunk/docutils/test/test_writers/test_docutils_xml.py 2023-04-08 21:08:47 UTC (rev 9338)
+++ trunk/docutils/test/test_writers/test_docutils_xml.py 2023-04-08 21:08:59 UTC (rev 9339)
@@ -121,7 +121,7 @@
def publish_xml(settings, source):
- return docutils.core.publish_bytes(source=source.encode('utf-8'),
+ return docutils.core.publish_string(source=source.encode('utf-8'),
reader_name='standalone',
writer_name='docutils_xml',
settings_overrides=settings)
Modified: trunk/docutils/test/test_writers/test_html4css1_misc.py
===================================================================
--- trunk/docutils/test/test_writers/test_html4css1_misc.py 2023-04-08 21:08:47 UTC (rev 9338)
+++ trunk/docutils/test/test_writers/test_html4css1_misc.py 2023-04-08 21:08:59 UTC (rev 9339)
@@ -33,7 +33,7 @@
'stylesheet': '',
'_disable_config': True,
}
- result = core.publish_bytes(
+ result = core.publish_string(
'EUR = \u20ac', writer_name='html4css1',
settings_overrides=settings_overrides)
# Encoding a euro sign with latin1 doesn't work, so the
Modified: trunk/docutils/test/test_writers/test_html5_polyglot_misc.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_polyglot_misc.py 2023-04-08 21:08:47 UTC (rev 9338)
+++ trunk/docutils/test/test_writers/test_html5_polyglot_misc.py 2023-04-08 21:08:59 UTC (rev 9339)
@@ -39,7 +39,7 @@
'output_encoding': 'latin1',
'stylesheet': '',
'_disable_config': True}
- result = core.publish_bytes(
+ result = core.publish_string(
'EUR = \u20ac', writer_name='html5_polyglot',
settings_overrides=settings_overrides)
# Encoding a euro sign with latin1 doesn't work, so the
Modified: trunk/docutils/test/test_writers/test_odt.py
===================================================================
--- trunk/docutils/test/test_writers/test_odt.py 2023-04-08 21:08:47 UTC (rev 9338)
+++ trunk/docutils/test/test_writers/test_odt.py 2023-04-08 21:08:59 UTC (rev 9339)
@@ -73,7 +73,7 @@
settings_overrides['_disable_config'] = True
settings_overrides['language_code'] = 'en-US'
- result = docutils.core.publish_bytes(
+ result = docutils.core.publish_string(
source=input,
reader_name='standalone',
writer_name='odf_odt',
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-04-08 21:09:10
|
Revision: 9340
http://sourceforge.net/p/docutils/code/9340
Author: milde
Date: 2023-04-08 21:09:08 +0000 (Sat, 08 Apr 2023)
Log Message:
-----------
Update "Publisher" documentation.
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/api/publisher.txt
trunk/docutils/docs/index.txt
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2023-04-08 21:08:59 UTC (rev 9339)
+++ trunk/docutils/RELEASE-NOTES.txt 2023-04-08 21:09:08 UTC (rev 9340)
@@ -100,7 +100,7 @@
- Change the default input encoding from ``None`` (auto-detect) to
"utf-8" in Docutils 0.22.
- - Remove the input encoding auto-detection code in Docutils 1.0.
+ - Remove the input encoding auto-detection code in Docutils 1.0 or later.
* "html5" writer:
@@ -194,8 +194,8 @@
* The new function argument `auto_encode` for `core.publish_string()` and
`core.publish_programmatically()` selects whether the output document is
- encoded and returned as `bytes` instance. The default will change to
- ``False`` in Docutils 0.22.
+ encoded and returned as `bytes` instance. The default is ``True`` (for
+ backwards compatibility) and will change to ``False`` in Docutils 0.22.
* Bugfixes and improvements (see HISTORY_).
Modified: trunk/docutils/docs/api/publisher.txt
===================================================================
--- trunk/docutils/docs/api/publisher.txt 2023-04-08 21:08:59 UTC (rev 9339)
+++ trunk/docutils/docs/api/publisher.txt 2023-04-08 21:09:08 UTC (rev 9340)
@@ -17,7 +17,7 @@
managing all the processing and relationships between components. See
`PEP 258`_ for an overview of Docutils components.
-The ``docutils.core.publish_*`` convenience functions are the normal
+The ``docutils.core.publish_*()`` convenience functions are the normal
entry points for using Docutils as a library.
See `Inside A Docutils Command-Line Front-End Tool`_ for an overview
@@ -31,157 +31,102 @@
Publisher Convenience Functions
===============================
-Each of these functions set up a ``docutils.core.Publisher`` object,
-then call its ``publish`` method. ``docutils.core.Publisher.publish``
+Each of these functions sets up a `docutils.core.Publisher` object,
+then calls its ``publish()`` method. ``docutils.core.Publisher.publish()``
handles everything else. There are several convenience functions in
the ``docutils.core`` module:
-:_`publish_cmdline()`: for command-line front-end tools, like
- ``rst2html.py``. There are several examples in the ``tools/``
- directory. A detailed analysis of one such tool is in `Inside A
- Docutils Command-Line Front-End Tool`_
-:_`publish_file()`: for programmatic use with file-like I/O. In
- addition to writing the encoded output to a file, also returns the
- encoded output as a `bytes` instance.
+publish_cmdline()
+-----------------
-:_`publish_string()`: for programmatic use with `string I/O`_. Returns
- the encoded output as a string [#string-output]_.
+Function for command-line front-end tools, like ``rst2html.py``. There are
+several examples in the ``tools/`` directory. A detailed analysis of one
+such tool is in `Inside A Docutils Command-Line Front-End Tool`_.
-:_`publish_parts()`: for programmatic use with string input [#string-input]_;
- returns a dictionary of document parts. Dictionary keys are the names of
- parts, and values are `str` instances; encoding is up to the client.
- Useful when only portions of the processed document are desired.
- See `publish_parts() Details`_ below.
-
- There are usage examples in the `docutils/examples.py`_ module.
-
-:_`publish_doctree()`: for programmatic use with string input [#string-input]_;
- returns a Docutils document tree data structure (doctree).
- The doctree can be modified, pickled & unpickled, etc., and then
- reprocessed with `publish_from_doctree()`_.
-
-:_`publish_from_doctree()`: for programmatic use to render from an
- existing document tree data structure (doctree); returns the encoded
- output as a string [#string-output]_.
-
-:_`publish_programmatically()`: for custom programmatic use. This
- function implements common code and is used by ``publish_file``,
- ``publish_string``, and ``publish_parts``. It returns a 2-tuple:
- the encoded string output [#string-output]_ and the Publisher object.
-
.. _Inside A Docutils Command-Line Front-End Tool: ../howto/cmdline-tool.html
-.. _docutils/examples.py: ../../docutils/examples.py
-.. _String I/O:
-.. [#string-input] Input can be a `str` or `bytes` instance.
- `bytes` are decoded with input_encoding_.
-.. [#string-output] Output is a `bytes` instance unless
- output_encoding_ is set to the special value ``"unicode"``.
+publish_file()
+--------------
+For programmatic use with file-like I/O.
+In addition to writing the output document to a file, also returns it as
+a `bytes` instance.
-Configuration
--------------
-To pass application-specific setting defaults to the Publisher
-convenience functions, use the ``settings_overrides`` parameter. Pass
-a dictionary of setting names & values, like this::
+publish_string()
+----------------
- overrides = {'input_encoding': 'ascii',
- 'output_encoding': 'latin-1'}
- output = publish_string(..., settings_overrides=overrides)
+For programmatic use with _`string I/O`:
-Settings from command-line options override configuration file
-settings, and they override application defaults. For details, see
-`Docutils Runtime Settings`_. See `Docutils Configuration`_ for
-details about individual settings.
+Input
+ can be a `str` or `bytes` instance.
+ `bytes` are decoded with input_encoding_.
-.. _Docutils Runtime Settings: ./runtime-settings.html
-.. _Docutils Configuration: ../user/config.html
+Output
+ is a memory object:
+ * a `str` instance [#]_, if the "encode_output" function argument is
+ ``False`` or output_encoding_ is set to the special value
+ ``"unicode"``.
-Encodings
----------
+ * a `bytes` instance, if the "encode_output" argument is ``True`` and
+ output_encoding_ is set to an encoding registerd with
+ Python's "codecs_" module (default: "utf-8").
-The default **input encoding** is UTF-8 (codec 'utf-8-sig').
-A different encoding can be specified with the `input_encoding`_ setting
-or an `explicit encoding declaration`_ (BOM or special comment).
-If the encoding is unspecified and decoding with UTF-8 fails,
-the `preferred encoding`_ is used as a fallback
-(if it maps to a valid codec and differs from UTF-8).
+ Calling ``output = bytes(publish_string(…))`` ensures that
+ ``output`` is a `bytes` instance encoded with output_encoding_.
-The default behaviour differs from Python's `open()`:
+.. [#] Actually an instance of a `str` sub-class with the
+ output_encoding_ and output_encoding_error_handler_ configuration
+ settings stored as "encoding" and "errors" attributes.
-- The UTF-8 encoding is tried before the `preferred encoding`_.
- (This is almost sure to fail if the actual source encoding differs.)
-- An `explicit encoding declaration`_ in the source takes precedence
- over the `preferred encoding`_.
-- An optional BOM_ is removed from UTF-8 encoded sources.
+.. _codecs: https://docs.python.org/3/library/codecs.html
-The default **output encoding** of Docutils is UTF-8.
-A different encoding can be specified with the `output_encoding`_ setting.
-Docutils may introduce some non-ASCII text if you use
-`auto-symbol footnotes`_ or the `"contents" directive`_.
-Explicit encoding declaration
-`````````````````````````````
+publish_doctree()
+-----------------
-A `Unicode byte order mark` (BOM_) in the source is interpreted as
-encoding declaration.
+Parse string input (cf. `string I/O`_) into a `Docutils document tree`_ data
+structure (doctree). The doctree can be modified, pickled & unpickled,
+etc., and then reprocessed with `publish_from_doctree()`_.
-The encoding of a reStructuredText source file can also be given by a
-"magic comment" similar to :PEP:`263`.
-This makes the input encoding both *visible* and *changeable*
-on a per-source file basis.
+.. _Docutils document tree: ../ref/doctree.html
-To declare the input encoding, a comment like ::
- .. text encoding: <encoding name>
+publish_from_doctree()
+----------------------
-must be placed into the source file either as first or second line.
+Render from an existing document tree data structure (doctree).
+Returns the output document as a memory object (cf. `string I/O`_).
-Examples: (using formats recognized by popular editors) ::
- .. -*- mode: rst -*-
- -*- coding: latin1 -*-
+publish_programmatically()
+--------------------------
-or::
+This function implements common code and is used by `publish_file()`_,
+`publish_string()`_, and `publish_parts()`_.
+It returns a 2-tuple: the output document as memory object (cf. `string
+I/O`_) and the Publisher object.
- .. vim: set fileencoding=cp737 :
-More precisely, the first and second line are searched for the following
-regular expression::
+publish_parts()
+---------------
- coding[:=]\s*([-\w.]+)
+For programmatic use with string input (cf. `string I/O`_).
+Returns a dictionary of document parts. Dictionary keys are the names of
+parts, and values are `str` instances; encoding is up to the client.
+Useful when only portions of the processed document are desired.
-The first group of this expression is then interpreted as encoding name.
-If the first line matches the second line is ignored.
+There are usage examples in the `docutils/examples.py`_ module.
-.. _input_encoding: ../user/config.html#input-encoding
-.. _preferred encoding:
- https://docs.python.org/3/library/locale.html#locale.getpreferredencoding
-.. _BOM: https://docs.python.org/3/library/codecs.html#codecs.BOM
-.. _output_encoding: ../user/config.html#output-encoding
-.. _auto-symbol footnotes:
- ../ref/rst/restructuredtext.html#auto-symbol-footnotes
-.. _"contents" directive:
- ../ref/rst/directives.html#table-of-contents
-
-
-``publish_parts()`` Details
-===========================
-
-The ``docutils.core.publish_parts()`` convenience function returns a
-dictionary of document parts. Dictionary keys are the names of parts,
-and values are `str` instances.
-
Each Writer component may publish a different set of document parts,
described below. Not all writers implement all parts.
Parts Provided By All Writers
------------------------------
+`````````````````````````````
_`encoding`
The output encoding setting.
@@ -194,10 +139,10 @@
Parts Provided By the HTML Writers
-----------------------------------
+``````````````````````````````````
HTML4 Writer
-````````````
+^^^^^^^^^^^^
_`body`
``parts['body']`` is equivalent to parts['fragment_']. It is
@@ -319,7 +264,7 @@
PEP/HTML Writer
-```````````````
+^^^^^^^^^^^^^^^
The PEP/HTML writer provides the same parts as the `HTML4 writer`_,
plus the following:
@@ -332,13 +277,13 @@
S5/HTML Writer
-``````````````
+^^^^^^^^^^^^^^
The S5/HTML writer provides the same parts as the `HTML4 writer`_.
HTML5 Writer
-````````````
+^^^^^^^^^^^^
The HTML5 writer provides the same parts as the `HTML4 writer`_.
However, it uses semantic HTML5 elements for the document, header and
@@ -345,8 +290,8 @@
footer.
-Parts Provided by the LaTeX2e Writer
-------------------------------------
+Parts Provided by the "LaTeX2e" and "XeTeX" Writers
+```````````````````````````````````````````````````
See the template files default.tex_, titlepage.tex_, titlingpage.tex_,
and xelatex.tex_ for examples how these parts can be combined
@@ -427,3 +372,100 @@
https://docutils.sourceforge.io/docutils/writers/latex2e/titlingpage.tex
.. _xelatex.tex:
https://docutils.sourceforge.io/docutils/writers/latex2e/xelatex.tex
+
+
+.. _docutils/examples.py: ../../docutils/examples.py
+
+
+Configuration
+=============
+
+To pass application-specific setting defaults to the Publisher
+convenience functions, use the ``settings_overrides`` parameter. Pass
+a dictionary of setting names & values, like this::
+
+ overrides = {'input_encoding': 'ascii',
+ 'output_encoding': 'latin-1'}
+ output = publish_string(..., settings_overrides=overrides)
+
+Settings from command-line options override configuration file
+settings, and they override application defaults. For details, see
+`Docutils Runtime Settings`_. See `Docutils Configuration`_ for
+details about individual settings.
+
+.. _Docutils Runtime Settings: ./runtime-settings.html
+.. _Docutils Configuration: ../user/config.html
+
+
+Encodings
+=========
+
+.. important:: Details will change over the next Docutils versions.
+ See RELEASE-NOTES_
+
+The default **input encoding** is UTF-8. A different encoding can be
+specified with the `input_encoding`_ setting.
+
+The encoding of a reStructuredText source can also be given by a
+`Unicode byte order mark` (BOM_) or a "magic comment" [#magic-comment]_
+similar to :PEP:`263`. This makes the input encoding both *visible* and
+*changeable* on a per-source basis.
+
+If the encoding is unspecified and decoding with UTF-8 fails, the locale's
+`preferred encoding`_ is used as a fallback (if it maps to a valid codec
+and differs from UTF-8).
+
+The default behaviour differs from Python's `open()`:
+
+- The UTF-8 encoding is tried before the `preferred encoding`_.
+ (This is almost sure to fail if the actual source encoding differs.)
+- An `explicit encoding declaration` [#magic-comment]_ in the source
+ takes precedence over the `preferred encoding`_.
+- An optional BOM_ is removed from UTF-8 encoded sources.
+
+The default **output encoding** is UTF-8.
+A different encoding can be specified with the `output_encoding`_ setting.
+
+.. Caution:: Docutils may introduce non-ASCII text if you use
+ `auto-symbol footnotes`_ or the `"contents" directive`_.
+
+.. [#magic-comment] A comment like ::
+
+ .. text encoding: <encoding name>
+
+ on the first or second line of a reStructuredText source
+ defines `<encoding name>` as the source's input encoding.
+
+ Examples: (using formats recognized by popular editors) ::
+
+ .. -*- mode: rst -*-
+ -*- coding: latin1 -*-
+
+ or::
+
+ .. vim: set fileencoding=cp737 :
+
+ More precisely, the first and second line are searched for the following
+ regular expression::
+
+ coding[:=]\s*([-\w.]+)
+
+ The first group of this expression is then interpreted as encoding name.
+ If the first line matches the second line is ignored.
+
+ This feature is scheduled to be removed in Docutils 1.0.
+ See the `inspecting_codecs`_ package for a possible replacement.
+
+.. _RELEASE-NOTES: ../../RELEASE-NOTES.html#future-changes
+.. _input_encoding: ../user/config.html#input-encoding
+.. _preferred encoding:
+ https://docs.python.org/3/library/locale.html#locale.getpreferredencoding
+.. _BOM: https://docs.python.org/3/library/codecs.html#codecs.BOM
+.. _output_encoding: ../user/config.html#output-encoding
+.. _output_encoding_error_handler:
+ ../user/config.html#output-encoding-error-handler
+.. _auto-symbol footnotes:
+ ../ref/rst/restructuredtext.html#auto-symbol-footnotes
+.. _"contents" directive:
+ ../ref/rst/directives.html#table-of-contents
+.. _inspecting_codecs: https://codeberg.org/milde/inspecting-codecs
Modified: trunk/docutils/docs/index.txt
===================================================================
--- trunk/docutils/docs/index.txt 2023-04-08 21:08:59 UTC (rev 9339)
+++ trunk/docutils/docs/index.txt 2023-04-08 21:09:08 UTC (rev 9340)
@@ -185,9 +185,12 @@
API Reference Material for Client-Developers
============================================
-* `The Docutils Publisher <api/publisher.html>`__
-* `Docutils Runtime Settings <api/runtime-settings.html>`__
-* `Docutils Transforms <api/transforms.html>`__
+`The Docutils Publisher <api/publisher.html>`__
+ entry points for using Docutils as a library
+`Docutils Runtime Settings <api/runtime-settings.html>`__
+ configuration framework details
+`Docutils Transforms <api/transforms.html>`__
+ change the document tree in-place (resolve references, …)
The `Docutils Design Specification`_ (PEP 258) is a must-read for any
Docutils developer.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-04-12 15:11:29
|
Revision: 9342
http://sourceforge.net/p/docutils/code/9342
Author: milde
Date: 2023-04-12 15:11:26 +0000 (Wed, 12 Apr 2023)
Log Message:
-----------
Add "auto_encode" argument to `core.publish_from_doctree()`.
publish_from_doctree() output is described as "string" and uses
`io.StringOutput` just as publish_string().
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/docutils/core.py
trunk/docutils/test/test_publisher.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2023-04-11 22:22:50 UTC (rev 9341)
+++ trunk/docutils/HISTORY.txt 2023-04-12 15:11:26 UTC (rev 9342)
@@ -23,8 +23,8 @@
* docutils/core.py
- - New argument "auto_encode" for `publish_string()` and
- `publish_programmatically()`.
+ - New argument "auto_encode" for `publish_string()`,
+ `publish_from_docstring()` and `publish_programmatically()`.
- New functions `rst2…()` for use as "console_scripts" `entry point`_.
* docutils/frontend.py
Modified: trunk/docutils/docutils/core.py
===================================================================
--- trunk/docutils/docutils/core.py 2023-04-11 22:22:50 UTC (rev 9341)
+++ trunk/docutils/docutils/core.py 2023-04-12 15:11:26 UTC (rev 9342)
@@ -383,8 +383,8 @@
usage=default_usage, description=default_description):
"""
Set up & run a `Publisher` for command-line-based file I/O (input and
- output file paths taken automatically from the command line). Return the
- encoded string output also.
+ output file paths taken automatically from the command line).
+ Also return the encoded output as `bytes`.
Parameters: see `publish_programmatically()` for the remainder.
@@ -411,7 +411,7 @@
config_section=None, enable_exit_status=False):
"""
Set up & run a `Publisher` for programmatic use with file-like I/O.
- Return the encoded string output also.
+ Also return the encoded output as `bytes`.
Parameters: see `publish_programmatically()`.
"""
@@ -542,25 +542,19 @@
writer=None, writer_name='pseudoxml',
settings=None, settings_spec=None,
settings_overrides=None, config_section=None,
- enable_exit_status=False):
+ enable_exit_status=False,
+ auto_encode=True):
"""
Set up & run a `Publisher` to render from an existing document
- tree data structure, for programmatic use with string I/O. Return
- the encoded string output.
+ tree data structure, for programmatic use with string output
+ (`bytes` or `str`, cf. `publish_string()`).
- Note that document.settings is overridden; if you want to use the settings
- of the original `document`, pass settings=document.settings.
+ Note that ``document.settings`` is overridden; if you want to use the
+ settings of the original `document`, pass ``settings=document.settings``.
- Also, new document.transformer and document.reporter objects are
+ Also, new `document.transformer` and `document.reporter` objects are
generated.
- For encoded string output, be sure to set the 'output_encoding' setting to
- the desired encoding. Set it to 'unicode' for unencoded Unicode string
- output. Here's one way::
-
- publish_from_doctree(
- ..., settings_overrides={'output_encoding': 'unicode'})
-
Parameters: `document` is a `docutils.nodes.document` object, an existing
document tree.
@@ -576,6 +570,7 @@
publisher.process_programmatic_settings(
settings_spec, settings_overrides, config_section)
publisher.set_destination(None, destination_path)
+ publisher.destination.auto_encode = auto_encode
return publisher.publish(enable_exit_status=enable_exit_status)
@@ -594,8 +589,8 @@
destination_class=io.BinaryFileOutput):
"""
Set up & run a `Publisher` for command-line-based file I/O (input and
- output file paths taken automatically from the command line). Return the
- encoded string output also.
+ output file paths taken automatically from the command line).
+ Also return the encoded output as `bytes`.
This is just like publish_cmdline, except that it uses
io.BinaryFileOutput instead of io.FileOutput.
@@ -720,7 +715,9 @@
* `auto_encode`: Boolean; encode string output and return `bytes`?
Ignored with `io.FileOutput`.
- The default value will change to ``False`` in Docutils 0.22.
+ New in Docutils 0.21.
+ The default value will change to ``False`` in Docutils 0.22 or later.
+ The argument may be removed in Docutils 2.0 or later.
"""
publisher = Publisher(reader, parser, writer, settings=settings,
source_class=source_class,
Modified: trunk/docutils/test/test_publisher.py
===================================================================
--- trunk/docutils/test/test_publisher.py 2023-04-11 22:22:50 UTC (rev 9341)
+++ trunk/docutils/test/test_publisher.py 2023-04-12 15:11:26 UTC (rev 9342)
@@ -111,8 +111,9 @@
' <paragraph>\n'
' test → me\n')
output = core.publish_string(source.encode('utf-16'),
- settings_overrides=settings)
- self.assertEqual(output.decode('utf-8'), expected)
+ settings_overrides=settings,
+ auto_encode=False)
+ self.assertEqual(output, expected)
# encoding declaration in source
source = '.. encoding: latin1\n\nGrüße'
@@ -119,7 +120,8 @@
# don't encode output (return `str`)
settings['output_encoding'] = 'unicode'
output = core.publish_string(source.encode('utf-16'),
- settings_overrides=settings)
+ settings_overrides=settings,
+ auto_encode=False)
self.assertTrue(output.endswith('Grüße\n'))
def test_publish_string_output_encoding(self):
@@ -132,13 +134,13 @@
' <paragraph>\n'
' Grüß → dich\n')
# current default: encode output, return `bytes`
- output = core.publish_string(source, settings_overrides=settings)
+ output = bytes(core.publish_string(source, settings_overrides=settings))
self.assertEqual(output, expected.encode('latin1', 'replace'))
# no encoding if `auto_encode` is False:
output = core.publish_string(source, settings_overrides=settings,
auto_encode=False)
self.assertEqual(output, expected)
- # self.assertEqual(output.encoding, 'latin1')
+ self.assertEqual(output.encoding, 'latin1')
class PublishDoctreeTestCase(unittest.TestCase, docutils.SettingsSpec):
@@ -219,9 +221,10 @@
self.assertTrue(isinstance(doctree_zombie, nodes.document))
# Write out the document:
- output = core.publish_from_doctree(
- doctree_zombie, writer_name='pseudoxml',
- settings_spec=self).decode('utf-8')
+ output = core.publish_from_doctree(doctree_zombie,
+ writer_name='pseudoxml',
+ settings_spec=self,
+ auto_encode=False)
self.assertEqual(output, pseudoxml_output)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-04-12 15:11:41
|
Revision: 9343
http://sourceforge.net/p/docutils/code/9343
Author: milde
Date: 2023-04-12 15:11:38 +0000 (Wed, 12 Apr 2023)
Log Message:
-----------
Update Publisher API documentation. Add links.
Modified Paths:
--------------
trunk/docutils/docs/api/publisher.txt
trunk/docutils/docutils/core.py
Modified: trunk/docutils/docs/api/publisher.txt
===================================================================
--- trunk/docutils/docs/api/publisher.txt 2023-04-12 15:11:26 UTC (rev 9342)
+++ trunk/docutils/docs/api/publisher.txt 2023-04-12 15:11:38 UTC (rev 9343)
@@ -16,34 +16,39 @@
The ``docutils.core.Publisher`` class is the core of Docutils,
managing all the processing and relationships between components. See
`PEP 258`_ for an overview of Docutils components.
+Configuration_ is done via `runtime settings`_ assembled from several sources.
-The ``docutils.core.publish_*()`` convenience functions are the normal
-entry points for using Docutils as a library.
+The `Publisher convenience functions`_ are the normal entry points for
+using Docutils as a library.
-See `Inside A Docutils Command-Line Front-End Tool`_ for an overview
-of a typical Docutils front-end tool, including how the Publisher
-class is used.
-
.. _PEP 258: ../peps/pep-0258.html
-.. _Inside A Docutils Command-Line Front-End Tool: ../howto/cmdline-tool.html
Publisher Convenience Functions
===============================
+There are several convenience functions in the ``docutils.core`` module.
Each of these functions sets up a `docutils.core.Publisher` object,
then calls its ``publish()`` method. ``docutils.core.Publisher.publish()``
-handles everything else. There are several convenience functions in
-the ``docutils.core`` module:
+handles everything else.
+See the module docstring, ``help(docutils.core)``, and the function
+docstrings, e.g., ``help(docutils.core.publish_string)``, for details and
+a description of the function arguments.
+.. TODO: generate API documentation with Sphinx and add links to it.
+
+
publish_cmdline()
-----------------
-Function for command-line front-end tools, like ``rst2html.py``. There are
-several examples in the ``tools/`` directory. A detailed analysis of one
-such tool is in `Inside A Docutils Command-Line Front-End Tool`_.
+Function for command-line front-end tools, like ``rst2html.py`` with
+file I/O. Also returns the output as `bytes` instance.
+There are several examples in the ``tools/`` directory of the Docutils
+repository. A detailed analysis of one such tool is in `Inside A Docutils
+Command-Line Front-End Tool`_.
+
.. _Inside A Docutils Command-Line Front-End Tool: ../howto/cmdline-tool.html
@@ -72,13 +77,14 @@
``"unicode"``.
* a `bytes` instance, if the "encode_output" argument is ``True`` and
- output_encoding_ is set to an encoding registerd with
+ output_encoding_ is set to an encoding registered with
Python's "codecs_" module (default: "utf-8").
- Calling ``output = bytes(publish_string(…))`` ensures that
- ``output`` is a `bytes` instance encoded with output_encoding_.
+ Calling ``output = bytes(publish_string(…))`` ensures that ``output``
+ is a `bytes` instance encoded with the configured output_encoding_
+ (matching the encoding indicated inside HTML, XML, and LaTeX documents).
-.. [#] Actually an instance of a `str` sub-class with the
+.. [#] More precisely, an instance of a `str` sub-class with the
output_encoding_ and output_encoding_error_handler_ configuration
settings stored as "encoding" and "errors" attributes.
@@ -92,13 +98,11 @@
structure (doctree). The doctree can be modified, pickled & unpickled,
etc., and then reprocessed with `publish_from_doctree()`_.
-.. _Docutils document tree: ../ref/doctree.html
-
publish_from_doctree()
----------------------
-Render from an existing document tree data structure (doctree).
+Render from an existing `document tree`_ data structure (doctree).
Returns the output document as a memory object (cf. `string I/O`_).
@@ -105,12 +109,14 @@
publish_programmatically()
--------------------------
-This function implements common code and is used by `publish_file()`_,
-`publish_string()`_, and `publish_parts()`_.
+Auxilliary function used by `publish_file()`_, `publish_string()`_,
+`publish_doctree()`_, and `publish_parts()`_.
It returns a 2-tuple: the output document as memory object (cf. `string
I/O`_) and the Publisher object.
+.. _publish-parts-details:
+
publish_parts()
---------------
@@ -380,6 +386,20 @@
Configuration
=============
+Docutils is configured by runtime settings assembled from several
+sources:
+
+* *settings specifications* of the selected components (reader, parser,
+ writer),
+* *configuration files* (if enabled), and
+* *command-line options* (if enabled).
+
+The individual settings are described in `Docutils Configuration`_.
+
+Docutils overlays default and explicitly specified values from these
+sources such that settings behave the way we want and expect them to
+behave. For details, see `Docutils Runtime Settings`_.
+
To pass application-specific setting defaults to the Publisher
convenience functions, use the ``settings_overrides`` parameter. Pass
a dictionary of setting names & values, like this::
@@ -389,12 +409,10 @@
output = publish_string(..., settings_overrides=overrides)
Settings from command-line options override configuration file
-settings, and they override application defaults. For details, see
-`Docutils Runtime Settings`_. See `Docutils Configuration`_ for
-details about individual settings.
+settings, and they override application defaults.
-.. _Docutils Runtime Settings: ./runtime-settings.html
-.. _Docutils Configuration: ../user/config.html
+Further customization is possible creating custom component
+objects and passing *them* to ``publish_*()`` or the ``Publisher``.
Encodings
@@ -456,6 +474,8 @@
This feature is scheduled to be removed in Docutils 1.0.
See the `inspecting_codecs`_ package for a possible replacement.
+
+.. _Inside A Docutils Command-Line Front-End Tool: ../howto/cmdline-tool.html
.. _RELEASE-NOTES: ../../RELEASE-NOTES.html#future-changes
.. _input_encoding: ../user/config.html#input-encoding
.. _preferred encoding:
@@ -468,4 +488,9 @@
../ref/rst/restructuredtext.html#auto-symbol-footnotes
.. _"contents" directive:
../ref/rst/directives.html#table-of-contents
+.. _document tree:
+.. _Docutils document tree: ../ref/doctree.html
+.. _runtime settings:
+.. _Docutils Runtime Settings: ./runtime-settings.html
+.. _Docutils Configuration: ../user/config.html
.. _inspecting_codecs: https://codeberg.org/milde/inspecting-codecs
Modified: trunk/docutils/docutils/core.py
===================================================================
--- trunk/docutils/docutils/core.py 2023-04-12 15:11:26 UTC (rev 9342)
+++ trunk/docutils/docutils/core.py 2023-04-12 15:11:38 UTC (rev 9343)
@@ -483,7 +483,7 @@
settings_overrides=None, config_section=None,
enable_exit_status=False):
"""
- Set up & run a `Publisher`, and return a dictionary of `document parts`_.
+ Set up & run a `Publisher`, and return a dictionary of document parts.
Dictionary keys are the names of parts.
Dictionary values are `str` instances; encoding is up to the client,
@@ -492,11 +492,11 @@
parts = publish_parts(...)
body = parts['body'].encode(parts['encoding'])
+ See the `API documentation`__ for details on the provided parts.
+
Parameters: see `publish_programmatically()`.
- .. _document parts:
- https://docutils.sourceforge.io/docs/api/publisher.html
- #publish-parts-details
+ __ https://docutils.sourceforge.io/docs/api/publisher.html#publish-parts
"""
output, publisher = publish_programmatically(
source=source, source_path=source_path, source_class=source_class,
@@ -545,8 +545,8 @@
enable_exit_status=False,
auto_encode=True):
"""
- Set up & run a `Publisher` to render from an existing document
- tree data structure, for programmatic use with string output
+ Set up & run a `Publisher` to render from an existing document tree
+ data structure. For programmatic use with string output
(`bytes` or `str`, cf. `publish_string()`).
Note that ``document.settings`` is overridden; if you want to use the
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-04-13 14:27:25
|
Revision: 9345
http://sourceforge.net/p/docutils/code/9345
Author: milde
Date: 2023-04-13 14:27:23 +0000 (Thu, 13 Apr 2023)
Log Message:
-----------
Do not decode OpenDocument zip packages with `publish_string()`.
The ODF writer produces output in binary format.
Raise an exception if `publish_string()` is called with
this writer and ``auto_encode=False``.
Update documentation, add cross-links.
TODO:
In future, the ODF writer may return a "flat XML" version of the
"OpenDocument Text" document as `str`.
Modified Paths:
--------------
trunk/docutils/docs/user/config.txt
trunk/docutils/docs/user/odt.txt
trunk/docutils/docutils/core.py
trunk/docutils/test/test_publisher.py
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2023-04-12 16:52:19 UTC (rev 9344)
+++ trunk/docutils/docs/user/config.txt 2023-04-13 14:27:23 UTC (rev 9345)
@@ -444,8 +444,10 @@
(e.g. an encoding declaration in HTML or XML or the representation of
characters as LaTeX macro vs. literal character).
-Default: "utf-8". Options: ``--output-encoding, -o``.
+This setting is ignored by the `ODF/ODT Writer`_
+Default: "utf-8". Options: ``--output-encoding``.
+
output_encoding_error_handler
-----------------------------
@@ -1999,11 +2001,22 @@
__ `template [latex writers]`_
+.. _ODF/ODT Writer:
+
[odf_odt writer]
----------------
-The following command line options are specific to ``odtwriter``:
+The `ODF/ODT Writer`__ generates documents in the
+OpenDocument_ Text format (.odt).
+The output_encoding_ setting is ignored, the output encoding is
+always "UTF-8".
+
+__
+.. _ODT Writer for Docutils: odt.html
+.. _OpenDocument: https://en.wikipedia.org/wiki/OpenDocument
+
+
stylesheet
~~~~~~~~~~
@@ -2029,6 +2042,7 @@
no-cloak-email-addresses
~~~~~~~~~~~~~~~~~~~~~~~~
+
Do not obfuscate email addresses.
table-border-thickness
@@ -2060,6 +2074,7 @@
create-links
~~~~~~~~~~~~
+
Create links.
no-links
@@ -2111,9 +2126,7 @@
time, etc" in the `Odt Writer for Docutils`_ document for
details.
-.. _Odt Writer for Docutils: odt.html
-
[pseudoxml writer]
------------------
Modified: trunk/docutils/docs/user/odt.txt
===================================================================
--- trunk/docutils/docs/user/odt.txt 2023-04-12 16:52:19 UTC (rev 9344)
+++ trunk/docutils/docs/user/odt.txt 2023-04-13 14:27:23 UTC (rev 9345)
@@ -1,7 +1,7 @@
.. include:: ../header.txt
=======================
-Odt Writer for Docutils
+ODT Writer for Docutils
=======================
:Author: Dave Kuhlman
@@ -10,8 +10,8 @@
:Date: $Date$
:Copyright: This document has been placed in the public domain.
-:abstract: This document describes the Docutils odtwriter
- (rst2odt.py).
+:abstract: This document describes the Docutils writer for
+ OpenDocument Text (.odt) documents.
.. sectnum::
@@ -21,21 +21,14 @@
Introduction
============
-What it does -- ``rst2odt.py`` translates reST
-(reStructuredText) into a Open Document Format ``.odt`` file. You
-can learn more about the ODF format here:
+The Docutils front end rst2odt.py_ translates reStructuredText_ into an
+`OpenDocument Text`_ (.odt) file.
+OpenDocument files `can be opened by most modern office software`__.
+It is the native file format for LibreOffice_ Writer.
-- `OASIS Open Document Format for Office Applications
- (OpenDocument) TC`_
+__ https://en.wikipedia.org/wiki/OpenDocument#Software
-- `Open Document at Wikipedia`_
-You should be able to open documents (.odt files) generated with
-``rst2odt.py`` in ``OpenOffice/oowriter``.
-
-You can learn more about Docutils and reST here: `Docutils`_
-
-
Requirements
============
@@ -57,7 +50,7 @@
Run it from the command line as follows::
- $ rst2odt.py myinput.txt myoutput.odt
+ $ rst2odt.py myinput.txt > myoutput.odt
To see usage information and to learn about command line options
that you can use, run the following::
@@ -66,27 +59,31 @@
Examples::
- $ rst2odt.py -s -g python_comments.txt python_comments.odt
+ $ rst2odt.py -s -g python_comments.txt > python_comments.odt
$ rst2odt.py --source-url=odtwriter.txt --generator \
- --stylesheet=/myconfigs/styles.odt odtwriter.txt odtwriter.odt
+ --stylesheet=/myconfigs/styles.odt odtwriter.txt > odtwriter.odt
Configuration file
------------------
-The options described below can also be set in a configuration file.
-Use section ``[odf_odt writer]`` to set options specific to the
+The options described below can also be set in a `configuration file`_.
+Use section `[odf_odt writer]`_ to set options specific to the
``odtwriter``. For example::
[odf_odt writer]
stylesheet: styles1.odt
-See the "Docutils Configuration" document for more information on
+See the `Docutils Configuration`_ document for more information on
Docutils configuration files, including locations which are
searched.
+.. _Docutils Configuration: config.html
+.. _configuration file: config.html#configuration-files
+.. _[odf_odt writer]: config.html#odf-odt-writer
+
Command line options
--------------------
@@ -1185,18 +1182,15 @@
-
+.. _rst2odt.py:
+ tools.html#rst2odt-py
+.. _reStructuredText:
+ ../ref/rst/restructuredtext.html
+.. _`OpenDocument Text`:
+ https://en.wikipedia.org/wiki/OpenDocument
+.. _LibreOffice:
+ https://libreoffice.org/
.. _`Pygments`:
https://pygments.org/
-
-.. _`Docutils`:
- https://docutils.sourceforge.io/
-
.. _`Python Imaging Library`:
https://en.wikipedia.org/wiki/Python_Imaging_Library
-
-.. _`Open Document at Wikipedia`:
- https://en.wikipedia.org/wiki/OpenDocument
-
-.. _`OASIS Open Document Format for Office Applications (OpenDocument) TC`:
- http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office
Modified: trunk/docutils/docutils/core.py
===================================================================
--- trunk/docutils/docutils/core.py 2023-04-12 16:52:19 UTC (rev 9344)
+++ trunk/docutils/docutils/core.py 2023-04-13 14:27:23 UTC (rev 9345)
@@ -23,6 +23,7 @@
from docutils import (__version__, __version_details__, SettingsSpec,
io, utils, readers, writers)
+import docutils.writers.odf_odt # noqa:F401
from docutils.frontend import OptionParser
from docutils.readers import doctree
@@ -203,7 +204,8 @@
or self.settings._destination)
self.settings._destination = destination_path
self.destination = self.destination_class(
- destination=destination, destination_path=destination_path,
+ destination=destination,
+ destination_path=destination_path,
encoding=self.settings.output_encoding,
error_handler=self.settings.output_encoding_error_handler)
@@ -723,11 +725,15 @@
source_class=source_class,
destination_class=destination_class)
publisher.set_components(reader_name, parser_name, writer_name)
+ if isinstance(publisher.writer,
+ writers.odf_odt.Writer) and not auto_encode:
+ raise ValueError('The ODT writer generates binary output and cannot '
+ 'be used with `auto_encode=False`')
publisher.process_programmatic_settings(
settings_spec, settings_overrides, config_section)
publisher.set_source(source, source_path)
publisher.set_destination(destination, destination_path)
- if not auto_encode and isinstance(publisher.destination, io.StringOutput):
+ if isinstance(publisher.destination, io.StringOutput):
publisher.destination.auto_encode = auto_encode
output = publisher.publish(enable_exit_status=enable_exit_status)
return output, publisher
Modified: trunk/docutils/test/test_publisher.py
===================================================================
--- trunk/docutils/test/test_publisher.py 2023-04-12 16:52:19 UTC (rev 9344)
+++ trunk/docutils/test/test_publisher.py 2023-04-13 14:27:23 UTC (rev 9345)
@@ -64,6 +64,9 @@
class PublisherTests(unittest.TestCase):
+ settings = {'_disable_config': True,
+ 'datestamp': False}
+
def test_input_error_handling(self):
# core.publish_cmdline(argv=['nonexisting/path'])
# exits with a short message, if `traceback` is False,
@@ -104,8 +107,7 @@
# Transparently decode `bytes` source (with "input_encoding" setting)
# default: auto-detect, fallback utf-8
# Output is encoded according to "output_encoding" setting.
- settings = {'_disable_config': True,
- 'datestamp': False}
+ settings = dict(self.settings)
source = 'test → me'
expected = ('<document source="<string>">\n'
' <paragraph>\n'
@@ -125,16 +127,16 @@
self.assertTrue(output.endswith('Grüße\n'))
def test_publish_string_output_encoding(self):
- settings = {'_disable_config': True,
- 'datestamp': False,
- 'output_encoding': 'latin1',
- 'output_encoding_error_handler': 'replace'}
+ settings = dict(self.settings)
+ settings['output_encoding'] = 'latin1'
+ settings['output_encoding_error_handler'] = 'replace'
source = 'Grüß → dich'
expected = ('<document source="<string>">\n'
' <paragraph>\n'
' Grüß → dich\n')
# current default: encode output, return `bytes`
- output = bytes(core.publish_string(source, settings_overrides=settings))
+ output = bytes(core.publish_string(source,
+ settings_overrides=settings))
self.assertEqual(output, expected.encode('latin1', 'replace'))
# no encoding if `auto_encode` is False:
output = core.publish_string(source, settings_overrides=settings,
@@ -142,7 +144,18 @@
self.assertEqual(output, expected)
self.assertEqual(output.encoding, 'latin1')
+ def test_publish_string_output_encoding_odt(self):
+ """The ODT writer generates a zip archive, not a `str`.
+ TODO: return `str` with document as "flat XML" (.fodt).
+ """
+ with self.assertRaises(ValueError) as cm:
+ core.publish_string('test',
+ writer_name='odt',
+ auto_encode=False)
+ self.assertIn('ODT writer generates binary output', str(cm.exception))
+
+
class PublishDoctreeTestCase(unittest.TestCase, docutils.SettingsSpec):
settings_default_overrides = {
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <gr...@us...> - 2023-04-13 18:48:31
|
Revision: 9346
http://sourceforge.net/p/docutils/code/9346
Author: grubert
Date: 2023-04-13 18:48:20 +0000 (Thu, 13 Apr 2023)
Log Message:
-----------
Fix regex to match multiline message "requires ... recommonmark"
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/test/test_parsers/test_get_parser_class.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2023-04-13 14:27:23 UTC (rev 9345)
+++ trunk/docutils/HISTORY.txt 2023-04-13 18:48:20 UTC (rev 9346)
@@ -147,6 +147,10 @@
.. _coverage.py: https://pypi.org/project/coverage/
+* test/test_parsers/test_get_parser_class.py
+
+ - Fix regex to match multiline message "requires ... recommonmark"
+
* tools/
- Moved ``quicktest.py`` to ``tools/dev/``.
Modified: trunk/docutils/test/test_parsers/test_get_parser_class.py
===================================================================
--- trunk/docutils/test/test_parsers/test_get_parser_class.py 2023-04-13 14:27:23 UTC (rev 9345)
+++ trunk/docutils/test/test_parsers/test_get_parser_class.py 2023-04-13 18:48:20 UTC (rev 9346)
@@ -48,8 +48,9 @@
class RecommonmarkMissingTests(unittest.TestCase):
def test_missing_parser_message(self):
+ # match multiline message (?s) = re.DOTALL "." also matches newline
with self.assertRaisesRegex(ImportError,
- 'requires the.*package .* recommonmark'):
+ '(?s)requires the.*package .*recommonmark'):
publish_string('test data', parser_name='recommonmark')
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-04-14 00:11:59
|
Revision: 9347
http://sourceforge.net/p/docutils/code/9347
Author: milde
Date: 2023-04-14 00:11:56 +0000 (Fri, 14 Apr 2023)
Log Message:
-----------
Announce change of "math-output" setting default for HTML5 to "MathML".
MathML is supported by Chrome since January 2023.
Use MathML in documentation pages generated with the HTML5 writer already now.
Update "LaTeX syntax for mathematics" documentation.
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/ref/rst/mathematics.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docutils.conf
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2023-04-13 18:48:20 UTC (rev 9346)
+++ trunk/docutils/RELEASE-NOTES.txt 2023-04-14 00:11:56 UTC (rev 9347)
@@ -120,6 +120,8 @@
- Remove option ``--embed-images`` (obsoleted by "image_loading_")
in Docutils 2.0.
+ - Change the default value for math_output_ to "MathML" in Docutils 0.22.
+
* "latex2e" writer:
- Change default of use_latex_citations_ setting to True
@@ -160,6 +162,7 @@
.. _front end tools: docs/user/tools.html
.. _input encoding:
.. _input_encoding: docs/user/config.html#input-encoding
+.. _math_output: docs/user/config.html#math-output
.. _UTF-8 mode: https://docs.python.org/3/library/os.html#utf8-mode
.. _image_loading: docs/user/config.html#image-loading
.. _old-format configuration files:
Modified: trunk/docutils/docs/ref/rst/mathematics.txt
===================================================================
--- trunk/docutils/docs/ref/rst/mathematics.txt 2023-04-13 18:48:20 UTC (rev 9346)
+++ trunk/docutils/docs/ref/rst/mathematics.txt 2023-04-14 00:11:56 UTC (rev 9347)
@@ -216,10 +216,8 @@
The use of ``|`` and ``\|`` for pairs of vertical bars may produce
incorrect spacing, e.g., ``|k|=|-k|`` produces `|k| = |−k|` and
``|\sin(x)|`` produces `|\sin(x)|`. The pairing delimiters, e.g.
-`\lvert -k\rvert` and `\lvert\sin(x)\rvert`, prevent this problem
-(in LaTeX and MathJax).
+`\lvert -k\rvert` and `\lvert\sin(x)\rvert`, prevent this problem.
-.. TODO: fix spacing before unary minus (see also cases example below).
Extensible vertical arrows
--------------------------
@@ -635,7 +633,7 @@
.. class:: colwidths-auto
- ====================== ======== ===================== ==================
+ ====================== ======== ===================== ===================
:m:`3\qquad 4` ``3\qquad 4`` = 2em
:m:`3\quad 4` ``3\quad 4`` = 1em
:m:`3~4` ``3~4`` ``3\nobreakspace 4``
@@ -644,18 +642,17 @@
:m:`3\:4` ``3\:4`` ``3\medspace 4``
:m:`3\,4` ``3\,4`` ``3\thinspace 4``
:m:`3 4` ``3 4`` regular space [#]_
- :m:`3\!4` ``3\!4`` ``3\negthinspace 4``
+ :m:`3\!4` ``3\!4`` ``3\negthinspace 4`` negative space [#]_
:m:`3\negmedspace 4` ``3\negmedspace 4``
:m:`3\negthickspace 4` ``3\negthickspace 4``
`3\hspace{1ex}4` ``3\hspace{1ex}4`` custom length
`3\mspace{20mu}4` ``3\mspace{20mu}4`` custom length [#]_
- ====================== ======== ===================== ==================
+ ====================== ======== ===================== ===================
.. [#] Whitespace characters are ignored in LaTeX math mode.
-.. [#] In LaTeX, unit must be 'mu' (1 mu = 1/18em).
+.. [#] Negative spacing does not work with MathML (last tested in Firefox 102).
+.. [#] In LaTeX, the unit must be 'mu' (1 mu = 1/18em).
-Negative spacing does not work with MathML (in Firefox 78).
-
There are also three commands that leave a space equal to the height and
width of its argument. For example ``\phantom{XXX}`` results in space as
wide and high as three X’s:
@@ -751,14 +748,16 @@
2 + \frac{7^2}{2 + \cdots}
}}}
-It supports the optional argument ``[l]`` or ``[r]`` for
-left or right placement of the numerator:
+The optional argument ``[l]`` or ``[r]`` for left or right placement of
+the numerator is `not supported by MathML Core`__:
.. math:: \cfrac[l]{x}{x-1} \quad
\cfrac{x}{x-1} \quad
\cfrac[r]{x}{x-1}
+__ https://github.com/w3c/mathml/issues/30
+
Delimiter sizes
===============
@@ -934,9 +933,12 @@
:mathcal: `\mathcal{abs(x) \pm \alpha \approx 3 \Gamma \quad \forall x \in R}`
:mathscr: `\mathscr{abs(x) \pm \alpha \approx 3 \Gamma \quad \forall x \in R}`
-Unicode supports the following blackboard-bold characters:
-`\mathbb{a \ldots z A \ldots Z 0 \ldots 9
-\mathbb\Gamma \mathbb{\Pi} \mathbb {\Sigma} \mathbb\gamma \mathbb\pi}`.
+Without additional packages, LaTeX supports "blackboard-bold" only for
+capital Latin letters.
+Unicode supports also small Latin letters, some Greek letters, and digits:
+`\mathbb{A \ldots Z a \ldots z}
+\mathbb\Gamma \mathbb{\Pi} \mathbb {\Sigma} \mathbb\gamma \mathbb \pi
+\mathbb{0 \ldots 9}`.
Inferred <mrow>s in MathML
@@ -956,7 +958,7 @@
Scripts and Limits
~~~~~~~~~~~~~~~~~~
-Accents should be nearer to the base (in MathML Firefox 78, it's vice versa!):
+Accents should be nearer to the base:
`\bar a \overline a, \bar l \overline l, \bar i \overline i`,
`\vec{r}` `\overrightarrow{r}`.
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2023-04-13 18:48:20 UTC (rev 9346)
+++ trunk/docutils/docs/user/config.txt 2023-04-14 00:11:56 UTC (rev 9347)
@@ -1091,6 +1091,40 @@
stylesheet(s) will only be referenced or embedded if required
(i.e. if there is mathematical content in the document).
+:MathML:
+ Embed math content as presentational MathML_.
+
+ Self-contained documents (no JavaScript, no external downloads).
+ MathML is part of the HTML5 standard [#mathml-in-html4]_ and
+ `supported by all major browsers`__ (since January 2023 also by Chrome).
+
+ .. [#mathml-in-html4]
+ With the "html4css1" writer, the resulting HTML document does
+ not validate, as there is no DTD for `MathML + XHTML Transitional`.
+ However, MathML-enabled browsers will render it fine.
+
+ Docutil's latex2mathml converter supports a considerable
+ `subset of LaTeX math syntax`__.
+
+ An external converter can be appended after whitespace, e.g.,
+ ``--math-output="MathML blahtexml"``:
+
+ blahtexml_
+ Fast conversion, support for many symbols and environments, but no
+ "align" (or other equation-aligning) environment. (C++)
+
+ LaTeXML_
+ Comprehensive macro support but *very* slow. (Perl)
+
+ TtM_
+ No "matrix", "align" and "cases" environments. Support may be removed.
+
+ Pandoc_
+ Comprehensive macro support, fast, but a large install size. (Haskell)
+
+ __ https://developer.mozilla.org/en-US/docs/Web/MathML#browser_compatibility
+ __ ../ref/rst/mathematics.html
+
:MathJax:
Format math for display with MathJax_, a JavaScript-based math rendering
engine.
@@ -1140,45 +1174,6 @@
This is the fallback if no URL is specified.
-:MathML:
- Embed math content as presentational MathML_.
-
- Pro:
- The W3C recommendation for math on the web.
-
- Self-contained documents (no JavaScript, no external downloads).
-
- Con:
- Limited `browser support`__.
-
- Docutil's latex2mathml converter supports only a
- `subset of LaTeX math syntax`__.
-
- With the "html4css1" writer, the resulting HTML document does
- not validate, as there is no DTD for `MathML + XHTML Transitional`.
- However, MathML-enabled browsers will render it fine.
-
- __ https://developer.mozilla.org/en-US/docs/Web/MathML
- #browser_compatibility
- __ ../ref/rst/mathematics.html
-
-
- An external converter can be appended after whitespace, e.g.,
- ``--math-output="MathML latexml"``:
-
- blahtexml_
- Fast conversion, support for many symbols and environments, but no
- "align" (or other equation-aligning) environment. (C++)
-
- LaTeXML_
- Comprehensive macro support but *very* slow. (Perl)
-
- TtM_
- No "matrix", "align" and "cases" environments. Support may be removed.
-
- Pandoc_
- Comprehensive macro support, fast, but a large install size. (Haskell)
-
:LaTeX:
Include literal LaTeX code.
@@ -1186,7 +1181,9 @@
Default: HTML math.css. Option: ``--math-output``.
-New in Docutils 0.8.
+| New in Docutils 0.8.
+| The default for the HTML5 writer will change to
+ "MathML" in Docutils 0.22.
.. _math directive: ../ref/rst/directives.html#math
.. _MathJax: http://www.mathjax.org/
Modified: trunk/docutils/docutils.conf
===================================================================
--- trunk/docutils/docutils.conf 2023-04-13 18:48:20 UTC (rev 9346)
+++ trunk/docutils/docutils.conf 2023-04-14 00:11:56 UTC (rev 9347)
@@ -13,6 +13,8 @@
field-name-limit: 20
[html5 writer]
+math-output: MathML
+# MathML will become the default for HTML5 in Docutils 0.22
stylesheet-dirs: docutils/writers/html5_polyglot/
stylesheet-path: minimal.css, responsive.css
section-self-link: yes
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2023-04-14 00:12:09
|
Revision: 9348
http://sourceforge.net/p/docutils/code/9348
Author: milde
Date: 2023-04-14 00:12:07 +0000 (Fri, 14 Apr 2023)
Log Message:
-----------
Fix test for spurious enumerated lists in bibliographic fields.
The test for "single line paragraphs" failed for bibliographic fields followed
by an empty line.
Modified Paths:
--------------
trunk/docutils/docutils/transforms/frontmatter.py
trunk/docutils/test/test_transforms/test_docinfo.py
Modified: trunk/docutils/docutils/transforms/frontmatter.py
===================================================================
--- trunk/docutils/docutils/transforms/frontmatter.py 2023-04-14 00:11:56 UTC (rev 9347)
+++ trunk/docutils/docutils/transforms/frontmatter.py 2023-04-14 00:12:07 UTC (rev 9348)
@@ -466,7 +466,7 @@
# enumerated list
# https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists
if (isinstance(f_body[0], nodes.enumerated_list)
- and '\n' not in f_body.rawsource):
+ and '\n' not in f_body.rawsource.strip()):
# parse into a dummy document and use created nodes
_document = utils.new_document('*DocInfo transform*',
field.document.settings)
@@ -517,7 +517,8 @@
'it must contain either a single paragraph (with authors '
'separated by one of "%s"), multiple paragraphs (one per '
'author), or a bullet list with one paragraph (one author) '
- 'per item.'
+ 'per item. Remember that leading initials can cause '
+ '(mis)recognizing names as enumerated lists.'
% (name, ''.join(self.language.author_separators)),
base_node=field)
raise
Modified: trunk/docutils/test/test_transforms/test_docinfo.py
===================================================================
--- trunk/docutils/test/test_transforms/test_docinfo.py 2023-04-14 00:11:56 UTC (rev 9347)
+++ trunk/docutils/test/test_transforms/test_docinfo.py 2023-04-14 00:12:07 UTC (rev 9348)
@@ -75,8 +75,11 @@
It is automatically moved to the end of the other bibliographic elements.
:Author: E. *Xample*
+
:Version: 1
+
:Date: 2001-08-11
+
:Parameter i: integer
""",
"""\
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
Thanks for helping keep SourceForge clean.
X