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

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: emacs; Reported by: "Y. E." <yet@HIDDEN>; Keywords: patch; dated Wed, 12 Jan 2022 11:48:01 UTC; Maintainer for emacs is bug-gnu-emacs@HIDDEN.

Message received at 53205 <at> debbugs.gnu.org:


Received: (at 53205) by debbugs.gnu.org; 13 Jan 2022 13:20:31 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Jan 13 08:20:31 2022
Received: from localhost ([127.0.0.1]:60478 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1n801n-0006sN-51
	for submit <at> debbugs.gnu.org; Thu, 13 Jan 2022 08:20:31 -0500
Received: from out0.migadu.com ([94.23.1.103]:55520)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <yet@HIDDEN>) id 1n801k-0006sB-LP
 for 53205 <at> debbugs.gnu.org; Thu, 13 Jan 2022 08:20:29 -0500
X-Report-Abuse: Please report any abuse attempt to abuse@HIDDEN and
 include these headers.
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ego.team; s=key1;
 t=1642080027; h=from:from:reply-to:reply-to:subject:subject:date:date:
 message-id:message-id:to:to:cc:cc:mime-version:mime-version:
 content-type:content-type:in-reply-to:in-reply-to;
 bh=sGxopdXYn6vfdyegXdYwxGN8U8Xf0TKf3CZTmfNYsrA=;
 b=vN5v2iKdktfukMd63+Ggw54dYxcbbwLXpQYzrw0Uu2RpkfxGklPCyoaJa7e+P4BGpeJzUh
 dBujC4f63sGM2slXSw/U48IszNaTeoRuXL93pr0g8Zpv/7Bzrs1ccYS0zcd3nBubReXuBw
 MagkNBmE2VjEzv0q19m69YcsfZWQcr4=
From: Y. E. <yet@HIDDEN>
To: Lars Ingebrigtsen <larsi@HIDDEN>
Subject: Re: bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over
 linked documentation
In-Reply-To: <871r1c9mrr.fsf@HIDDEN> (message from Lars Ingebrigtsen on
 Thu, 13 Jan 2022 07:23:52 +0100)
Date: Thu, 13 Jan 2022 15:20:25 +0200
Message-ID: <m2ilunu606.fsf@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain
X-Migadu-Flow: FLOW_OUT
X-Migadu-Auth-User: ego.team
X-Spam-Score: -0.7 (/)
X-Debbugs-Envelope-To: 53205
Cc: yet@HIDDEN, 53205 <at> debbugs.gnu.org, monnier@HIDDEN
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Reply-To: "Y. E." <yet@HIDDEN>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.7 (-)

>Lars Ingebrigtsen <larsi@HIDDEN> writes:

>> Y. E. <yet@HIDDEN> writes:
>>
>> 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:
>
> I think that sounds OK...

Fine by me, though with a workaround to apply custom styles. The
generated plain HTML outputs images as is, which doesn't look well in
the described case.

>
>> 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?
>
> [...]
>
>>   :doc-html ignore
>>   :resources (("User Manual" . "https://company-mode.github.io/manual/index.html"))
>
> Well, the user wants to see the version of the manual that corresponds
> to the version of the package they have installed, so just redirecting
> them to an external web page doesn't seem very useful?  But perhaps I'm
> misunderstanding the proposal.  (And I'm adding Stefan to the CCs;
> perhaps he has some comments.)

I agree, this is a good point. Currently, the most recent version of the
manual is displayed at Company website. But it's planned to output the
stable version there in the future. So, yes, it would be nice/convenient
to have a development version generated at GNU ELPA.




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#53205; Package emacs. Full text available.

Message received at 53205 <at> debbugs.gnu.org:


