docutils-develop

[Docutils-develop] [docutils:feature-requests] #108 Image title directive

[toastal <to...@us...>]

---

**[feature-requests:#108] Image title directive**

**Status:** open
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Sun Sep 29, 2024 08:41 AM UTC
**Owner:** nobody


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”">
~~~

~~~






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #108 Image title directive

[Günter M. <mi...@us...>]

How should this be handled for non-HTML output like LaTeX/PDF or OpenDocument text?


---

**[feature-requests:#108] Image title directive**

**Status:** open
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Sun Sep 29, 2024 08:41 AM UTC
**Owner:** nobody


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”">
~~~

~~~






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #108 Image title directive option

[Günter M. <mi...@us...>]

- **summary**: Image title directive --> Image title directive option



---

**[feature-requests:#108] Image title directive option**

**Status:** open
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Tue Oct 01, 2024 06:50 AM UTC
**Owner:** nobody


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”">
~~~

~~~






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #108 "title" option for the "image" directive

[Günter M. <mi...@us...>]

- **summary**: Image title directive option --> "title" option for the "image" directive



---

**[feature-requests:#108] "title" option for the "image" directive**

**Status:** open
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Tue Oct 01, 2024 07:21 AM UTC
**Owner:** nobody


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”">
~~~

~~~






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #108 "title" option for the "image" directive

[Günter M. <mi...@us...>]

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

* Looking at its [description in the HTML standard](https://html.spec.whatwg.org/multipage/dom.html#the-title-attribute), the title attribute is misnamed. It contains "advisory information" presented as a tooltip (if at all). 
* It can easily be confused with the HTML [`<title>` element](https://html.spec.whatwg.org/multipage/semantics.html#the-title-element).
* In  Docutils, there is already a ["title" attribute](https://docutils.sourceforge.io/docs/ref/doctree.html#title-1): Used on the `<document>` element for the "metadata title" (which corresponds to the HTML `<title>` element!

In HTML, "title" is one of the common attributes, supported by (almost) all elements. Where should Docutils/rST support stop?

The LaTeX package "pdfcomment" provides a `\pdftooltip` macro that may be used for
pop-ups in PDF output. Like the HTML "title" attribute, it may be used on paragraphs, tables, footnotes references...

However, whether support for an attribute you should not rely on is a valuable addition for a lightweight markup language remains questionable, especially as 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



---

**[feature-requests:#108] "title" option for the "image" directive**

**Status:** open
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Mon Oct 14, 2024 06:46 AM UTC
**Owner:** nobody


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”">
~~~

~~~






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #108 "title" option for the "image" directive

[Günter M. <mi...@us...>]

- **status**: open --> pending-works-for-me



---

**[feature-requests:#108] "title" option for the "image" directive**

**Status:** pending-works-for-me
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Tue Oct 15, 2024 07:57 PM UTC
**Owner:** nobody


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”">
~~~

~~~






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #108 Image title directive option

[toastal <to...@us...>]

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


---

**[feature-requests:#108] Image title directive option**

**Status:** open
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Tue Oct 01, 2024 07:00 AM UTC
**Owner:** nobody


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”">
~~~

~~~






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #108 "title" option for the "image" directive

[Günter M. <mi...@us...>]

See also the proposal by Roman Suzi in "docutils-users" from 2003-07-07.
https://sourceforge.net/p/docutils/mailman/docutils-users/thread/Pine.LNX.4.44.0307070819150.2138-100000%40rnd.onego.ru/#msg4465479



---

**[feature-requests:#108] "title" option for the "image" directive**

**Status:** pending-works-for-me
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Thu Oct 17, 2024 08:23 PM UTC
**Owner:** nobody


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”">
~~~

~~~






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #108 title/tooltip option for the "image" directive

[Günter M. <mi...@us...>]

- **summary**: "title" option for the "image" directive --> title/tooltip option for the "image" directive
- **status**: pending-works-for-me --> pending



---

**[feature-requests:#108] title/tooltip option for the "image" directive**

**Status:** pending
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Mon Dec 30, 2024 03:51 PM UTC
**Owner:** nobody


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”">
~~~

~~~






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #108 title/tooltip option for the "image" directive

[Günter M. <mi...@us...>]

- **status**: pending --> pending-moreinfo
- **Comment**:

This feature requestd needs more thought and discussion -- may be a topic for an enhancement proposal.



---

**[feature-requests:#108] title/tooltip option for the "image" directive**

**Status:** pending-moreinfo
**Group:** Default
**Created:** Sun Sep 29, 2024 08:41 AM UTC by toastal
**Last Updated:** Sat Feb 15, 2025 01:35 PM UTC
**Owner:** nobody


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”">
~~~

~~~






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.