Fixing the text alternative for images in documentation

[parulin]

Hi,

I would like to review and fix the text alternatives for images in the
documentation.

From the HTML specification:

> So, in general, alternative text can be written by considering what
> one would have written had one not been able to include the image.
> [...]
> Another corollary is that the alt attribute's value should not repeat
> information that is already provided in the prose next to the image.

https://html.spec.whatwg.org/multipage/images.html#general-guidelines

I tried to list what I encountered in the docs and how I want to resolve
the issues (using "An alt Decision Tree" of WAI:
https://www.w3.org/WAI/tutorials/images/decision-tree/ ):

* some current pictures have no alt at all (i.e.: the "Screenshots"
page). Sphinx automatically generates an alt from the filename, this is
inappropriate. In the case of the "Screenshots" page, most of the
pictures are already described in the nearby text, so using an empty alt
would be enough.
* most of the diagrams have an alt (i.e. in "How to organize your
qubes") but this is not sufficient, they should have a full description
* a lot of screenshots have a description that repeats the nearby text
(i.e. in "Installation guide"). In that case, the alt should be empty.
In some situations, the alt is quite long and I think it should be part
of the nearby text instead (i.e.: "How to take screenshots and set a
wallpaper")

I would like to expand the content of the image-related sections of the
how-to and style guide to spend more time explaining why this matters
and link to the decision tree.

I know that it is not how things have been handled until now, so I'm
open to discussion.

[unman]

Thanks for raising this.
I am painfully aware of the current situation.

Some comments -
1. There should always be an Alt tag. If a screenshot is described
in nearby text, then a simple description in alt text is appropriate:
it should not be left empty. An empty Alt tag will in most cases lead
screen readers to skip that element.
2. Alt text should be concise - a sentence or two. Whether this is
consistent with your use of "full description" for diagrams is moot. I
doubt that it is. Alt text should not repeat the file name - this is
useless information (in most cases).
3. If there is a diagram, then a long description may be used. In this
case, the alt text summarises the image, (and explains that a long
description follows), and the long description should be placed below
the image/diagram. If the surrounding text already provides a description
of the diagram then a long description is not needed, but the text
should clearly identify the image to which it refers.
4. If the image is purely decorative, the Alt text can be "decorative",
a single space, or left empty. Users differ on this.
5. Where an image is functional, like some of the logos on the home
page, including the Qubes logo, the alt text should describe the
FUNCTION not the image.
6. Alt text need not include phrases like "screenshot showing", "image
of", etc.

I do not think that we need duplicate material elsewhere explaining why
this is important.

[parulin]

Thanks for your comments

On 4/12/26 12:29, 'unman' via qubes-devel wrote:
> 1. There should always be an Alt tag. If a screenshot is described
> in nearby text, then a simple description in alt text is appropriate:
> it should not be left empty. An empty Alt tag will in most cases lead
> screen readers to skip that element.

I will take an example: I don't understand how having "Boot screen"
helps the user figure out something useful while the surrounding text is
providing a description of everything meaningful in the screenshot (in
the "Installation guide").

> 4. If the image is purely decorative, the Alt text can be "decorative",
> a single space, or left empty. Users differ on this.

I learned that leaving an single space instead of using an empty alt
should be avoided. What do you mean by "users differ on this"?

> I do not think that we need duplicate material elsewhere explaining why
> this is important.

Right, but we should point contributors to good external resources
explaining that. And the current example given in the how-to contradicts
your comment #6...

[qubist]

Here is what I used for some websites in the past:

Have the image description in the image itself (metadata) and let the
CMS extract it and place it as an alt text. This is much easier for a
larger collection of images and makes handling multiple sizes easier.

[unman]

On Sun, Apr 12, 2026 at 05:04:25PM +0000, 'parulin' via qubes-devel wrote:

There's an unfortunate assumption that all users who use screen readers
are incapable of viewing images. This is not true. (I've argued this
point repeatedly across various fora with little success.)

> Thanks for your comments
>
> On 4/12/26 12:29, 'unman' via qubes-devel wrote:
> > 1. There should always be an Alt tag. If a screenshot is described
> > in nearby text, then a simple description in alt text is appropriate:
> > it should not be left empty. An empty Alt tag will in most cases lead
> > screen readers to skip that element.
>
> I will take an example: I don't understand how having "Boot screen" helps
> the user figure out something useful while the surrounding text is providing
> a description of everything meaningful in the screenshot (in the
> "Installation guide").

I agree that "Boot Screen" is inadequate alt text. But if the image
displays any worthwhile information then users should know what it is,
and have the opportunity to view it if they can. If the image does not
display worthwhile information why is it there?

>
> > 4. If the image is purely decorative, the Alt text can be "decorative",
> > a single space, or left empty. Users differ on this.
>
> I learned that leaving an single space instead of using an empty alt should
> be avoided. What do you mean by "users differ on this"?

I mean users of screen readers.
Note that even users who cannot see any images may still wish to know
they are there, even if purely decorative. (E.g for orientation on the
page when discussing with sighted users.)

>
> > I do not think that we need duplicate material elsewhere explaining why
> > this is important.
>
> Right, but we should point contributors to good external resources
> explaining that. And the current example given in the how-to contradicts
> your comment #6...

I think not . I said "need not" , not "should not".

In any case, a more immediate issue is that currently many images are
rendered as links: the link text is taken from the alt text, and the
target is the source file. So readers generate "link", not "image" 0
definitely sub-optimal.

[parulin]

On 4/16/26 12:23, 'unman' via qubes-devel wrote:
> In any case, a more immediate issue is that currently many images are
> rendered as links: the link text is taken from the alt text, and the
> target is the source file. So readers generate "link", not "image" 0
> definitely sub-optimal.

Thanks A LOT for pointing this issue.

The way Sphinx and Docutils treat images and links has many flaws. When
an image is inside a link without any text, the alternative text should
describe the link function, not the image. So even with a non-empty alt,
that's not a good situation. It is of course worse with empty alts.

One solution could be to edit the build process with a custom extension:

* remove the link that Sphinx adds on top of the image
* add a new link **after** the image node

The following is a snippet to show how it would be possible. I would
like to know if it would be an acceptable solution before finishing it.
Copy-pasting it at the end of conf.py is a simple way to test the code:

from sphinx.application import Sphinx
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.util.typing import ExtensionMetadata

from docutils import nodes

import posixpath

class FixStandaloneHTMLBuilder(StandaloneHTMLBuilder):
name = "html"
html_scaled_image_link = False

def post_process_images(self, doctree: Node) -> None:
super().post_process_images(doctree)

for node in doctree.findall(nodes.image):
if not any((key in node) for key in ("scale", "width",
"height")):
continue
if isinstance(node.parent, nodes.reference):
continue
if "no-scaled-link" in node["classes"]:
continue

uri = node["uri"]

parent = nodes.paragraph("")
reference = nodes.reference("", f"Link to {node['uri']}",
internal=True)
parent.append(reference)

if uri in self.images:
reference["refuri"] = posixpath.join(self.imgpath,
self.images[uri])
else:
reference["refuri"] = uri

node.parent.append(parent)


def setup(app: Sphinx) -> ExtensionMetadata:
app.add_builder(FixStandaloneHTMLBuilder, override=True)

return {
"version": "0.1",
"env_version": 1,
"parallel_read_safe": True,
"parallel_write_safe": True,
}