Received: (at 53205) by debbugs.gnu.org; 13 Jan 2022 06:24:11 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Jan 13 01:24:11 2022
Received: from localhost ([127.0.0.1]:59795 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1n7tWs-0003eX-G1
	for submit <at> debbugs.gnu.org; Thu, 13 Jan 2022 01:24:10 -0500
Received: from quimby.gnus.org ([95.216.78.240]:50164)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <larsi@HIDDEN>) id 1n7tWm-0003dt-AB
 for 53205 <at> debbugs.gnu.org; Thu, 13 Jan 2022 01:24:09 -0500
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org;
 s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date:
 References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding:
 Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender:
 Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:
 List-Subscribe:List-Post:List-Owner:List-Archive;
 bh=heOevoOHca1ZEYwejg93DzKXN15Lbpsh2Eea3+8dYqE=; b=IN4utzPTF8XzsHZUtdrieP1Xo9
 6TgN35eV8XuyDGGS7IUssDMfs2myqDlBHeL9HF7sSVswKTiLxE/wvqs0yHOvyQGmCNwv/J5gqsG/9
 YEJPKhqPFDaxeIoF4DF7B/vDxnGOLuC0LCQ/BMjN8cIRPPWG8s/mmOJCAvkZ+hAbD/aI=;
Received: from [84.212.220.105] (helo=xo)
 by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.92) (envelope-from <larsi@HIDDEN>)
 id 1n7tWc-000885-5V; Thu, 13 Jan 2022 07:23:57 +0100
From: Lars Ingebrigtsen <larsi@HIDDEN>
To: Y. E. <yet@HIDDEN>
Subject: Re: bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over
 linked documentation
References: <m2pmoxfa5p.fsf@HIDDEN>
X-Now-Playing: James White & The Blacks's _Second Chance_: "Almost Black"
Date: Thu, 13 Jan 2022 07:23:52 +0100
In-Reply-To: <m2pmoxfa5p.fsf@HIDDEN> (Y. E.'s message of "Wed, 12 Jan 2022
 13:47:30 +0200")
Message-ID: <871r1c9mrr.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org",
 has NOT identified this incoming email as spam.  The original
 message has been attached to this so you can view it or label
 similar future email.  If you have any questions, see
 @@CONTACT_ADDRESS@@ for details.
 Content preview:  Y. E. <yet@HIDDEN> writes: > 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/comp [...] 
 Content analysis details:   (-2.9 points, 5.0 required)
 pts rule name              description
 ---- ---------------------- --------------------------------------------------
 -1.0 ALL_TRUSTED            Passed through trusted hosts only via SMTP
 -1.9 BAYES_00               BODY: Bayes spam probability is 0 to 1%
 [score: 0.0000]
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 53205
Cc: 53205 <at> debbugs.gnu.org, Stefan Monnier <monnier@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)

Y. E. <yet@HIDDEN> writes:

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

I think that sounds OK...

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

[...]

>   :doc-html ignore
>   :resources (("User Manual" . "https://company-mode.github.io/manual/index.html"))

Well, the user wants to see the version of the manual that corresponds
to the version of the package they have installed, so just redirecting
them to an external web page doesn't seem very useful?  But perhaps I'm
misunderstanding the proposal.  (And I'm adding Stefan to the CCs;
perhaps he has some comments.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#53205; Package emacs. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 12 Jan 2022 11:47:42 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Jan 12 06:47:42 2022
Received: from localhost ([127.0.0.1]:56351 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1n7c6P-00010Y-L1
	for submit <at> debbugs.gnu.org; Wed, 12 Jan 2022 06:47:42 -0500
Received: from lists.gnu.org ([209.51.188.17]:47276)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <yet@HIDDEN>) id 1n7c6O-00010M-9g
 for submit <at> debbugs.gnu.org; Wed, 12 Jan 2022 06:47:40 -0500
Received: from eggs.gnu.org ([209.51.188.92]:59140)
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <yet@HIDDEN>) id 1n7c6N-0005XU-GT
 for bug-gnu-emacs@HIDDEN; Wed, 12 Jan 2022 06:47:40 -0500
Received: from out0.migadu.com ([94.23.1.103]:21287)
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <yet@HIDDEN>) id 1n7c6J-0006Lx-Q4
 for bug-gnu-emacs@HIDDEN; Wed, 12 Jan 2022 06:47:39 -0500
X-Report-Abuse: Please report any abuse attempt to abuse@HIDDEN and
 include these headers.
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ego.team; s=key1;
 t=1641988051; h=from:from:reply-to:reply-to:subject:subject:date:date:
 message-id:message-id:to:to:cc:mime-version:mime-version:
 content-type:content-type; bh=W+WP6yLr0zEaSaa0Pnzi11f8mdd+nttsEezER6yN05o=;
 b=bY7p7FDRoQbkJyDijEPJX1x59gmeFvFA188hFc9jU2L3q0aMvGSQ6Nov0iEPCa8wJArcSw
 vlBCPm1YaMZ+z8fSKr2jAvnNAgUX1daKED/WXFLKNoRNL38slT7UgVwUgzr5sZYxR+J+fT
 AuLwvHk4J/wxtCuXGWZwnvYdeRGm5uI=
