Manuals for GNU ELPA packages

Manuals for GNU ELPA packages

[Kjartan Óli Ágústsson]

Some time ago my calibre package
(https://elpa.gnu.org/packages/calibre.html) was added to GNU ELPA.
Shortly after that I made my first attempt to write a Texinfo manual for
the package.  When I look at the tarball downloaded from ELPA I see the
texi files are there but there are no info files.  Does the ELPA package
specification need to be updated, or did I do something wrong when
adding the manual to my repository?

-- 
Kjartan Oli Agustsson
GPG Key fingerprint: 4801 0D71 49C0 1DD6 E5FD  6AC9 D757 2FE3 605E E6B0

Re: Manuals for GNU ELPA packages

[Philip Kaludercic]

[-- Attachment #1: Type: text/plain, Size: 584 bytes --]

Kjartan Óli Ágústsson <kjartanoli@outlook.com> writes:

> Some time ago my calibre package
> (https://elpa.gnu.org/packages/calibre.html) was added to GNU ELPA.
> Shortly after that I made my first attempt to write a Texinfo manual for
> the package.  When I look at the tarball downloaded from ELPA I see the
> texi files are there but there are no info files.  Does the ELPA package
> specification need to be updated, or did I do something wrong when
> adding the manual to my repository?

Yes, the package specification needs a new :doc attribute, something
like


[-- Attachment #2: Type: text/plain, Size: 543 bytes --]

diff --git a/elpa-packages b/elpa-packages
index 858948422f..8faa74d12b 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -123,7 +123,8 @@
  ;;                      :doc "cc-mode.texi"))
  (buildbot		:url "https://g.ypei.me/buildbot.el.git"
   :readme "README.org")
- (calibre               :url "https://git.disroot.org/kjartanoli/calibre.el")
+ (calibre               :url "https://git.disroot.org/kjartanoli/calibre.el"
+  :doc "doc/calibre.tex")
  (cape			:url "https://github.com/minad/cape"
   :doc "README.org"
   :news "CHANGELOG.org"

[-- Attachment #3: Type: text/plain, Size: 301 bytes --]


Just note that the file extension .tex is wrong here, since this is not
a regular TeX or LaTeX file.  If you rename it to .texi and we then
update the specification, then the documentation should be packaged in
the tarball and also appear online under
https://elpa.gnu.org/packages/doc/calibre.html.

Re: Manuals for GNU ELPA packages

[Michael Albinus]

Philip Kaludercic <philipk@posteo.net> writes:

Hi Philip,

> ... then the documentation should be packaged in
> the tarball and also appear online under
> https://elpa.gnu.org/packages/doc/calibre.html.

On https://elpa.gnu.org/packages/doc/, there is a directory of all
manuals, plus the README of plz.el. The latter is wrong here, I guess.

Best regards, Michael.

Re: Manuals for GNU ELPA packages

[Philip Kaludercic]

Michael Albinus <michael.albinus@gmx.de> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
> Hi Philip,
>
>> ... then the documentation should be packaged in
>> the tarball and also appear online under
>> https://elpa.gnu.org/packages/doc/calibre.html.
>
> On https://elpa.gnu.org/packages/doc/, there is a directory of all
> manuals, plus the README of plz.el. The latter is wrong here, I guess.

That is true, but it appears that the file is being regenerated
regularly, so this is probably an issue  with elpa-admin.el.  I'll look
into it.

> Best regards, Michael.

Re: Manuals for GNU ELPA packages

[Philip Kaludercic]

[-- Attachment #1: Type: text/plain, Size: 855 bytes --]

Michael Albinus <michael.albinus@gmx.de> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
> Hi Philip,
>
>> ... then the documentation should be packaged in
>> the tarball and also appear online under
>> https://elpa.gnu.org/packages/doc/calibre.html.
>
> On https://elpa.gnu.org/packages/doc/, there is a directory of all
> manuals, plus the README of plz.el. The latter is wrong here, I guess.

It turns out that this is actually a more general issue, since
elpa-admin.el keeps the basename of the file being rendered, even if
multiple packages use the same name (e.g. as is the case with packages
that use "README.org").  As we want to be able to render multiple manual
files, we cannot just trivially rename the name of the symlink.

I think the simplest solution is to point to files in the respective
doc/ sub-directory of each package:


[-- Attachment #2: Type: text/plain, Size: 654 bytes --]

diff --git a/elpa-admin.el b/elpa-admin.el
index cde0e3437a..3e79bef078 100644
--- a/elpa-admin.el
+++ b/elpa-admin.el
@@ -1856,7 +1856,11 @@ arbitrary code."
                (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))))
+	(let ((html-file (expand-file-name
+                          (cdr doc)
+                          (expand-file-name
+                           (symbol-name (car pkg-spec))
+                           html-dir))))
 	  (insert "<a href=\"" html-file "\">"
 	          (car doc)
 	          "</a>\n")

[-- Attachment #3: Type: text/plain, Size: 111 bytes --]


and perhaps even stop generating the symlinks.

> Best regards, Michael.

-- 
	Philip Kaludercic on peregrine

Re: Manuals for GNU ELPA packages

[Stefan Monnier]

> -	(let ((html-file (concat html-dir (cdr doc))))
> +	(let ((html-file (expand-file-name
> +                          (cdr doc)
> +                          (expand-file-name
> +                           (symbol-name (car pkg-spec))
> +                           html-dir))))

That looks about right, except we want relative names, so we should use
`concat` or `file-name-concat`.


        Stefan

Re: Manuals for GNU ELPA packages

[Philip Kaludercic]

[-- Attachment #1: Type: text/plain, Size: 611 bytes --]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> -	(let ((html-file (concat html-dir (cdr doc))))
>> +	(let ((html-file (expand-file-name
>> +                          (cdr doc)
>> +                          (expand-file-name
>> +                           (symbol-name (car pkg-spec))
>> +                           html-dir))))
>
> That looks about right, except we want relative names, so we should use
> `concat` or `file-name-concat`.

Of course, I forgot that fine-name-concat was available, and yes, the
absolute file names wouldn't really improve the website experience ^^

This is my suggestion:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Link-to-HTML-manuals-in-their-respective-subdirector.patch --]
[-- Type: text/x-patch, Size: 1972 bytes --]

From e999dbdc195b27ebd5699e5e756131e9b8de5fe5 Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Mon, 26 Feb 2024 15:03:43 +0100
Subject: [PATCH] Link to HTML manuals in their respective subdirectories

* elpa-admin.el (elpaa--html-insert-docs): To avoid manuals with the
same names overwriting each other, link directly to the files under
doc/[package name].
(elpaa--html-build-doc): Do not generate symlinks to the actual manual
files.
---
 elpa-admin.el | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/elpa-admin.el b/elpa-admin.el
index cde0e3437a..4eb47d6856 100644
--- a/elpa-admin.el
+++ b/elpa-admin.el
@@ -1856,7 +1856,10 @@ arbitrary code."
                (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))))
+	(let ((html-file (file-name-concat
+                          html-dir
+                          (symbol-name (car pkg-spec))
+                          (cdr doc))))
 	  (insert "<a href=\"" html-file "\">"
 	          (car doc)
 	          "</a>\n")
@@ -2539,14 +2542,7 @@ directory; one of archive, archive-devel."
                :internal--html-docs
                (cons (cons (file-name-base html-file)
                            (file-name-nondirectory html-file))
-                     (plist-get (cdr pkg-spec) :internal--html-docs)))
-
-    ;; Create a symlink from elpa/archive[-devel]/doc/* to
-    ;; the actual file, so html references work.
-    (with-demoted-errors "%S" ;; 'make-symbolic-link' doesn't work on Windows
-      (make-symbolic-link
-       (concat (file-name-nondirectory html-dir) "/" destname)
-       html-xref-file t))))
+                     (plist-get (cdr pkg-spec) :internal--html-docs)))))
 
 (defun elpaa--build-Info-1 (pkg-spec docfile dir html-dir)
   "Build an info file from DOCFILE (a texinfo source file).
-- 
2.43.2


[-- Attachment #3: Type: text/plain, Size: 38 bytes --]



-- 
	Philip Kaludercic on peregrine

Re: Manuals for GNU ELPA packages

[Stefan Monnier]

>> On https://elpa.gnu.org/packages/doc/, there is a directory of all
>> manuals, plus the README of plz.el. The latter is wrong here, I guess.

I can't see any "readme" or "README" in
https://elpa.gnu.org/packages/doc/ What am I missing?


        Stefan

Re: Manuals for GNU ELPA packages

[Philip Kaludercic]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> On https://elpa.gnu.org/packages/doc/, there is a directory of all
>>> manuals, plus the README of plz.el. The latter is wrong here, I guess.
>
> I can't see any "readme" or "README" in
> https://elpa.gnu.org/packages/doc/ What am I missing?

I made the mistake of removing it, but the timestamp was from 2024-02-22
so it would reappear shortly (also, it wasn't the plz manual any more).

>
>         Stefan
>

-- 
	Philip Kaludercic on peregrine

Re: Manuals for GNU ELPA packages

[Stefan Monnier]

>>>> On https://elpa.gnu.org/packages/doc/, there is a directory of all
>>>> manuals, plus the README of plz.el. The latter is wrong here, I guess.
>> I can't see any "readme" or "README" in
>> https://elpa.gnu.org/packages/doc/ What am I missing?
> I made the mistake of removing it, but the timestamp was from 2024-02-22
> so it would reappear shortly

Ah, makes sense.  No worries.

> (also, it wasn't the plz manual any more).

Right: whichever package was rebuilt more recently will temporarily get
the spot :-)


        Stefan