docutils-users

[Docutils-users] <img> instead of <video> tag inserted for image:: foo.mp4

[Agathe P. <mic...@mi...>]

Dear Docutils maintainers,

I am using docutils 0.18.1. When feeding the following input to docutils 
via pelican [0] :

.. image:: 
/blog/2022/04/27/exporting-mov-and-mp4-animations-from-gimp/out.mp4
    :alt: test

I get the following HTML output:

<img alt="test" 
src="/blog/2022/04/27/exporting-mov-and-mp4-animations-from-gimp/out.mp4">

However, according to the documentation [1], this should export a 
<video> tag instead of a <img> tag given that the file extension is ".mp4".

[0] https://blog.getpelican.com/
[1] https://docutils.sourceforge.io/docs/ref/rst/directives.html#footnote-1

Please keep me in Cc, I am not subscribed to this list.

Best regards,

Agata.

Re: [Docutils-users] <img> instead of <video> tag inserted for image:: foo.mp4

[Guenter M. <mi...@us...>]

On 2022-04-27, Agathe Porte wrote in gmane.text.docutils.user:
> Dear Docutils maintainers,

> I am using docutils 0.18.1. When feeding the following input to docutils 
> via pelican [0] :

> .. image:: 
> /blog/2022/04/27/exporting-mov-and-mp4-animations-from-gimp/out.mp4
>     :alt: test

> I get the following HTML output:

><img alt="test" 
> src="/blog/2022/04/27/exporting-mov-and-mp4-animations-from-gimp/out.mp4">

> However, according to the documentation [1], this should export a 
><video> tag instead of a <img> tag given that the file extension is ".mp4".

It seems that Pelican (at least with your configuration) uses the
traditional HTML4 writer for HTML export.

Only the `HTML5 writer`_ supports video. Finding out how/whether Pelican
can be configured to use the HTML5 writer is left as an exercise for the
reader.



.. HTML5 writer: 
   https://docutils.sourceforge.io/docs/user/html.html#html5-polyglot


> [0] https://blog.getpelican.com/
> [1] https://docutils.sourceforge.io/docs/ref/rst/directives.html#footnote-1

y

Re: [Docutils-users] <img> instead of <video> tag inserted for image:: foo.mp4

[Agathe P. <mic...@mi...>]

Hi,

29/04/2022 10:54, Guenter Milde :
>> However, according to the documentation [1], this should export a
>> <video> tag instead of a <img> tag given that the file extension is ".mp4".
> It seems that Pelican (at least with your configuration) uses the
> traditional HTML4 writer for HTML export.
>
> Only the `HTML5 writer`_ supports video. Finding out how/whether Pelican
> can be configured to use the HTML5 writer is left as an exercise for the
> reader.
>
I was able to configure pelican to use html5_polyglot using 
rst_with_html5 Pelican plugin [1]. As I dig further and further into 
html5_polyglot, I am sad to see that <video> has no first class support 
in reStructuredText. I did a local patch to add more attributes to the 
renderer, then another patch for allowing alternative source format, but 
I think that a new video class should be added instead of hacking the 
image class so deeply.

This has been done in a plugin for sphinx [2]: full support of a 
distinct video node that can support extra attributes. One quirk of 
using "classes" for detecting {loop,controls,autoplay} is that the video 
keeps the "loop" CSS style class, which seems not useful and can 
conflict with CSS classes.

I was not able to see prior discussion for proper video support in 
docutils using a search engine. Please enlighten my light if anything 
seems wrong with this proposal. I can volonteer to implement this 
feature and document it for docutils. I think it would be better than 
the current two alternatives: using out-of-tree plugins or hacking image 
nodes.

Bests,

Agata

[1] https://github.com/bekcpear/pelican-rst_with_html5

[2] 
https://github.com/sphinx-contrib/video/blob/master/sphinxcontrib/video.py

Re: [Docutils-users] <img> instead of <video> tag inserted for image:: foo.mp4

[Guenter M. <mi...@us...>]

Dear Agathe,

On 2022-05-03, Agathe Porte wrote:

...

> As I dig further and further into html5_polyglot, I am sad to see that
> <video> has no first class support in reStructuredText. 

Video is a relatively new addition and only rarely used up to now.
This is also related to poor support in the target document formats 
(just HTML5, no ODF, LaTeX, or troff (manpage)).

> I did a local patch to add more attributes to the renderer, then
> another patch for allowing alternative source format, 

thank you for sharing

> but I think that a new video class should be added instead of hacking
> the image class so deeply. This has been done in a plugin for sphinx
> [2]: full support of a distinct video node that can support extra
> attributes. 

I suppose "class" here means a new document node class and maybe matching
directive? 
This is one way to do it, it would mean a change to the Docutils document
model https://docutils.sourceforge.io/docs/ref/doctree.html as well as
the reStructuredText specification
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html.

What would be the advantage over a common <image> node for both still and
moving images?

> One quirk of using "classes" for detecting {loop,controls,autoplay} is
> that the video keeps the "loop" CSS style class, which seems not useful
> and can conflict with CSS classes.

This may be solved by popping the relevant values from the "classes" list
(as is done with "language-.." values and, in `html5_polyglot` for the
classes corresponding to semantic HTML5 tags (cf. the
`html5-text-level-tags.txt` functional test input and resulting
`standalone_rst_html5.html`).
(CSS stylesheet rules can also use the "loop" attribute as selector.)

> I was not able to see prior discussion for proper video support in 
> docutils using a search engine. Please enlighten my light if anything 
> seems wrong with this proposal. 

Alternative sources are also useful (and supported for) still images in HTML5.
cf. https://sourceforge.net/p/docutils/mailman/docutils-develop/thread/a461cd5a-6222-45bc-ac66-0be0117e6002%40Spark/#msg37264494

Another use case is providing for alternative formats in the rst source 
for different output formats (e.g. SVG for HTML, PDF for LaTeX).
Different writers would filter out non-supported formats.

Instead of the HTML "srcset" syntax, I consider adding support for
optional nested <source> nodes (similar to the ones in HTML5 <video>).
This would, IMO, give a clearer way to specify image resolution and sizes
than the "srcset" and "sizes" attributes.

We should/could start a dedicated thread in docutils-develop or
feature-enhancement ticket for this.

Thanks,

Günter