From: Y. E. <yet@HIDDEN>
To: bug-gnu-emacs@HIDDEN
Subject: 28.0.90; [PATCH] GNU ELPA: Provide more control over linked
 documentation
Date: Wed, 12 Jan 2022 13:47:30 +0200
Message-ID: <m2pmoxfa5p.fsf@HIDDEN>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="=-=-="
X-Migadu-Flow: FLOW_OUT
X-Migadu-Auth-User: ego.team
Received-SPF: pass client-ip=94.23.1.103; envelope-from=yet@HIDDEN;
 helo=out0.migadu.com
X-Spam_score_int: -27
X-Spam_score: -2.8
X-Spam_bar: --
X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
 DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,
 RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_NONE=0.001,
 SPF_PASS=-0.001 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-Spam-Score: -1.4 (-)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Reply-To: "Y. E." <yet@HIDDEN>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -2.4 (--)

--=-=-=
Content-Type: text/plain

The introductory text is longish, so if no additional context is needed,
please see the following attached patches:

- 0001-Provide-more-control-over-linked-documentation.patch

- 0001-README-doc-html-resources-Document-new-properties.patch


--=-=-=
Content-Type: text/x-patch
Content-Disposition: attachment;
 filename=0001-Provide-more-control-over-linked-documentation.patch
Content-Description: Provide more control over linked documentation

From 834f01f267f2f8ab677d0de33e12034c06dbabd6 Mon Sep 17 00:00:00 2001
From: YugaEgo <yet@HIDDEN>
Date: Wed, 12 Jan 2022 12:24:09 +0200
Subject: [PATCH] Provide more control over linked documentation

* README: (:doc-html, :resources): Document new properties.
* elpa-admin.el (elpaa--html-insert-resources): New function.
(elpaa--html-make-pkg): Use new function.
(elpaa--build-Info-1): Do not generate HTML doc if :doc-html is
'ignore'.
---
 README        | 13 +++++++++++++
 elpa-admin.el | 12 +++++++++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/README b/README
index a0e34ff78c..b83e8dfd1a 100644
--- a/README
+++ b/README
@@ -146,6 +146,19 @@ Name of the documentation file for the package.
 It can be either an Info file, a Texinfo file, or an Org file.
 FILE can also be a list of those.
 
+** =: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~.
+
+** =: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"))
+
 ** =:make TARGET=
 Indicates that we should run ~make TARGET~ in order to build some files.
 This is run before processing =:doc=, so it can be used to generate
diff --git a/elpa-admin.el b/elpa-admin.el
index d570c3c6aa..c09e22241d 100644
--- a/elpa-admin.el
+++ b/elpa-admin.el
@@ -1469,6 +1469,13 @@ arbitrary code."
 	  ))
       (insert "</dd>\n"))))
 
