Add LaTeX SVG to PDF converter extension

[sephalon]

Subject: Add LaTeX SVG to PDF converter extension

Feature or Bugfix

• Feature

Purpose

The imgconverter extension converts vector graphics like SVG and PDF to PNG, which is a very portable approach. However, for quality and reusability reasons we prefer to keep all images in SVG format and only perform a conversion if necessary; right now, the LaTeX builder seems to be the only one.

Open Issues

• I don't like the extension name yet, any better ideas?
• Do we have to consider any other builders that need conversion?
• If yes, we could add configuration options to fine-tune conversion rules.
• Support rsvg-convert (lower footprint) in addition to Inkscape and allow the user to choose
• No documentation yet.

Relates

• Add a new extension: sphinx.ext.imgconverter #3653
• Automatically convert SVG to PDF images in the latex builder #2859

[tk0miya]

-1; it's hard to support them on this project because we don't have enough time. How about third party extension?

[tk0miya]

Why only for LaTeX builder?

[sephalon]

HTML, ePUB and so on handle SVG fine (if the viewer supports it, but that's another story). AFAIK LaTeX is the only one that needs mandatory conversion to PDF. However we could provide a configuration option to fine-tune conversion rules.

[tk0miya]

ImageConveter will be called only if the builder does not support the image format.
For example, HTML builder supports image/svg+xml format. So this converter will not be called on that case.

sphinx/sphinx/builders/html.py

Lines 227 to 228 in 69383f8

	supported_image_types = ['image/svg+xml', 'image/png',
	'image/gif', 'image/jpeg']

On the other hand, LaTeX builder does not support it. But it supports application/pdf.

sphinx/sphinx/builders/latex.py

Line 57 in 69383f8

supported_image_types = ['application/pdf', 'image/png', 'image/jpeg']

ImageConverter class and its subclass will be called based on conversion_rules mapping.

+    conversion_rules = [
+        ('image/svg+xml', 'application/pdf'),
+    ]

This mapping table consists of list of (source format, destination format).

For this reason, you don't need to restrict this only for LaTeX builder.

[sephalon]

Thanks, you're completely right. For some reason I must have missed that…

[sephalon]

@tk0miya Yeah, I kind of expected that ;-) In that case I'd like to collect some opinions here and publish it as a third-party extension.

[tk0miya]

Good to know. I agreed this is very useful. +1!

[codecov]

Codecov Report

Merging #4772 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #4772   +/-   ##
=======================================
  Coverage   82.13%   82.13%           
=======================================
  Files         283      283           
  Lines       37671    37671           
  Branches     5838     5838           
=======================================
  Hits        30942    30942           
  Misses       5418     5418           
  Partials     1311     1311

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f26db5b...0f7efff. Read the comment docs.

[jfbu]

I have a proposal about Mac OS: as explained at https://bugs.launchpad.net/inkscape/+bug/1449251, when using a binary install of Inkscape on Mac OS X (as one gets from the Download page, currently https://inkscape.org/en/release/0.92.2/mac-os-x/107/dmg/ is latest available, 0.92.3 must be compiled from sources), one must use filename with absolute paths.

For example, this

$ /Applications/Inkscape.app/Contents/Resources/script -z --export-pdf=/Users/xxxxxx/Downloads/pic1.pdf testpsspecials.svg

** (inkscape-bin:1493): WARNING **: Can't open file: testpsspecials.svg (doesn't exist)

fails and one must use

$ /Applications/Inkscape.app/Contents/Resources/script -z --export-pdf=/Users/xxxxxx/Downloads/pic1.pdf /Users/xxxxxx/Downloads/testpsspecials.svg

Thus to better support Inkscape on Mac OS X, you would need also to check for existence of /Applications/Inkscape.app/Contents/Resources/script and additionally to make sure all used filenames are absolute.

[sephalon]

I moved the extension into sphinxcontrib-svg2pdfconverter. Let's continue the discussion over there; pull request can be closed.

@jfbu At least under Linux, Sphinx already uses absolute paths by default. I don't have macOS available; could you please test the extension on your system?

[jfbu]

@sephalon

Yes, Sphinx imgconverter uses absolute paths which is good for Inkscape on MacOS. I have made simple test of your https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter and it seems to work fine. I added to PATH

/Applications/Inkscape.app/Contents/Resources/bin

because I only have Inkscape installed as a MacOS application. I thought that invoking it as in my comment with Resources/script -z would have been the better way (I am no expert user and copied pasted some long time ago from the net) but it seems to behave like inkscape, by this I mean in both cases an XQuartz session is opened, which adds a bit overhead first time.

Not being Inkscape-knowledgeable I don't know if one can run it on the Mac from a script without having XQuartz launched, when Inkscape is installed only in /Applications.

Because all seems well, I add my comments here, not at https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter because I see no immediate issue to raise ;-).

edit: I have found one, on make clean html Inkscape seems to be invoked in some way despite no conversion needed because XQuartz gets opened.

Ah well, console output seems to give no account of your extension activity, perhaps it could be useful to have a verbose mode? (github has no good interface for discussions like this...)

[sephalon]

@jfbu

Ah well, console output seems to give no account of your extension activity, perhaps it could be useful to have a verbose mode? (github has no good interface for discussions like this...)

You can see debug messages if you invoke Sphinx with -vv (by e.g. adding them to SPHINXOPTS in the Makefile).