[Docutils-develop] Proposal: removing the fallback alt-text for inline images

[James A. <ja...@jp...>]

Hi docutils developers,

Before potentially submitting a patch, I'd like to sense-check a
possible adjustment to the way that docutils handles alt-text for
inline images[1] in rST documents.

Currently, when an inline image (itself a substitution reference) that
lacks a configured :alt: option is parsed, then the substitution's
name - the text enclosed by pipe symbols - is included as the alt text
on the resulting image node.

This behaviour is demonstrated by corresponding parser test coverage[2].

The change I'd like to suggest is that the alt-text be omitted from
inline images in cases where it is not explicitly set as an option.
In other words: to remove the fallback value of the substitution name.

The reasoning for the change is that although the substitution name
_may_ in some cases provide a valuable, accessible alt-text, that
positive outcome relies upon the documentation authors being aware of
the alt text selection behaviour and adopting an appropriate
substitution naming scheme.  Contrastingly, using the :alt: option
directly is better-documented and more explicit.

However: this could be a controversial or disruptive change, and I'd
be particularly glad to hear from anyone with accessibility-related
opinions, and anyone with thoughts about whether configuration/gradual
migration would make sense.


For anyone curious: my eventual objective here is one or two steps
removed from docutils -- I would like Jupyter notebooks rendered using
nbsphinx to be output deterministically.  The internals of nbsphinx
emit ephemeral (randomized) substitution names in the rST it produces
when it encounters images in the input markdown it parses - and those
ephemeral identifiers in turn produce nondeterminism (and likely poor
accessibility) in the HTML output because docutils embeds them into
img alt attribute values.  If further context is of interest, please
see the the Debian bugreport[3] where I discovered this behaviour, and
the followup discussion on a related GitHub nbsphinx issue thread[4].

Thank you and please let me know if I can clarify anything about the
suggestion and/or reasoning for it.

Regards,
James

[1] - https://docutils.sourceforge.io/docs/ref/rst/directives.html#image

[2] - https://sourceforge.net/p/docutils/code/9553/tree/trunk/docutils/test/test_parsers/test_rst/test_substitutions.py#l52

[3] - https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1064575

[4] - https://github.com/spatialaudio/nbsphinx/pull/438