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

Previous Next

Full log

Message #55 received at 73425 <at> debbugs.gnu.org (full text, mbox):

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

> Yes.  My suggestion is to allow listing additional non-.texi/.org files
> under :doc that would be copied out to the web server.  So in Eshel's
> case, we could update the specification to be
>
>  (kubed			:url "https://git.sr.ht/~eshel/kubed"
>   :doc ("kubed.texi" "images/"))

That'd be kind of a problem because `:doc` already supports a list of
strings where each string is expected to be the source file of a manual,
so the above is currently treated as a package with two manuals: one
produced from `kubed.texi` and the other from `images/`.

IOW we'd need to tweak the format a bit to avoid the ambiguity.
Maybe we can get away with just a `:doc-files` instead?

Other than that I agree.

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

- Arrange to copy those "associated files" to the `doc/<PACKAGE>/`
  subdirectory of the `archive(-devel)/` area.

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

This should make the HTML links to images work in the web versions of
the manuals.  Complements:

- Offer a way to specify part of the package specs directly in the
  package itself (presumably within the pseudo-headers of the main
  file).  Would be useful in general rather than just for "associated
  files".

- Maybe also offer some support to generate the list of associated files
  dynamically/automatically by scrubbing the generated HTML files?

There is apparently a related issue with the Info version of the manual
when the Texinfo doc is not in the root of the package dir, in which
case when the Info file is moved to the root of the package directory
(which is necessary for the code in `package.el` which adds the
package's dir in `Info-directory-list`), the links to the image
files break.  So another related change would be:

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

Beside `kubed` there's also `hyperbole` which can be used
for experiments (`hyperbole` suffers from the problem both in the web
version and in the Info version of their manual).


        Stefan

Previous Next

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