GNU bug report logs - #73425
31.0.50; Support images in HTML versions of ELPA package manuals

Previous Next

Full log

View this message in rfc822 format

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Mats Lidell <matsl <at> gnu.org>
Cc: Philip Kaludercic <philipk <at> posteo.net>, Robert Weiner <rswgnu <at> gmail.com>, me <at> eshelyaron.com, Eli Zaretskii <eliz <at> gnu.org>, 73425 <at> debbugs.gnu.org
Subject: bug#73425: 31.0.50; Support images in HTML versions of ELPA package manuals
Date: Fri, 18 Apr 2025 18:57:44 -0400

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.