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

From: Robert Weiner <[email-masked]>
Date: Fri, 18 Apr 2025 23:05:12 -0400

Hi Stefan:

For Hyperbole with regard to use of our hyperbole.css file, if you prefer
that all the Elpa manuals use the same css, then that is fine with us.  The
main reason for our new css file was to add a decent style for reading the
manual on mobile phone-sized devices, but the Elpa css seems to work fine
there now, so no issue there.

Cheers,

Bob

On Fri, Apr 18, 2025 at 6:57 PM Stefan Monnier <[email-masked]>
wrote:

> >  - We use another css which is stored on the same level as the
> texi-file, in
> >    the man-folder. The css is missed and a "standard" css is used
> instead. So
> >    the formatting is not the expected but it is not bad.
>
> We use our own CSS for all the Texinfo manuals, indeed.
> [ Well, it's not exactly "our own", it's stolen from
>   www.gnu.org/software, IIRC.  ]
>
> >    I guess having different css for each package will add some extra
> >    complexity, it has to be passed to the texinfo command line I think,
> but
> >    might be possible to support? WDYT?
>
> I think it heavily depends on the purpose.  If your CSS has something
> specific to Hyperbole, then it would be nice to support that in some
> way, but otherwise it seems better to use the same CSS for all the
> (Non)GNU ELPA manuals.
>
> >  - I got the impression that the images would be copied to a flat
> >    structure. Looking in the generated html it looks like the file
> structure
> >    is kept. Was that the intention?
> >
> >    Example: <img name="Hyperbole Screenshot"
> src="hyperbole/man/im/hyperbole-cv.png">
> >
> >    That src works so it is fine. Just want to check that there is no
> >    unintended magic going on here.
>
> I wrote the code under the assumption that the HTML would use file names
> relative that "work in place", i.e. that are relative to the location of
> the source file.  For that reason, the files are copied in a way that
> tries to preserve the directory structure.  This hopefully also avoids
> name conflicts.
>
> >>> - Make sure the links to associated files work also for the Info
> >>>   versions of the manuals, even when they're moved to the
> >>>   root directory.
> >> Not there yet either.
> > For hyperbole it should work to lift the "man/im" folder one level up.
> No need
> > to manipulate the texi nor info files for that. Just keep the relative
> > distance and install them one level up. Is that what you are planning to
> do?
>
> I haven't looked closely, but it's one of the options I'd consider, yes.
> Currently for the HTML, I do a search&replace directly on the HTML (in
> a naive way, sadly), but it's not so easy to do on the Info file because
> it contains "inner pointers" which would need to be adjusted.
>
> Moving the image files like you propose would avoid that problem, but it
> comes with another downside: it would break the references to those same
> image files contained in the HTML and Texinfo manual bundled in the
> tarball.  To get both to work correctly, we'd need to *copy* (rather
> than move) those files, which would bloat the tarball a bit more.
>
> Another option is to modify the Texinfo before we generate the Info.
> This seems more cumbersome to do with the current code but would avoid
> both of those problems.
>
> The overall cleaner option might be not to move the Info file.
> It's currently not supported by the ELPA protocol, so we'd have to "do
> it by hand".  This means adding code in the `<PKG>-autoloads.el` file to
> tweak `Info-directory-list`, but since we don't get to generate the
> `<PKG>-autoloads.el` ourselves, we'd have instead to tweak some *other*
> file so as to cause the end-user's Emacs to generate a `<PKG>-autoloads.el`
> with the appropriate tweak to `Info-directory-list`.  🙁
>
>
>         Stefan
>
>