Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[8853] trunk/docutils
|
From: <mi...@us...> - 2021-10-13 15:42:33
|
Revision: 8853
http://sourceforge.net/p/docutils/code/8853
Author: milde
Date: 2021-10-13 15:42:30 +0000 (Wed, 13 Oct 2021)
Log Message:
-----------
New option "image_loading" for HTML5.
With values "embed", "eager", "lazy", cf, feature-request #78.
Obsoletes "embed_image".
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docutils/writers/_html_base.py
trunk/docutils/docutils/writers/html5_polyglot/__init__.py
trunk/docutils/test/test_writers/test_html5_polyglot_parts.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2021-10-12 22:16:43 UTC (rev 8852)
+++ trunk/docutils/HISTORY.txt 2021-10-13 15:42:30 UTC (rev 8853)
@@ -18,7 +18,7 @@
* docutils/nodes.py
- - Don't change a list while looping over it (in
+ - Don't change a list while looping over it (in
document.set_name_id_map()). Thanks to Mickey Endito.
* docutils/parsers/rst/directives/misc.py
@@ -28,10 +28,15 @@
to keep a log of recursive inclusions.
* docutils/parsers/rst/states.py
-
+
- Use a "magic" comment to update the log of recursive inclusions.
+* docutils/writers/html5_polyglot/__init__.py
+ - New option "image_loading". Support "lazy" loading of images.
+ Obsoletes "embed_images".
+
+
Release 0.18b1 (2021-10-05)
===========================
@@ -253,7 +258,7 @@
- Apply patch #165 "Fix error when copying `system_message` node"
by Takeshi KOMIYA.
- Apply version of patch #167 "Let document.set_id() register all
- existing IDs" (thanks to Takeshi KOMIYA).
+ existing IDs". Thanks to Takeshi KOMIYA.
- Fix bug #410: Use a "property" function to recursively fetch
`Node.document` value from parent node.
@@ -306,7 +311,7 @@
__ https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article
- Use HTML text-level tags <small>, <s>, <q>, <dfn>, <var>, <samp>, <kbd>,
- <i>, <b>, <u>, <mark>, and <bdi> if a unique matching class value
+ <i>, <b>, <u>, <mark>, and <bdi> if a unique, matching class value
is found in `inline`__ and `literal`__ elements.
Use <ins> and <del> if a unique matching class value
is found in `inline`, `literal`, or `container` elements.
@@ -537,7 +542,7 @@
* docutils/io.py
- Fix [ 348 ] Since Python 3.4, the 'U' universal newlines mode has been
- deprecated (thanks to hugovk).
+ deprecated. Thanks to hugovk.
* docutils/languages/ko.py
docutils/parsers/rst/languages/ko.py:
@@ -1242,8 +1247,8 @@
* tools/editors/emacs/rst.el:
- - Fix [ 3001100 ] does not handle spaces in filenames
- (thanks to Jakub Wilk)
+ - Fix [ 3001100 ] does not handle spaces in filenames.
+ Thanks to Jakub Wilk.
* docutils/utils.py:
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2021-10-12 22:16:43 UTC (rev 8852)
+++ trunk/docutils/RELEASE-NOTES.txt 2021-10-13 15:42:30 UTC (rev 8853)
@@ -24,20 +24,22 @@
* `html5` writer:
- - Do not longer set the "footnote-reference" class value for footnote
+ - Stop setting the "footnote-reference" class value for footnote
references. Since 0.18, you can use the CSS selector
``[role="doc-noteref"]`` instead of ``.footnote-reference``
(see minimal.css for examples).
+
+ - Remove option "embed_images" (obsoleted by image_loading_).
+
+ .. _image_loading: docs/user/config.html#image-loading
- - Move attribution behind the blockquote to comply with the
- `"living standard"`__?
- (HTML5__ allows <cite> elements inside a blockquote, cf. Example 16.)
+ - Move attribution behind the blockquote to comply with the `"living
+ standard"`__. (HTML5__ allows <cite> elements inside a blockquote.)
__ https://html.spec.whatwg.org/#the-blockquote-element
- __ https://www.w3.org/TR/html52/grouping-content.html#the-blockquote-element
+ __ https://www.w3.org/TR/2014/REC-html5-20141028/grouping-content.html
+ #the-blockquote-element
-* `htm4css1` writer: Support the embed_images_ option.
-
* `latex2e` writer:
- Change default of use_latex_citations_ setting to True.
@@ -76,8 +78,8 @@
.. _use_latex_citations: docs/user/config.html#use-latex-citations
-Release 0.18b1 (2021-10-05)
-===========================
+Release 0.18
+============
.. Note::
@@ -139,17 +141,18 @@
Use STIX fonts if available.
LaTeX:
- `legacy_class_functions`_ setting default changed to "False":
+ `legacy_class_functions`_ setting default changed to "False",
admonitions are now environments.
-* New standard Docutils doctree node "meta__".
+* New standard Docutils doctree node: <meta__>.
-* New configuration setting: [latex writers] legacy_column_widths_.
+* New configuration settings:
+ [latex writers] legacy_column_widths_ and
+ [html5 writer] image_loading_.
* Removed files:
+ ``iepngfix.htc`` and ``blank.gif`` (IE 6 workaround for `s5_html`).
- - ``iepngfix.htc`` and ``blank.gif`` (IE 6 workaround for `s5_html`).
-
* Removed function: ``utils.unique_combinations``
(obsoleted by ``itertools.combinations``).
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2021-10-12 22:16:43 UTC (rev 8852)
+++ trunk/docutils/docs/user/config.txt 2021-10-13 15:42:30 UTC (rev 8853)
@@ -1143,7 +1143,7 @@
Overrides also stylesheet_path_. [#override]_
-Default: None. Options: ``--stylesheet``.
+Default: None. Option: ``--stylesheet``.
.. _stylesheet_dirs [html writers]:
@@ -1212,7 +1212,7 @@
captionbelow
Place the table caption below the table
- (New in 0.17).
+ (New in Docutils 0.17).
In addition, the HTML writers support:
@@ -1315,34 +1315,49 @@
New in Docutils 0.13.
-__ https://www.w3.org/TR/html53/sections.html#the-h1-h2-h3-h4-h5-and-h6-elements
.. _HTML5 Writer: html.html#html5-polyglot
-.. _HTML5: http://www.w3.org/TR/html5/
+.. _HTML5: https://www.w3.org/TR/2014/REC-html5-20141028/
-
Writer Specific Defaults
""""""""""""""""""""""""
`initial_header_level`_
- 2 (for "<h2>", cf. the `HTML5.3 Working Draft`__)
+ 2 (for "<h2>", cf. the "`The h1, h2, h3, h4, h5, and h6 elements`__"
+ in the HTML Standard)
`stylesheet_path <stylesheet_path [html writers]_>`__:
"minimal.css, plain.css"
+__ https://html.spec.whatwg.org/multipage/sections.html
+ #the-h1,-h2,-h3,-h4,-h5,-and-h6-elements
+
embed_images
""""""""""""
-Embed images in the output HTML file. If the image can be read from
-the local file system and its MIME type can be determined, it is
-base64_ encoded and included as a `data URI`_.
+Deprecated. Obsoleted by image_loading_.
-Default: disabled (False).
-Options: ``--embed-images``, ``--link-images``.
-New in Docutils 0.17.
+image_loading
+"""""""""""""
+Suggest at which point images should be loaded.
+
+:embed: If the image can be read from the local file system, it is
+ base64_ encoded and included as a `data URI`_.
+ (In future, SVG images will be converted to inline SVG)
+
+:eager: load image immediately when opening the HTML document (default).
+
+:lazy: Specify the `lazy loading attribute`_ to defer fetching the image.
+
+Default: "eager". Option: ``--image-loading``.
+
+New in Docutils 0.18.
+
.. _base64: https://en.wikipedia.org/wiki/Base64
.. _data URI: https://en.wikipedia.org/wiki/Data_URI_scheme
+.. _lazy loading attribute: https://html.spec.whatwg.org/multipage/
+ urls-and-fetching.html#lazy-loading-attributes
section_self_link
Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py 2021-10-12 22:16:43 UTC (rev 8852)
+++ trunk/docutils/docutils/writers/_html_base.py 2021-10-13 15:42:30 UTC (rev 8853)
@@ -318,7 +318,11 @@
self.body_suffix = ['</body>\n</html>\n']
self.section_level = 0
self.initial_header_level = int(settings.initial_header_level)
-
+ # image_loading only defined for HTML5 writer
+ self.image_loading = getattr(settings, 'image_loading', 'eager')
+ if (getattr(settings, 'embed_images', False)
+ and self.image_loading == 'eager'):
+ self.image_loading = 'embed'
self.math_output = settings.math_output.split()
self.math_output_options = self.math_output[1:]
self.math_output = self.math_output[0].lower()
@@ -1041,7 +1045,7 @@
if 'align' in node:
atts['class'] = 'align-%s' % node['align']
# Embed image file (embedded SVG or data URI):
- if self.settings.embed_images or ('embed' in node):
+ if self.image_loading == 'embed':
err_msg = ''
if not mimetype:
err_msg = 'unknown MIME type'
@@ -1064,6 +1068,8 @@
# insert as <svg ....> ... </svg> # (about 1/3 less data)
data64 = base64.b64encode(imagedata).decode()
uri = u'data:%s;base64,%s' % (mimetype, data64)
+ elif self.image_loading == 'lazy':
+ atts['loading'] = 'lazy'
if mimetype == 'application/x-shockwave-flash':
atts['type'] = mimetype
# do NOT use an empty tag: incorrect rendering in browsers
Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2021-10-12 22:16:43 UTC (rev 8852)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2021-10-13 15:42:30 UTC (rev 8853)
@@ -85,14 +85,18 @@
settings_spec = settings_spec + (
'HTML5 Writer Options',
'',
- (('Embed images in the output HTML file, if the image '
- 'files are accessible during processing.',
+ (('Obsoleted by "--image-loading".',
['--embed-images'],
{'default': 0, 'action': 'store_true',
'validator': frontend.validate_boolean}),
- ('Link to images in the output HTML file. (default)',
+ ('Obsoleted by "--image-loading".',
['--link-images'],
{'dest': 'embed_images', 'action': 'store_false'}),
+ ('Suggest at which point images should be loaded: '
+ '"embed", "eager" (default), or "lazy".',
+ ['--image-loading'],
+ {'choices': ('embed', 'eager', 'lazy'),
+ 'default': 'eager'}),
('Append a self-link to section headings.',
['--section-self-link'],
{'default': 0, 'action': 'store_true'}),
@@ -281,7 +285,8 @@
if 'controls' in node['classes']:
atts['controls'] = 'controls'
atts['title'] = node.get('alt', uri)
-
+ if self.settings.image_loading == 'lazy':
+ atts['loading'] = 'lazy'
# No newline in inline context or if surrounded by <a>...</a>.
if (isinstance(node.parent, nodes.TextElement) or
(isinstance(node.parent, nodes.reference) and
Modified: trunk/docutils/test/test_writers/test_html5_polyglot_parts.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_polyglot_parts.py 2021-10-12 22:16:43 UTC (rev 8852)
+++ trunk/docutils/test/test_writers/test_html5_polyglot_parts.py 2021-10-13 15:42:30 UTC (rev 8853)
@@ -623,6 +623,40 @@
"""],
+totest['lazy loading'] = ({'image_loading': 'lazy',
+ 'stylesheet_path': '',
+ 'embed_stylesheet': 0}, [
+
+["""\
+.. image:: dummy.png
+""",
+"""\
+{'fragment': '''\
+<img alt="dummy.png" loading="lazy" src="dummy.png" />\\n''',
+ 'html_body': '''\
+<main>
+<img alt="dummy.png" loading="lazy" src="dummy.png" />
+</main>\\n''',
+ 'html_head': '''...<title><string></title>\\n'''}
+"""],
+["""\
+.. figure:: dummy.png
+""",
+"""\
+{'fragment': '''\
+<figure>
+<img alt="dummy.png" loading="lazy" src="dummy.png" />
+</figure>\\n''',
+ 'html_body': '''\
+<main>
+<figure>
+<img alt="dummy.png" loading="lazy" src="dummy.png" />
+</figure>
+</main>\\n''',
+ 'html_head': '''...<title><string></title>\\n'''}
+"""],
+])
+
if __name__ == '__main__':
import unittest
unittest.main(defaultTest='suite')
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
