#113 scale option in docutils.conf

[Aaron Schif]

I would like all the images in the generated html to have width and height attributes to prevent content flashes. This is especially important with loading: lazy. The code to do this already mostly exists, but would be automatic if only I could set a default to `scale: 100%'.

[Günter Milde]

Mind, that setting "scale" on an image/figure without explicitely set "height" and "width" starts an attempt to get the image size from the image file on the local file system. In addition to slowing down compilation time, this raises a warning for all non-available (e.g. external) image URIs.
This means, that in addition to a configuration setting we would need a convention how to override this setting so that individual images will not be read from the local file system. Something like :scale: None or :scale: False that is currently not a valid argument for the scale option. Alternatively, the special value :scale: 0 may be used.

[Aaron Schif]

Maybe an alternative would be to have a json file next to the image file that contains the image attributes. It would be simple to set width/height using a simple script and would be quick to load on build. Such a file could also be useful for setting alt text for an image (alt text should be context independent).

For a image file named kitty.png, load the optional file kitty.png.json which may contain the keys alt, height, width,loading.

I don't see how align or scale would be useful.

[Günter Milde]

This approach would add a level of complexity that makes it more suitable for an extension or a custom HTML writer than for standard Docutils.

Some alternatives come to mind:

A "simple script" could also be used to pre-process the rST source or post-process the generated HTML to add image dimensions instead of generating sidecar files.

A custom HTML writer may add image dimensions by reading from the image file for all image elements that do not have at least one of the "width", "height" or "scale" options.

An editor macro may insert a template with :width: and :height: either read from the image file or set to a fixed default. (Since [feature-requests:#102] is fixed, Docutils 0.22 will support CSS style-sheet rules to override :widht: and :height: if these use unitless values.)

[Karl O. Pinc]

On Wed, 23 Apr 2025 18:57:34 -0000
Günter Milde via Docutils-develop
docutils-develop@lists.sourceforge.net wrote:

This approach would add a level of complexity that makes it more
suitable for an extension or a custom HTML writer than for standard
Docutils.

Some alternatives come to mind:

A "simple script" could also be used to pre-process the rST source or
post-process the generated HTML to add image dimensions instead of
generating sidecar files.

FWIW, I've used the m4 macro processor
(https://www.gnu.org/software/m4/m4.html)
for pre-processing rST. With plain-old macro text substitution it's
hard to go wrong.

It is easy to be seduced and utilize more
sophisticated m4 features, conditionals, calling out to shell,
and so forth, which can lead to over-engineering.
That said, utilizing ImageMagic, it should be easy to write a
m4 macro that takes a path to an image and returns
(one of) the dimensions for substitution into the rsT source.

Regards,

Karl kop@karlpinc.com
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein

[Günter Milde]

I don't want to overburden the standard Docutils with too many features and options.
If there are questions around implementing this in an extension or external script, feel free to ask on the Docutils mail list or in private mail.
Thank you for the suggestion.