SF.net SVN: docutils:[9999 ] trunk/docutils
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9999
http://sourceforge.net/p/docutils/code/9999
Author: milde
Date: 2024-12-11 21:14:49 +0000 (Wed, 11 Dec 2024)
Log Message:
-----------
Support SVG images in LaTeX with the "svg" package.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/docs/ref/rst/directives.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docs/user/latex.rst
trunk/docutils/docutils/writers/latex2e/__init__.py
trunk/docutils/test/test_writers/test_latex2e.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2024-12-11 14:36:47 UTC (rev 9998)
+++ trunk/docutils/HISTORY.rst 2024-12-11 21:14:49 UTC (rev 9999)
@@ -177,8 +177,11 @@
- Mark the main language when loading "babel".
- Provide an "unknown_references_resolver" (cf. `docutils/TransformSpec`)
for citation references resolved with BibTeX (cf. `use_bibtex`_ setting).
+ - Support SVG image inclusion with the "svg" LaTeX package (see the
+ `stylesheet`__ configuration setting).
.. _reference-label: docs/user/config.html#reference-label
+ __ docs/user/config.html#stylesheet-latex-writers
* docutils/writers/latex2e/docutils.sty
Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst 2024-12-11 14:36:47 UTC (rev 9998)
+++ trunk/docutils/docs/ref/rst/directives.rst 2024-12-11 21:14:49 UTC (rev 9999)
@@ -171,7 +171,7 @@
HTML5_ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
-LaTeX_ [#]_ ✓ ✓ ✓
+LaTeX_ [#]_ ✓ [#]_ ✓ ✓ ✓
ODT_ ✓ ✓ ✓ ✓ ✓
=========== ====== ====== ===== ===== ===== ===== ===== ===== ===== =====
@@ -190,6 +190,9 @@
Some build systems, e.g. rubber_ support additional formats
via on-the-fly image conversion.
+.. [#] New in Docutils 0.22.
+ The `"svg" package`_ must be listed in the stylesheet__ setting.
+
__ https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types
.. _HTML4:
.. _html4 writer: ../../user/html.html#html4css1
@@ -198,7 +201,9 @@
.. _LaTeX: ../../user/latex.html#image-inclusion
.. _ODT: ../../user/odt.html
.. _manpage: ../../user/manpage.html
-.. _rubber: https://github.com/petrhosek/rubber
+.. _rubber: https://gitlab.com/latex-rubber/rubber
+.. _"svg" package: https://ctan.org/pkg/svg
+__ ../../user/config.html#stylesheet-latex-writers
Image
@@ -271,7 +276,7 @@
``height`` : length_
The desired height of the image.
- Used to reserve space or scale the image vertically. When the ``scale``
+ Used to reserve space or scale the image vertically. When the scale_
option is also specified, they are combined. For example, a height of
200px and a scale of 50 is equivalent to a height of 100px with no scale.
@@ -288,6 +293,8 @@
(New in Docutils 0.21.)
+ .. _scale:
+
``scale`` : integer percentage (the "%" symbol is optional)
The uniform scaling factor of the image. The default is "100 %",
i.e. no scaling.
@@ -305,7 +312,7 @@
``width`` : length_ or percentage_ of the current line width
The width of the image.
Used to reserve space or scale the image horizontally. As with ``height``
- above, when the ``scale`` option is also specified, they are combined.
+ above, when the scale_ option is also specified, they are combined.
.. [#] Currently only recognized by the `HTML5 writer`_
(overriding the `image_loading`_ configuration setting).
@@ -596,7 +603,7 @@
The parsing can be turned off with the syntax_highlight_ configuration
setting and command line option or by specifying the language as
-`class <class option_>`_ option instead of directive argument.
+`class <class option>`_ option instead of directive argument.
This also avoids warnings when Pygments_ is not installed or the language
is not in the `supported languages and markup formats`_.
@@ -2295,7 +2302,6 @@
.. _loading attribute: ../doctree.html#loading
.. _names attribute: ../doctree.html#names
.. _title attribute: ../doctree.html#title-attribute
-.. _uri attribute: ../doctree.html#uri
.. _width attribute: ../doctree.html#width
.. _<admonition>: ../doctree.html#admonition
.. _<attention>: ../doctree.html#attention
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2024-12-11 14:36:47 UTC (rev 9998)
+++ trunk/docutils/docs/user/config.rst 2024-12-11 21:14:49 UTC (rev 9999)
@@ -1853,7 +1853,7 @@
stylesheet
~~~~~~~~~~
-List of style files (comma-separated_). Used verbatim
+Comma-separated_ list of style files (LaTeX packages). Used verbatim
(under Windows, path separators are normalized to forward slashes).
Overrides also stylesheet_path__. [#override]_
See also `stylesheet [html writers]`_.
@@ -1863,11 +1863,23 @@
extension) or ``\input`` (any other extension).
LaTeX will search the specified files in the `TeX input path`_.
+Some values change the behaviour of the LaTeX writer:
+
+:docutils: If the `"docutils" package`_ is listed, fallback definitions
+ for `Docutils specific LaTeX macros`_ are loaded from there
+ instead of literal inclusion in the output document.
+:svg: If the `"svg" package`_ is listed, SVG images_ are
+ included with the ``\includesvg`` command instead of
+ the default ``\includegraphics`` (new in Docutils 0.22).
+
*Default*: empty list. *Option*: ``--stylesheet``.
__ `stylesheet_path [latex writers]`_
__ `embed_stylesheet [latex writers]`_
.. _TeX input path: https://texfaq.org/FAQ-tds
+.. _"docutils" package: https://ctan.org/pkg/docutils
+.. _Docutils specific LaTeX macros: latex.html#docutils-specific-latex-macros
+.. _"svg" package: https://ctan.org/pkg/svg
.. _stylesheet_dirs [latex writers]:
@@ -2513,8 +2525,8 @@
.. References
+.. _Docutils Document Tree:
.. _Docutils Generic document type definition:
-.. _Docutils Document Tree:
.. _Document Tree: ../ref/doctree.html
.. _class attribute: ../ref/doctree.html#classes
.. _title attribute: ../ref/doctree.html#title-attribute
@@ -2536,6 +2548,7 @@
.. _"code": ../ref/rst/directives.html#code
.. _"csv-table": ../ref/rst/directives.html#csv-table
.. _"figure": ../ref/rst/directives.html#figure
+.. _images:
.. _"image": ../ref/rst/directives.html#image
.. _"include": ../ref/rst/directives.html#include
.. _"loading": ../ref/rst/directives.html#loading
Modified: trunk/docutils/docs/user/latex.rst
===================================================================
--- trunk/docutils/docs/user/latex.rst 2024-12-11 14:36:47 UTC (rev 9998)
+++ trunk/docutils/docs/user/latex.rst 2024-12-11 21:14:49 UTC (rev 9999)
@@ -60,30 +60,29 @@
------------------------------
Some Docutils objects have no LaTeX counterpart, they will be typeset
-using a Docutils specific LaTeX *macro* (command, environment, or
-length) to allow customization. By convention, special macros use the
-prefix ``\DU``\ [#]_.
+using a Docutils specific LaTeX *macro* (command, environment, or length)
+to allow customization. By convention, these macros use the prefix
+``\DU``\ [#]_.
+Fallback definitions are included after the `custom style sheets`_,
+for all macros required in the document. Alternatively, you may list
+"docutils" in the `stylesheet`_ setting to use the `"docutils" package`_
+instead.
-The `docutils.sty`_ LaTeX package providing required definitions is
-part of Docutils ≥ 0.17 and available on CTAN since 2020-09-04.
-The generated LaTeX documents should be kept processable by a standard LaTeX
-installation. Therefore fallback definitions are included after the `custom
-style sheets`_, if a macro is required in the document and
-the `stylesheet`_ setting does not include "docutils".
-
* Custom `style sheets`_ can define alternative implementations with
``\newcommand``, ``\newenvironment``, and ``\newlength`` followed by
``\setlength``.
-* Definitions with `raw LaTeX`_ are part of the document body. Use
+* Definitions with `raw LaTeX`_ are part of the document body. Use
``\def``, ``\renewcommand`` or ``\renewenvironment``, and ``\setlength``.
-See the test output standalone_rst_latex.tex_ for an example of the fallback
-definitions and their use in the document.
+See docutils.sty_ and the test output `standalone_rst_latex.tex`_ for
+an example of the fallback definitions and their use in the document.
.. [#] DU for Documentation Utilities = Docutils
-.. _docutils.sty: https://ctan.org/pkg/docutils
+.. _"docutils" package: https://ctan.org/pkg/docutils
+.. _docutils.sty:
+ https://mirrors.ctan.org/macros/latex/contrib/docutils/docutils.sty.html
.. _length unit:
@@ -1974,35 +1973,43 @@
image inclusion
```````````````
-Images__ are included in LaTeX with the help of the `graphicx` package. The
-supported file formats depend on the used driver:
+Images_ are included in LaTeX with the help of the `graphicx`_ package.
+The supported graphic formats depend on the postprocessor:
-* pdflatex_, lualatex, and xelatex_ work with PNG, JPG, or PDF,
- but **not EPS**.
-* Standard latex_ can include **only EPS** graphics, no other format.
-* latex + dvipdfmx works with EPS and JPG (add 'dvipdfmx' to the
- documentoptions_ or graphicx-option_ setting
- and 'bmpsize' to the stylesheet_ setting).
+* pdflatex_, lualatex_, and xelatex_ work with PNG, JPG, and PDF
+ but *not EPS*.
-If PDF-image inclusion in PDF files fails, specifying
-``--graphicx-option=pdftex`` might help.
+* When compiling to DVI with the ``latex`` command, support depends on
+ the viewer or post-processor:
+ - dvips supports EPS but not other format,
+ - dvipdfmx works with EPS and JPG (add 'dvipdfmx' to the documentoptions_
+ or graphicx-option_ setting and 'bmpsize' to the stylesheet_ setting).
+
+* SVG images are supported if the `"svg" package`_ is listed in the
+ stylesheet_ setting. Pass the ``--shell-escape`` option to the LaTeX
+ compiler to enable image conversion on the fly by Inkscape_.
+ (New in Docutils 0.22.)
+
+* The Rubber_ wrapper can be used for automatic image conversion.
+
For details see grfguide.pdf_.
-The Rubber_ wrapper can be used for automatic image conversion.
-
Docutils expects a URI-reference_ as pointer to the image ressource.
-LaTeX requires it to refer to a local file.
+The LaTeX writer transforms it to a filesystem path.
By default, LaTeX does not accept spaces and more than one dot in the
filename. If using "traditional" filenames is not an option, loading the
grffile_ package may help.
-__ ../ref/rst/directives.html#images
+.. _images: ../ref/rst/directives.html#images
+.. _graphicx: https://ctan.org/pkg/graphicx
+.. _graphicx-option: config.html#graphicx-option
.. _grfguide.pdf:
https://mirrors.ctan.org/macros/latex/required/graphics/grfguide.pdf
+.. _URI-reference: https://www.rfc-editor.org/rfc/rfc3986.html#section-4.1
+.. _"svg" package: https://ctan.org/pkg/svg
+.. _Inkscape: https://inkscape.org/
.. _grffile: https://ctan.org/pkg/grffile
-.. _graphicx-option: config.html#graphicx-option
-.. _URI-reference: https://www.rfc-editor.org/rfc/rfc3986.html#section-4.1
Why are my images too big?
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2024-12-11 14:36:47 UTC (rev 9998)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2024-12-11 21:14:49 UTC (rev 9999)
@@ -2483,10 +2483,14 @@
post.append('\n')
pre.reverse()
self.out.extend(pre)
+ if imagepath.suffix == '.svg' and 'svg' in self.settings.stylesheet:
+ cmd = 'includesvg'
+ else:
+ cmd = 'includegraphics'
options = ''
if include_graphics_options:
- options = '[%s]' % (','.join(include_graphics_options))
- self.out.append('\\includegraphics%s{%s}' % (options, imagepath))
+ options = f"[{','.join(include_graphics_options)}]"
+ self.out.append(f'\\{cmd}{options}{{{imagepath}}}')
self.out.extend(post)
def depart_image(self, node) -> None:
Modified: trunk/docutils/test/test_writers/test_latex2e.py
===================================================================
--- trunk/docutils/test/test_writers/test_latex2e.py 2024-12-11 14:36:47 UTC (rev 9998)
+++ trunk/docutils/test/test_writers/test_latex2e.py 2024-12-11 21:14:49 UTC (rev 9999)
@@ -163,15 +163,39 @@
"""],
])
-samples['image'] = ({}, [
-[".. image:: blue%20square.png",
+samples['images'] = ({}, [
+["""
+.. image:: blue%20square.png
+.. image:: vectors.svg
+""",
head_image + r"""
\includegraphics{blue square.png}
+\includegraphics{vectors.svg}
+
\end{document}
"""],
])
+samples['svg-image'] = ({'stylesheet': 'svg'}, [
+["""
+.. image:: pixels.png
+.. image:: vectors.svg
+""",
+head_template.substitute(dict(parts,
+requirements=r"""\usepackage[T1]{fontenc}
+\usepackage{graphicx}
+""",
+stylesheet=r"""\usepackage{svg}
+""")) + r"""
+\includegraphics{pixels.png}
+
+\includesvg{vectors.svg}
+
+\end{document}
+"""],
+])
+
samples['spanish_quote'] = ({}, [
[".. role:: language-es\n\nUnd damit :language-es:`basta`!",
head_template.substitute(dict(parts,
@@ -1145,6 +1169,7 @@
"""],
])
+
samples['stylesheet_path'] = ({'stylesheet_path': f'{spam},{ham}'}, [
["""two stylesheet links in the header""",
head_template.substitute(dict(parts,
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins