Proposal: Links from SVG images to the document content

[Volker Jaenisch]

Free diagram softwares like draw.io are capable to glue links to every diagram element you like. These links will be exported to SVG.

My Idea is to use these SVG links from Sphinx (Myst) to link to the document content.

This Idea is not new others have proposed such thing e.g.

https://github.com/executablebooks/MyST-Parser/issues/176

This is not possible since the inflexible nature of the HTML-Translator classes.

The translation of a docutils.image token to HTML is hard coded to produce an <img> tag.

To use the links of a SVG one needs to use a <object> tag to include the SVG image.

This can be succesfully demostrated utilizing the following md code:

<object data="../../_images/output.svg" type="image/svg+xml"></object>

```{figure} ../../images/output.svg
:height: 0px

The caption text....

```

To implement such a feature two things must happen:

1) Sphinx needs to learn a new token.type or a new parameter to an existing token type

A short time "solution" may be to implement an extension which replaces the HTML-Translators with custom ones.

2) Myst has to learn this new type also. 

And there is some work to do to patch the SVG images on the fly to deal with relative links from the document structure. But this can easily be done by defining some sort of speudo URIs like:

* Local anchor: myst://#local-anchor

* Anchor on other file: myst://mydoc#local-anchor

for the use in the SVG generating software. 

And some simple python code to parse the SVG and replace the speudo URIs with the real relative URIs.

I am here to learn and discuss.

Cheers,

Volker

[Guenter Milde]

On 2024-02-15, Volker Jaenisch wrote:

> Free diagram softwares like draw.io are capable to glue links to every
> diagram element you like. These links will be exported to SVG.

> *My Idea is to use these SVG links from Sphinx (Myst) to link to the
> document content.*

> This Idea is not new others have proposed such thing e.g.
> https://github.com/executablebooks/MyST-Parser/issues/176

> This is not possible since the inflexible nature of the HTML-Translator
> classes.
> The translation of a docutils.image token to HTML is hard coded to produce
> an <img> tag.

This is the behaviour of the current Docutils "html5" writer (which is also
the default HTML writer for Sphinx).

> To use the links of a SVG one needs to use a <object> tag to include the
> SVG image

... or embed the SVG image in the HTML. Both methods have their advantages
and problems.

The "html4css1" writer, references SVG images in <object> nodes
(to work around missing SVG support in Internet Explorer).
Sphinx can be configured to use this legacy HTML writer.

The upcoming Docutils 0.20 will support directly embedding SVG images.

> A short time "solution" may be to implement an extension which replaces the
> HTML-Translators with custom ones.

Yes.

...

`docutils.writers.html4css1.HTMLTranslator` uses the attribute::

object_image_types = {'.svg': 'image/svg+xml',
'.swf': 'application/x-shockwave-flash',
'.mp4': 'video/mp4',
'.webm': 'video/webm',
'.ogg': 'video/ogg',
}

for image formats that should be referenced in <object> tags.

With browser support for SVG in <img> tags and video support in <video>
tags, the only remaining format requiring <object> is Shockwave Flash.

Would it help, if `docutils.writers._html_base.HTMLTranslator` used::

object_image_types = {'.swf': 'application/x-shockwave-flash'}

instead of the current hard-coded selection?


Günter