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

From: Stefan Monnier <[email-masked]>
Date: Mon, 23 Sep 2024 10:00:00 -0400

>> How do we generate these HTML files from the Texinfo sources?
>
> Basically by executing,
>
> --8<---------------cut here---------------start------------->8---
> makeinfo --no-split [input-name] -o [output-name] --html --css-ref=[css-url]
> --8<---------------cut here---------------end--------------->8---
>
>>> plus the manual under https://elpa.gnu.org/packages/doc/[package name]
>>
>> So we have the HTML docs in two places?  Why two?  And why do I see
>> both https://elpa.gnu.org/packages/doc/compat.html and
>> https://elpa.gnu.org/packages/doc/compat/compat.html?
>
> I am not sure, my suspicion is some kind of historical backwards
> compatibility.  I have CC'ed Stefan who might know more.

On disk, this is only one place: the `doc/compat.html` is a symlink to
`doc/compat/compat.html`.  The only URL we want to expose is
the `doc/compat.html`, OTOH (which is why `doc/compat.html` is a symlink
rather than an HTTP redirect).

The reason is the following:

- We put all the generated files into the `doc/PKG/` subdir so we know
  which files belong to which package when we need to "garbage collect"
  old files when updating a package.
- We need to the URL to be `doc/compat.html` (i.e. include only the
  manual name but not the package name) so that links from one
  manual to the other work correctly regardless if the other manual
  belongs to the same package or not.

        Stefan