unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
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






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