From: Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
To: Y. E. <yet@ego.team>
Cc: 53205@debbugs.gnu.org
Subject: bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over linked documentation
Date: Thu, 13 Jan 2022 10:08:13 -0500 [thread overview]
Message-ID: <jwvczkvvgcx.fsf-monnier+emacs@gnu.org> (raw)
In-Reply-To: <m2pmoxfa5p.fsf@ego.team> (Y. E.'s message of "Wed, 12 Jan 2022 13:47:30 +0200")
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
next prev parent reply other threads:[~2022-01-13 15:08 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-01-12 11:47 bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over linked documentation Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-01-13 6:23 ` Lars Ingebrigtsen
2022-01-13 13:20 ` Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-01-13 15:08 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors [this message]
2022-01-14 11:11 ` Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-01-14 14:59 ` Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-09-08 13:55 ` Lars Ingebrigtsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=jwvczkvvgcx.fsf-monnier+emacs@gnu.org \
--to=bug-gnu-emacs@gnu.org \
--cc=53205@debbugs.gnu.org \
--cc=monnier@iro.umontreal.ca \
--cc=yet@ego.team \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).