Skip to content

Support SVG in PDF / LaTeX (e.g. via svg2pdf), or allow specifying "alternates" #2873

@fingolfin

Description

@fingolfin

We have SVGs in our Documenter manual, and now want to produce PDFs. This doesn't work, as SVGs are not currently supported by lulatex.

While researching this I discovered that Julia itself has run into this issue and worked around it by using PNG versions of the images, which is not nice of course (the PNGs are relatively low-res, so this is a common lowest denominator solution).

Right now I am tinkering with a solution based on @raw blocks. But that's really cumbersome. E.g. to get Julia to again use SVG instead of PNG, I am now tinkering with replacing this:

![Diagram of the compiler flow](./img/compiler_diagram.png)

by this:

```@raw html
<img src="img/compiler_diagram.svg" alt="Diagram of the compiler flow"/>
```
```@raw latex
\begin{figure}
\centering
\includegraphics[max width=\linewidth]{devdocs/img/compiler_diagram.pdf}
\caption{Diagram of the compiler flow}
\end{figure}
```

But besides duplicating a lot of stuff (e.g. the caption) it also requires fiddling to figure out the right path for the LaTeX.

Two possible solutions come to mind:

  1. add transparent support for SVGs by using a tool like svg2pdf or so
    (drawback: the quality of this can be very varied, from great to horrible.)
  2. add a way to specify "alternates" for an image based on e.g. the rendering target... Several variants of that come to mind:
    i. Implicit: e.g. by omitting the file extension and letting Documenter pick one: so ![text](demo.png) would become ![text](demo) and Documenter would try adding various extensions. For example) first .pdf then .png for LaTeX; and first .svgthen.pngthen.jpgfor HTML. (This is loosely inspired byincludegraphicsin LaTeX) ii. Explicitly: by adding some mechanism to substitute the image being used... for this in turn one can think of many variants, e.g. theLaTeXWrite` could take an optional dictionary which maps image paths to alternate images.

For the "explicit" solution it might also be useful to have some sibling to the @raw format blocks which inserts Markdown... Then one could write

This only appears in HTML:
```@only_format html
![text](demo.svg)
```
```@except_format html
![text](demo.pdf)
```

or so. But this is still repetitive, so I'd really like to have one of the options listed before (but it might still be useful to have such a "conditional" feature).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions