#108 title/tooltip option for the "image" directive

[toastal]

Like image’s :alt: directive, allow :title: for creating titles on pointer hover. The use case here is different from alt as alt is for assistive technologies & titles are more to give a labels for images for those with pointer cursors.

Expected input

.. image:: /house.jxl
    :alt: Home
    :title: Navigate home
    :target: /

.. image:: /cat.jxl
    :alt: A Siamese cat on a chair
    :title: Chula says, “meow”

Expected HTML output

<a href="/"><img src="/house.jxl" alt="Home" title="Navigate home"></a>
<img src="/cat.jxl" alt="A Siamese cat on a chair" title="Chula says, “meow”">

~~~

[Günter Milde]

Thank you for the suggestion.
Support for the <img> "title" attribute in HTML output would require a means to store the
title in the <image> document tree element, e.g. a new attribute.
Before an implementation, we would have to consider how an image "title" option/attribute should be handled in other output formats like LaTeX/PDF or OpenDocument text.

Alternatively, a figure with approbiately styled caption might suit your needs:

For the rST source

.. figure:: meow.png

   A siamese cat.

a possible styling of HTML5 writer output would be

figcaption {
  display: none;
  padding: 1em;
  width: 30vw;
  background: lightyellow}
figure:hover figcaption { display: block; }

[toastal]

I would say the title is strictly for HTML output. In the way that touch pointers often can’t read the title, it is left for cursor pointer & screen readers. Thinking about it in this sense tho, I think even if the HTML attribute is called title the name is probably easily confused with something visible. HTML spec says to not ‘rely’ on it, but it makes a good place for Easter eggs or other flavor commentary.

For context, my existing workaround is, as you noted, using a .. figure & post-processing based on a specific CSS class to 1) move <figcaption> contents to title, 2) ‘unwrap’ the parent figure node to just leave the <img> behind, but this feels like a hack/abuse, especially since the flavor text isn’t meant to be visible for PDFs which the .. figure would show.

More info: https://html.spec.whatwg.org/multipage/dom.html#the-title-attribute

[Günter Milde]

If at all, an attribute/option to-be-translated to the HTML "title" attribute would come under a different name ("tooltip" or "annotation", say):

• Looking at its description in the HTML standard, the "title" attribute seems misnamed. It contains "advisory information" presented as a tooltip (or not at all).
• It can easily be confused with the HTML <title> element.
• In Docutils, there is already a "title" attribute: Used on the <document> element for the "metadata title" (which corresponds to the HTML <title> element) and is, e.g. shown on a browsers toolbar.

Where should Docutils/rST support stop?

• In HTML, "title" is one of the common attributes, supported by (almost) all elements.

• The LaTeX package "pdfcomment" provides a \pdftooltip macro that creates
  pop-ups in PDF output. Like the HTML "title" attribute, it can be used on paragraphs, tables, footnote references, and more.

However, whether support for an attribute you may use for easter eggs but must not rely on is a valuable addition for a lightweight markup language remains questionable.
For the rare use cases exist workarounds in form of CSS rules or "raw" HTML.

Commit [r9950] adds support for class values on the figure caption. Now you can write:

.. figure:: meow.png
    .. class:: tooltip

   A siamese cat.

and style the resulting HTML5 writer output with

 figcaption.tooltip {
   display: none;
   padding: 0.5em;
   width: 20vh;
   background: lightyellow;
   }
 figure:hover figcaption.tooltip { 
   display: block; 
   position: absolute;
   }

To suppress the tooltip in PDF output, convert with

rst2latex --strip-elements-with-class=tooltip

[Günter Milde]

See also the proposal by Roman Suzi in "docutils-users" from 2003-07-07 [1]
and a recent request for a hyperlink with "title" attribute [2].

[1] https://sourceforge.net/p/docutils/mailman/docutils-users/thread/Pine.LNX.4.44.0307070819150.2138-100000%40rnd.onego.ru/#msg4465479

[2] https://sourceforge.net/p/docutils/mailman/docutils-users/thread/20241223165633.348f4e6559e04e9e1afd1c12%40poczta.onet.pl/#msg59108867

[Günter Milde]

This feature request needs more thought and discussion.
It may be a topic for a new enhancement proposal.