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

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

Dear James,

thank you for posting your suggestion and the rationale.

On 2024-03-09, James Addison via Docutils-develop wrote:
> 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].

It is in line with the general idea of reStructuredText markup:

  reStructuredText is plaintext that uses simple and intuitive constructs
  to indicate the structure of a document. These constructs are equally
  easy to read in raw and processed forms.

  -- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html

The idea is that authors use reference names for hyperlinks and
substitutions that make the text easy to comprehend in raw form as well as
in output formats that do not support hyperlinks or images (e.g. man
pages).

> 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.

In the general case, the fallback does not impair accessibility:

Authors that do not (need to) care about accessibility get an "alt" value
that is just as readable as the source.

Authors that care about accessibility but are not aware of the fallback
specify an :alt: value for all images.

"Caring experts" use the :alt: option directly for descriptions requiring
a phrase. In cases where a `simple reference name`_ can adequately
describe the image, the fallback saves these authors from duplicating the
substitution name as :alt: value. They will complain if the fallback
were removed.

.. _simple reference name:
   https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#simple-reference-name

...

> 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.
...
> [4] - https://github.com/spatialaudio/nbsphinx/pull/438

IMO, the particular use case of an auto-generated rST source with
pseudo-random substitution names does not merit dropping the :alt:
fallback.

I see several alternative solutions/workarounds for this problem, e.g.

* Use a deterministic substitution name (e.g. the image URI).

* Use a `3rd party markdown parser`__ to convert "markdown" input
  directly into a document tree
  (cf. https://github.com/spatialaudio/nbsphinx/issues/36).

  __ https://docutils.sourceforge.io/docs/user/config.html#parser

with kind regards,

Günter