Subject: bug#73425: 31.0.50; Support images in HTML versions of ELPA package manuals

From: Eshel Yaron <[email-masked]>
Date: Sat, 19 Apr 2025 09:10:58 +0200

Hi Stefan,

Stefan Monnier <[email-masked]> writes:

>> AFAICT, the plan is as follows:
>>
>> - Add support in package specs for "associated files" for each of the
>>   manuals (ideally also for the `:readme`, BTW).
>
> OK, I added a `:doc-files` thingy.
> Currently it can be a list of file or dir names, and if it's a dir we
> copy all the files in it (but not recursively).
>
>> - Arrange to copy those "associated files" to the `doc/<PACKAGE>/`
>>   subdirectory of the `archive(-devel)/` area.
>
> Done.
>
>> - Massage the HTML files so that `href="snapshot.png"` becomes
>>   `href="<PACKAGE>/snapshot.png"`.  For the `:readme` case, we should
>>   instead redirect them to `doc/<PACKAGE>/snapshot.png`.
>
> Done to some extent but I'm not completely sure what to do with the
> Kubed manual (and I haven't looked at the `:readme` case at all).
>
> Eshel: could you explain to me the "/assets" thingy in the references
> to images in the Texi (and resulting HTML)?

So currently the way we include images in kubed.texi is as follows:

--8<---------------cut here---------------start------------->8---
@ifhtml
@float
@image{/assets/kubed-overview,,,Image: Four different kinds of Kubed buffers in Emacs,.png}
@caption{Pods, logs, shells, YAMLs, all in one integrated interface}
@end float
@end ifhtml
--8<---------------cut here---------------end--------------->8---

This refers to https://eshelyaron.com/assets/kubed-overview.png

I'd love to change these references to relative paths so they also work
on the ELPA server, but I'm still not sure how to do that: we provide
the manual at https://eshelyaron.com/kubed.html (all nodes in one page)
and at https://eshelyaron.com/man/kubed/ (each node in a separate page).
The image references need to work from these two different locations.
That's easy to do with absolute references.  With relative references,
not so much...  It would be nice if Texinfo allowed us to use different
references depending on whether or not "--no-split" is in effect, but I
couldn't find such an option. 

Any ideas/suggestions?

>> This should make the HTML links to images work in the web versions of
>> the manuals.
>
> And indeed it seems to work for Hyerpbole.
> Mats&Robert: please check http://elpa.gnu.org/devel/doc/hyperbole.html

Cool!

Eshel