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

From: Eshel Yaron <[email-masked]>
Date: Sun, 22 Sep 2024 20:13:52 +0200

Philip Kaludercic <[email-masked]> writes:

> Eli Zaretskii <[email-masked]> writes:
>
>>> Cc: Philip Kaludercic <[email-masked]>
>>> Date: Sun, 22 Sep 2024 18:06:16 +0200
>>> From:  Eshel Yaron via "Bug reports for GNU Emacs,
>>>  the Swiss army knife of text editors" <[email-masked]>
>>> 
>>> I'm opening this feature request following a discussion with Philip
>>> elsewhere: Texinfo manual can include images, but AFAIK (and please
>>> correct me if I'm wrong here) there's currently no way for ELPA packages
>>> to include images in their manuals and have these images appear also in
>>> the HTML version of the manual that the ELPA server builds and serves.
>>
>> Why "no way"?  If the image files are present at their filenames as
>> mentioned by the HTML version of the documentation, they will be shown
>> by the browser.
>
> The issue is that when generating the HTML documentation for
> elpa.gnu.org, we don't copy out any files, but just generate the HTML
> version of the manual.
>
> What we need is some kind of an indication in the package specification,
> what files should be copied out for the manual to access, as otherwise
> the images would only be hidden in the package tarball, that a web
> browser cannot access (AFAIK).

Yes.

>>> An example is my GNU ELPA package Kubed.  In the development version,
>>> the manual refers to images which are present on my web server, where I
>>> provide HTML versions[1][2] of the manual.  There, the images are
>>> displayed properly.  
>
>   Unrelated to this issue, have you considered rendering screenshots as
>   SVG files using `x-export-frames'?

I haven't, but I'll be sure to check it out.  Thanks for the tip :)

>>> On the ELPA server[3], OTOH, the images are nowhere
>>> to be found, and we instead get just the alt text and caption.  That's
>>> expected, but the alt text is shown with no distinctive styling so the
>>> result seems quite confusing.
>>
>> To show images, your HTML version of the manual should reference local
>> files, not URLs from your some other server.  And, of course, the
>> image files should be part of the package tarball.
>>
>>> - Include images in the package repository, somehow indicate in the
>>>   package specification that the manual refers to these images, and have
>>>   the ELPA server keep the images around in a predictable location, so I
>>>   can link to it from the manual.
>>
>> I don't understand why this would be needed.  Simply include the image
>> files with the package, and the rest should "just work", AFAIU.
>
> Do you know if TeXinfo has an option to inline images?  If the
> "makeinfo" command could somehow generate data: urls when exporting
> images, then this could be very easily solved.

I'm not aware of such an option.  BTW, which version of Texinfo does the
ELPA server run?

Thanks,

Eshel