From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over linked documentation Date: Thu, 13 Jan 2022 10:08:13 -0500 Message-ID: References: Reply-To: Stefan Monnier Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="29902"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) Cc: 53205@debbugs.gnu.org To: Y. E. Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Jan 13 16:14:29 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1n81o3-0007Zt-Q5 for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 13 Jan 2022 16:14:28 +0100 Original-Received: from localhost ([::1]:59752 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n81o2-0003JV-OA for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 13 Jan 2022 10:14:26 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:48918) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n81io-0005AM-Ky for bug-gnu-emacs@gnu.org; Thu, 13 Jan 2022 10:09:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:41338) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1n81io-0004mC-8Y for bug-gnu-emacs@gnu.org; Thu, 13 Jan 2022 10:09:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1n81in-0004Lx-VF for bug-gnu-emacs@gnu.org; Thu, 13 Jan 2022 10:09:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Monnier Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 13 Jan 2022 15:09:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 53205 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 53205-submit@debbugs.gnu.org id=B53205.164208651516691 (code B ref 53205); Thu, 13 Jan 2022 15:09:01 +0000 Original-Received: (at 53205) by debbugs.gnu.org; 13 Jan 2022 15:08:35 +0000 Original-Received: from localhost ([127.0.0.1]:34241 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n81iM-0004L9-VU for submit@debbugs.gnu.org; Thu, 13 Jan 2022 10:08:35 -0500 Original-Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:62186) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n81iK-0004Kp-7Y for 53205@debbugs.gnu.org; Thu, 13 Jan 2022 10:08:33 -0500 Original-Received: from pmg3.iro.umontreal.ca (localhost [127.0.0.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id 1B867442387; Thu, 13 Jan 2022 10:08:26 -0500 (EST) Original-Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg3.iro.umontreal.ca (Proxmox) with ESMTP id 18B0B44026D; Thu, 13 Jan 2022 10:08:24 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1642086504; bh=j7k8dGG0mI0YtZ4T4O7voiWGfBqZThpeCosmQtCK+ZE=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=Ix9QxdFYsaxRV0xg1ULB0yS8MdryE1dtYk3hv243LofFkR3K599jSf0jx7B9QyQP2 a1lq8MT8AXs3e+b4dp3thV1f3NzvicJhD8GcyTOk8G8Dwicfbwwy3rVXQffTtG6pEU nxtJMzPup7482vCP2Vt50qzi0b142EkZNBtdkHBeAUCt+IISilWh9+0mJPYH9uvSkN LXORs0sN/hELBz8teq1AApVHpoXL3LqeCGNqVT1Dmq+Ek37d/2SUNJ2zTNez+XkEbw 8bUiJ1riO1rOHVaTGtgRRw6LAYuMQ6L17VLTeMsw3mhGNNNe11Am4LLFHsu1OApS2t h+oEB243n417w== Original-Received: from ceviche (unknown [216.154.30.173]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id DA27A12077C; Thu, 13 Jan 2022 10:08:23 -0500 (EST) In-Reply-To: (Y. E.'s message of "Wed, 12 Jan 2022 13:47:30 +0200") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:224116 Archived-At: 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