README used by NonGNU packages "remotely" even though it's ignored

README used by NonGNU packages "remotely" even though it's ignored

[Daniel Semyonov]

Hi,

I noticed that the description shown on the NonGNU ELPA website for my
packages (swsw and vcomplete), as well as the description shown through
Emacs when viewing a version of the packages that isn't installed
locally is the content of the README file included in their respective
repositories.  However, both packages explicitly ignore that file (using
an '.elpaignore' file).

When viewing the description of a locally installed version of the
packages, the commentary is shown (as is expected).

I wonder if this behavior is intended, and if so whether it is
documented anywhere?

Regards,
Daniel

Re: README used by NonGNU packages "remotely" even though it's ignored

[Stefan Monnier]

> I wonder if this behavior is intended,

Yes and no: the `.elpaignore` is only meant to control what goes into
the tarball, and it doesn't restrict what's used for the rest.

You can control which file is used for the "readme" using `:readme` in
the `elpa-packages` file, but currently that doesn't let you say "use
the Commentary:" :-(

[ ...Checking the `elpa-admin.el` file... ]

Hmm... it looks like I was wrong and  you can say `:readme ignore` to force
the use of the `Commentary:`.


        Stefan

Re: README used by NonGNU packages "remotely" even though it's ignored

[Philip Kaludercic]

Daniel Semyonov <daniel@dsemy.com> writes:

> Hi,
>
> I noticed that the description shown on the NonGNU ELPA website for my
> packages (swsw and vcomplete), as well as the description shown through
> Emacs when viewing a version of the packages that isn't installed
> locally is the content of the README file included in their respective
> repositories.  However, both packages explicitly ignore that file (using
> an '.elpaignore' file).

Ignored files specify what files should not be added to the package
tarball.

> When viewing the description of a locally installed version of the
> packages, the commentary is shown (as is expected).
>
> I wonder if this behavior is intended, and if so whether it is
> documented anywhere?

See [0].  By default the README file is used.  If you prefer to, it is
possible to configure using the commentary section.

[0] https://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/README?h=elpa-admin#n132,

> Regards,
> Daniel

Re: README used by NonGNU packages "remotely" even though it's ignored

[Daniel Semyonov]

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

>>>>> Philip Kaludercic writes:

    > Ignored files specify what files should not be added to the
    > package tarball.

    > See [0].  By default the README file is used.  If you prefer to,
    > it is possible to configure using the commentary section.

    > [0]
    > https://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/README?h=elpa-admin#n132,

Thanks, I previously read the first few paragraphs of the elpa-admin
README and made the (incorrect) assumption that it wasn't very relevant
to me as a package author.

Attached is a patch updating my packages to use the commentary.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: patch --]
[-- Type: text/x-diff, Size: 822 bytes --]

From 7be993e60bdc7c69a8dd8444f0bca6e5c108957f Mon Sep 17 00:00:00 2001
From: Daniel Semyonov <daniel@dsemy.com>
Date: Wed, 8 Jun 2022 00:54:29 +0300
Subject: [PATCH] * elpa-packages (vcomplete, swsw): Use commentary for
 ':readme'

---
 elpa-packages | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/elpa-packages b/elpa-packages
index 034ed41c01..a6bf3ffd8f 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -531,6 +531,7 @@
   :ignored-files ("COPYING" "scripts" "test" "Eldev" "Makefile"))
 
  ("swsw"		:url "https://git.sr.ht/~dsemy/swsw"
+  :readme ignore
   :doc "swsw.texi"
   :news "NEWS")
 
@@ -563,6 +564,7 @@
  ("vc-fossil"		:url "https://github.com/venks1/emacs-fossil")
 
  ("vcomplete"		:url "https://git.sr.ht/~dsemy/vcomplete"
+  :readme ignore
   :doc "vcomplete.texi"
   :news "NEWS")
 
-- 
2.36.1

Re: README used by NonGNU packages "remotely" even though it's ignored

[Philip Kaludercic]

Daniel Semyonov <daniel@dsemy.com> writes:

>>>>>> Philip Kaludercic writes:
>
>     > Ignored files specify what files should not be added to the
>     > package tarball.
>
>     > See [0].  By default the README file is used.  If you prefer to,
>     > it is possible to configure using the commentary section.
>
>     > [0]
>     > https://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/README?h=elpa-admin#n132,
>
> Thanks, I previously read the first few paragraphs of the elpa-admin
> README and made the (incorrect) assumption that it wasn't very relevant
> to me as a package author.

There is certainly potential to improve the documentation.

> Attached is a patch updating my packages to use the commentary.

Thanks, it has been pushed.

> From 7be993e60bdc7c69a8dd8444f0bca6e5c108957f Mon Sep 17 00:00:00 2001
> From: Daniel Semyonov <daniel@dsemy.com>
> Date: Wed, 8 Jun 2022 00:54:29 +0300
> Subject: [PATCH] * elpa-packages (vcomplete, swsw): Use commentary for
>  ':readme'
>
> ---
>  elpa-packages | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/elpa-packages b/elpa-packages
> index 034ed41c01..a6bf3ffd8f 100644
> --- a/elpa-packages
> +++ b/elpa-packages
> @@ -531,6 +531,7 @@
>    :ignored-files ("COPYING" "scripts" "test" "Eldev" "Makefile"))
>  
>   ("swsw"		:url "https://git.sr.ht/~dsemy/swsw"
> +  :readme ignore
>    :doc "swsw.texi"
>    :news "NEWS")
>  
> @@ -563,6 +564,7 @@
>   ("vc-fossil"		:url "https://github.com/venks1/emacs-fossil")
>  
>   ("vcomplete"		:url "https://git.sr.ht/~dsemy/vcomplete"
> +  :readme ignore
>    :doc "vcomplete.texi"
>    :news "NEWS")