Subject: Re: bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over linked documentation

From: Y. E. <[email-masked]>
Date: Fri, 14 Jan 2022 13:11:07 +0200

> Stefan Monnier <[email-masked]> writes:

> Ah... yes, this is indeed a serious problem with the current code.
> But we should fix it rather than disable the generation of the
> HTML manual.
> [ Note that the problem also applies to Org manuals, and to the
>   `:readme`s.  ]

I'm aware of the issues reported at
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=53069 (though the second
example images are loaded fine with my setup). I looked at it because of
the images load issue coincidence. It seemed to me that changes of a
different type than discussed here would be required for that bug.

>
>> My initial idea for fixing this issue was to add a property
>> ':doc-asset', which could be configured to '(FROM . TO)' directories
>> names, then used for moving images to the 'archive-devel/doc/company/'
>> folder, as shown below:
>
> That sounds like a good plan.

After getting back to this plan, appears there's one more issue for
which I don't see a good strategy to handle.

In the final part of the 'elpaa--html-build-doc' function, it creates a
symlink to the actual HTML file; this symlink is displayed at the
package page. Naturally, putting images the suggested way ('doc-assets'
diff) works fine for the actual HTML file, but not for the symlinked.

Creating a symlinked directory, with the name(s) only one particular
package needs, in the shared '/doc/' directory doesn't look like a good
idea to me. Neither does requiring packages to comply with some naming
for the ELPA needs only.

Any advice on which approach could be suitable to handle this?

> I'd still much prefer to get the "local HTML doc" working better.

This sounds good to me.

Thinking about improving images output for Company local HTML doc, may
it become possible to allow adding small quantity per-package page
styles directly to the ELPA repository?

Having an HTML "package-name wrapper" could allow doing something like:

#pkg-company img {
    max-width: 300px;
}