bug#29420: 26.0; doc of `list-packages'

[Stefan Kangas <stefan@marxist.se>]

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

tags 29420 + patch
quit

Drew Adams <drew.adams@oracle.com> writes:

>> > `C-h r g package menu' should give you a better description.
>> > It should describe each column of the display.
>>
>> It does that already.
>
> It does, but the next sentence details the problem
> with that description: nothing about `dependency',
> for example (dunno whether there are other problems
> with the columns description).
>
>> > It could describe column `status' better, for instance.  Apparently
>> > one of the possible values is `dependency', but that is not
>> > mentioned.
>>
>> Patches to improve the documentation of package.el in the manual are
>> most welcome.  I generally find its documentation inadequate and
>> outdated, and tried to improve that as best I could, but I don't know
>> enough about it to do a better job, and apparently (and sadly) no one
>> else is interested.
>
> I know (and likely care) less about the package system
> than you.  Neither of us is well placed, probably, to
> help much in this regard.
>
> I do appreciate your attempts to solicit strong doc
> along with new developments.  The package system
> slipped between the cracks to some extent in this
> regard, I guessed.  A guess is that when a large
> set of code gets developed outside Emacs first
> it can get added to Emacs all at once, and the doc
> isn't necessarily gone over with a fine-tooth comb,
> in spite of your best efforts.
>
> I agree that it would be great if Someone (TM) gave
> the package.el doc some more attention.

Please see the attached patch which extends the documentation to cover
all possible package statuses.  Any comments?

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Document-package-statuses-better.patch --]
[-- Type: application/octet-stream, Size: 2498 bytes --]

From 4838942b4e736ff89c14f519e7c5244bd382d524 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 19 Oct 2019 03:56:41 +0200
Subject: [PATCH] Document package statuses better

* doc/emacs/package.texi (Package Menu): Extend documentation to
cover all possible package statuses.  (Bug#29420)
---
 doc/emacs/package.texi | 33 +++++++++++++++++++++++++++------
 1 file changed, 27 insertions(+), 6 deletions(-)

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index d97648af1b..1d23158d59 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -64,13 +64,34 @@ Package Menu
 cannot be deleted through the package menu, and are not considered for
 upgrading.
 
-The status can also be @samp{new}.  This is equivalent to
-@samp{available}, except that it means the package became newly
-available on the package archive after your last invocation of
-@kbd{M-x list-packages}.  In other instances, a package may have the
-status @samp{held}, @samp{disabled}, or @samp{obsolete}.
+The status @samp{dependency} means that the package was automatically
+installed to satisfy a dependency of another package.
+
+The status @samp{new} is equivalent to @samp{available}, except that
+it means the package became newly available on the package archive
+after your last invocation of @kbd{M-x list-packages}.
+
+The status @samp{incompat} means that the package cannot be installed
+for some reason, for example because it depends on uninstallable
+packages.
+
+The status @samp{obsolete} means that the package is an outdated
+installed version; in addition to this version, a newer version is
+already installed.
+
+The status @samp{avail-obso} means that the package is available for
+installation, but there also exists a newer version.
+
+The status @samp{disabled} means that the package has been disabled
+using the variable `package-load-list'.
+
+Finally, a package may have the status @samp{held}.
 @xref{Package Installation}.
 
+@item
+Which package archive this package is from, if you have more than one
+package archive.
+
 @item
 A short description of the package.
 @end itemize
@@ -123,7 +144,7 @@ Package Menu
 Mark all package with a newer available version for upgrading
 (@code{package-menu-mark-upgrades}).  This places an installation mark
 on the new available versions, and a deletion mark on the old
-installed versions.
+installed versions (marked with status @samp{obsolete}).
 
 @item x
 @vindex package-menu-async
-- 
2.23.0