* Manuals for GNU ELPA packages @ 2023-12-26 13:44 Kjartan Óli Ágústsson 2023-12-26 17:17 ` Philip Kaludercic 0 siblings, 1 reply; 10+ messages in thread From: Kjartan Óli Ágústsson @ 2023-12-26 13:44 UTC (permalink / raw) To: emacs-devel@gnu.org 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Manuals for GNU ELPA packages 2023-12-26 13:44 Manuals for GNU ELPA packages Kjartan Óli Ágústsson @ 2023-12-26 17:17 ` Philip Kaludercic 2023-12-27 8:41 ` Michael Albinus 0 siblings, 1 reply; 10+ messages in thread From: Philip Kaludercic @ 2023-12-26 17:17 UTC (permalink / raw) To: Kjartan Óli Ágústsson; +Cc: emacs-devel@gnu.org [-- 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. ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: Manuals for GNU ELPA packages 2023-12-26 17:17 ` Philip Kaludercic @ 2023-12-27 8:41 ` Michael Albinus 2023-12-27 13:47 ` Philip Kaludercic 2024-02-26 10:49 ` Philip Kaludercic 0 siblings, 2 replies; 10+ messages in thread From: Michael Albinus @ 2023-12-27 8:41 UTC (permalink / raw) To: Philip Kaludercic Cc: Kjartan Óli Ágústsson, emacs-devel@gnu.org 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Manuals for GNU ELPA packages 2023-12-27 8:41 ` Michael Albinus @ 2023-12-27 13:47 ` Philip Kaludercic 2024-02-26 10:49 ` Philip Kaludercic 1 sibling, 0 replies; 10+ messages in thread From: Philip Kaludercic @ 2023-12-27 13:47 UTC (permalink / raw) To: Michael Albinus; +Cc: Kjartan Óli Ágústsson, emacs-devel@gnu.org 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Manuals for GNU ELPA packages 2023-12-27 8:41 ` Michael Albinus 2023-12-27 13:47 ` Philip Kaludercic @ 2024-02-26 10:49 ` Philip Kaludercic 2024-02-26 13:04 ` Stefan Monnier 2024-02-26 15:03 ` Stefan Monnier 1 sibling, 2 replies; 10+ messages in thread From: Philip Kaludercic @ 2024-02-26 10:49 UTC (permalink / raw) To: Michael Albinus Cc: Kjartan Óli Ágústsson, emacs-devel@gnu.org, Stefan Monnier [-- 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 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: Manuals for GNU ELPA packages 2024-02-26 10:49 ` Philip Kaludercic @ 2024-02-26 13:04 ` Stefan Monnier 2024-02-26 14:05 ` Philip Kaludercic 2024-02-26 15:03 ` Stefan Monnier 1 sibling, 1 reply; 10+ messages in thread From: Stefan Monnier @ 2024-02-26 13:04 UTC (permalink / raw) To: Philip Kaludercic Cc: Michael Albinus, Kjartan Óli Ágústsson, emacs-devel@gnu.org > - (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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Manuals for GNU ELPA packages 2024-02-26 13:04 ` Stefan Monnier @ 2024-02-26 14:05 ` Philip Kaludercic 0 siblings, 0 replies; 10+ messages in thread From: Philip Kaludercic @ 2024-02-26 14:05 UTC (permalink / raw) To: Stefan Monnier Cc: Michael Albinus, Kjartan Óli Ágústsson, emacs-devel@gnu.org [-- 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 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: Manuals for GNU ELPA packages 2024-02-26 10:49 ` Philip Kaludercic 2024-02-26 13:04 ` Stefan Monnier @ 2024-02-26 15:03 ` Stefan Monnier 2024-02-26 15:27 ` Philip Kaludercic 1 sibling, 1 reply; 10+ messages in thread From: Stefan Monnier @ 2024-02-26 15:03 UTC (permalink / raw) To: Michael Albinus Cc: Philip Kaludercic, Kjartan Óli Ágústsson, emacs-devel@gnu.org >> 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Manuals for GNU ELPA packages 2024-02-26 15:03 ` Stefan Monnier @ 2024-02-26 15:27 ` Philip Kaludercic 2024-02-26 16:15 ` Stefan Monnier 0 siblings, 1 reply; 10+ messages in thread From: Philip Kaludercic @ 2024-02-26 15:27 UTC (permalink / raw) To: Stefan Monnier Cc: Michael Albinus, Kjartan Óli Ágústsson, emacs-devel@gnu.org 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Manuals for GNU ELPA packages 2024-02-26 15:27 ` Philip Kaludercic @ 2024-02-26 16:15 ` Stefan Monnier 0 siblings, 0 replies; 10+ messages in thread From: Stefan Monnier @ 2024-02-26 16:15 UTC (permalink / raw) To: Philip Kaludercic Cc: Michael Albinus, Kjartan Óli Ágústsson, emacs-devel@gnu.org >>>> 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2024-02-26 16:15 UTC | newest] Thread overview: 10+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2023-12-26 13:44 Manuals for GNU ELPA packages Kjartan Óli Ágústsson 2023-12-26 17:17 ` Philip Kaludercic 2023-12-27 8:41 ` Michael Albinus 2023-12-27 13:47 ` Philip Kaludercic 2024-02-26 10:49 ` Philip Kaludercic 2024-02-26 13:04 ` Stefan Monnier 2024-02-26 14:05 ` Philip Kaludercic 2024-02-26 15:03 ` Stefan Monnier 2024-02-26 15:27 ` Philip Kaludercic 2024-02-26 16:15 ` Stefan Monnier
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.