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

Previous Next

Full log

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Y. E. <yet <at> ego.team>
Cc: 53205 <at> debbugs.gnu.org
Subject: Re: bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over
 linked documentation
Date: Thu, 13 Jan 2022 10:08:13 -0500

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

Previous Next

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