+(defun elpaa--html-insert-resources (pkg-spec)
+  (when-let ((links (elpaa--spec-get pkg-spec :resources)))
+    (insert "<dt>Additional Resources</dt> <dd>\n")
+    (dolist (link links)
+      (insert "<a href=\"" (cdr link) "\">" (car link) "</a>\n"))
+    (insert "</dd>\n")))
+
 (defun elpaa--html-make-pkg (pkg pkg-spec files srcdir)
   (let* ((name (symbol-name (car pkg)))
          (latest (package-version-join (aref (cdr pkg) 0)))
@@ -1517,6 +1524,7 @@ arbitrary code."
            (elpaa--get-prop "URL" name srcdir mainsrcfile)))
       (insert (format "<dt>Badge</dt><dd><img src=\"%s.svg\"/></dd>\n" (elpaa--html-quote name)))
       (elpaa--html-insert-docs pkg-spec)
+      (elpaa--html-insert-resources pkg-spec)
       (insert "</dl>")
       (insert (format "<p>To install this package, run in Emacs:</p>
                        <pre>M-x <span class=\"kw\">package-install</span> RET <span class=\"kw\">%s</span> RET</pre>"
@@ -2106,7 +2114,9 @@ relative to elpa root."
            t "makeinfo" "--no-split" docfile "-o" info-file)
           (message "%s" (buffer-string)))
 
-	(when html-dir (elpaa--html-build-doc pkg-spec docfile html-dir))
+        (let ((doc-html (elpaa--spec-get pkg-spec :doc-html)))
+          (when (and html-dir (not (equal doc-html 'ignore)))
+            (elpaa--html-build-doc pkg-spec docfile html-dir)))
 
         (setq docfile info-file)))
 
-- 
2.34.1


--=-=-=
Content-Type: text/x-patch
Content-Disposition: attachment;
 filename=0001-README-doc-html-resources-Document-new-properties.patch
Content-Description: README file changes for the 'main' branch

From ab2394e3c3816deb85aaa241d0b341b2fc7a5fea Mon Sep 17 00:00:00 2001
From: YugaEgo <yet@HIDDEN>
Date: Wed, 12 Jan 2022 12:31:30 +0200
Subject: [PATCH] * README (:doc-html, :resources): Document new properties

---
 README | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/README b/README
index f05e9e58ac..eafe517fac 100644
--- a/README
+++ b/README
@@ -184,6 +184,19 @@ Name of the documentation file for the package.
 It can be either an Info file, a Texinfo file, or an Org file.
 FILE can also be a list of those.
 
+** =: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~.
+
+** =: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"))
+
 ** =:make TARGET=
 Indicates that we should run ~make TARGET~ in order to build some files.
 This is run before processing =:doc=, so it can be used to generate
-- 
2.34.1


--=-=-=
Content-Type: text/plain



I've been locally testing configuration for Company documentation (to
add it to GNU ELPA) and noticed that an HTML version of the manual is
automatically generated from the '.texi' file. The generated HTML file
is linked under the label 'Manual' on the package page and served from
the 'archive-devel/doc/company/' directory.

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

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:

#+BEGIN_SRC diff
diff --git a/elpa-admin.el b/elpa-admin.el
index d94cc7fd73..23bb582ceb 100644
--- a/elpa-admin.el
+++ b/elpa-admin.el
@@ -1999,7 +1999,11 @@ directory; one of archive, archive-devel."
 	    (expand-file-name elpaa--doc-subdirectory tarball-dir)))))
     (when html-dir
       (when (not (file-readable-p html-dir)) ;FIXME: Why bother testing?
-	(make-directory html-dir t)))
+	    (make-directory html-dir t))
+      (when-let ((assets (elpaa--spec-get pkg-spec :doc-assets)))
+        (cl-loop for (from . to) in assets
+                 do (rename-file (expand-file-name from dir)
+                                 (expand-file-name to html-dir) t))))

     (plist-put (cdr pkg-spec) :internal--html-docs nil)
     (dolist (f docfiles)
-- 
2.34.1
#+END_SRC

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?

So, the suggested patch provides a way to do that. It introduces and
uses two new properties: ':doc-html' and ':resources'.

With it, for example, Company setup could be configured this way:

#+BEGIN_SRC lisp
("company"
  :url "https://github.com/company-mode/company-mode.git"
  :shell-command "mkdir images; mv doc/images/small images/"
  :doc "doc/company.texi"
  :doc-html ignore
  :resources (("User Manual" . "https://company-mode.github.io/manual/index.html"))
  :auto-sync t)
#+END_SRC


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



--=-=-=
Content-Type: text/x-patch
Content-Disposition: attachment;
 filename=0001-Add-doc-links-property-to-specifications.patch
Content-Description: Add :doc-links property to specifications

From c470c6a669c395d82247d79fa3be0084727bb8e3 Mon Sep 17 00:00:00 2001
From: YugaEgo <yet@HIDDEN>
Date: Tue, 11 Jan 2022 03:05:37 +0200
Subject: [PATCH] Add ':doc-links' property to specifications

Provide control over documentation linked from package page.

* elpa-admin.el (elpaa--html-insert-docs, elpaa--build-Info-1):
Utilize new property.
* README (:doc-links): Usage instructions.
---
 README        | 10 ++++++++++
 elpa-admin.el | 51 +++++++++++++++++++++++++++++++--------------------
 2 files changed, 41 insertions(+), 20 deletions(-)

diff --git a/README b/README
index a0e34ff78c..dd5d9aef41 100644
--- a/README
+++ b/README
@@ -146,6 +146,16 @@ Name of the documentation file for the package.
 It can be either an Info file, a Texinfo file, or an Org file.
 FILE can also be a list of those.
 
+** =:doc-links LINKS=
+Allows configuring documentation links for the package page.  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-links= to ~ignore~ or to an association list of the titles and
+URLs of an existing documentation.  For example:
+
+    (("User Manual" . "https://example.tld/manual.html"))
+
 ** =:make TARGET=
 Indicates that we should run ~make TARGET~ in order to build some files.
 This is run before processing =:doc=, so it can be used to generate
diff --git a/elpa-admin.el b/elpa-admin.el
index 363919d9ab..6c25be5483 100644
--- a/elpa-admin.el
+++ b/elpa-admin.el
@@ -1449,25 +1449,35 @@ arbitrary code."
   (concat (file-name-base docfile) ".html"))
 
 (defun elpaa--html-insert-docs (pkg-spec)
-  (let ((docfiles (reverse (plist-get (cdr pkg-spec) :internal--html-docs)))
-	;; `html-dir' is relative to the tarball directory, so html
-	;; references on mirrors work.  It does not include the
-	;; package name, so cross references among package docs work.
-	(html-dir (when elpaa--doc-subdirectory
-	            (file-name-as-directory elpaa--doc-subdirectory))))
-    (when (and docfiles html-dir
-	       ;; FIXME: This dir is shared, so it will always exist.
-	       ;; Should we use (expand-file-name pkg html-dir) instead?
-               (file-readable-p html-dir)) ;; html doc files were built
-      (insert "<dt>Manual</dt> <dd>\n")
-      (dolist (doc docfiles)
-	(let ((html-file (concat html-dir (cdr doc))))
-	  (insert "<a href=\"" html-file "\">"
-	          (car doc)
-	          "</a>\n")
-	  ;; FIXME: get link text from info direntry?
-	  ))
-      (insert "</dd>\n"))))
+  (let ((doc-links (elpaa--spec-get pkg-spec :doc-links)))
+    (unless (equal doc-links 'ignore)
+      (let ((docfiles (or doc-links
+                          (reverse (elpaa--spec-get
+                                    pkg-spec :internal--html-docs))))
+            ;; `html-dir' is relative to the tarball directory, so
+            ;; html references on mirrors work.  It does not include
+            ;; the package name, so cross references among package
+            ;; docs work.
+            (html-dir (when (and (not doc-links) elpaa--doc-subdirectory)
+                        (file-name-as-directory elpaa--doc-subdirectory))))
+        (when (and docfiles
+                   (or doc-links
+                       ;; FIXME: This dir is shared, so it will always
+                       ;; exist.  Should we use (expand-file-name pkg
+                       ;; html-dir) instead?
+                       (and html-dir
+                            ;; html doc files were built
+                            (file-readable-p html-dir))))
+          (insert "<dt>Documentation</dt> <dd>\n")
+          (dolist (doc docfiles)
+            (let ((html-file (if doc-links (cdr doc)
+                               (concat html-dir (cdr doc)))))
+              (insert "<a href=\"" html-file "\">"
+                      (car doc)
+                      "</a>\n")
+              ;; FIXME: get link text from info direntry?
+              ))
+          (insert "</dd>\n"))))))
 
 (defun elpaa--html-make-pkg (pkg pkg-spec files srcdir)
   (let* ((name (symbol-name (car pkg)))
@@ -2106,7 +2116,8 @@ relative to elpa root."
            t "makeinfo" "--no-split" docfile "-o" info-file)
           (message "%s" (buffer-string)))
 
-	(when html-dir (elpaa--html-build-doc pkg-spec docfile html-dir))
+        (when (and html-dir (not (elpaa--spec-get pkg-spec :doc-links)))
+          (elpaa--html-build-doc pkg-spec docfile html-dir))
 
         (setq docfile info-file)))
 
-- 
2.34.1


--=-=-=--




Acknowledgement sent to "Y. E." <yet@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to bug-gnu-emacs@HIDDEN:
bug#53205; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Thu, 13 Jan 2022 13:30:02 UTC

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