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

[Stefan Monnier]

Hi,

Yay!  More people working on `elpa-admin.el`!

> +** =:doc-html=
> +By default, if =:doc= specification contains a Texinfo file, then HTML
> +documentation is generated from it; the link to the generated HTML
> +file is added to the package page.  To disable this behavior, set
> +=:doc-html= to ~ignore~.

Hmm... why would you want to disable it?

> +** =:resoures LINKS=
> +Enables 'Additional Resources' section on the package page.  This must
> +be an association list of the titles and URLs of online resources.
> +For example:
> +
> +    (("User Manual" . "https://example.tld/manual.html";))

Could you give more context as for why we want this?
More specifically, the `:readme` file can already contain links to other
places, so I'm not sure why we need special support for it here
(especially since the :readme file is much more flexible and can be
changed without write access to `elpa.git`).

> I was pleased to see that automatic generation but there were two issues
> (namely, images and styles).
>
> The user manual for Company is shipped with the images; and it is
> currently impossible to configure the addition of them to the
> 'elpaa--doc-subdirectory'.

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

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

> That worked fine during my tests but thinking about how to apply CSS
> styles to the manual (including to control the size of the shown
> images), I've got the second idea: Company already has an online version
> of the user manual with all the proper styles and images in place, so
> why not link directly to it?

There are various reasons why this would not be a good solution.
One Lars already mentioned the issue of the version that may not match,
another one is that some packages don't have such a separate web page.

> I also attach a version with a bit different (IMO less robust/clear)
> approach.  It introduces/uses one new property instead: ':doc-links'.

FWIW, I like this approach better than the first patch, tho I'd still
much prefer to get the "local HTML doc" working better.


        Stefan