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

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

[Drew Adams]

`C-h f list-packages' should give you a better description of the
display that results.  It wouldn't hurt to succinctly describe each
column.

`C-h r g package menu' should give you a better description.  It should
describe each column of the display.  It could describe column `status'
better, for instance.  Apparently one of the possible values is
`dependency', but that is not mentioned.

Cf. https://emacs.stackexchange.com/q/37058/105



In GNU Emacs 26.0.90 (build 3, x86_64-w64-mingw32)
 of 2017-10-13
Repository revision: 906224eba147bdfc0514090064e8e8f53160f1d4
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

[Eli Zaretskii]

> Date: Thu, 23 Nov 2017 18:05:57 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> `C-h f list-packages' should give you a better description of the
> display that results.  It wouldn't hurt to succinctly describe each
> column.

I added the list of columns.

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

Thanks.

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

[Stefan Kangas]

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

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

[Drew Adams]

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

Only comment is thanks for doing this.

I know almost nothing about the package system,
so I can't comment on the technical content.
I trust that you did a good job.

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 19 Oct 2019 04:04:21 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>, 29420@debbugs.gnu.org
> 
> +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'.

This kind of list is better formatted as a @table.

Thanks.

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

[Stefan Kangas]

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

Eli Zaretskii <eliz@gnu.org> writes:
> This kind of list is better formatted as a @table.

Thanks.  I decided to add a new section to not make the "Package Menu"
node too cluttered.  What do you think?

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Add-section-on-Package-Status-to-info-manual.patch --]
[-- Type: application/octet-stream, Size: 4780 bytes --]

From e517ea8663c17d8675ebe19da5dfb08bfbcb3bd9 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 19 Oct 2019 03:56:41 +0200
Subject: [PATCH] Add section on Package Status to info manual

* doc/emacs/emacs.texi (Top):
* doc/emacs/package.texi (Package Status): Add new section.
(Packages, Package Menu): Refer to above section.  (Bug#29420)
---
 doc/emacs/emacs.texi   |  1 +
 doc/emacs/package.texi | 76 ++++++++++++++++++++++++++++++++++--------
 2 files changed, 63 insertions(+), 14 deletions(-)

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index a7967ecaee..b9bc65f838 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -1101,6 +1101,7 @@ Top
 
 * Package Menu::         Buffer for viewing and managing packages.
 * Package Installation:: Options for package installation.
+* Package Status::       The status of a package.
 * Package Files::        Where packages are installed.
 
 Customization
diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index d97648af1b..b367ca48cf 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -33,6 +33,7 @@ Packages
 @menu
 * Package Menu::         Buffer for viewing and managing packages.
 * Package Installation:: Options for package installation.
+* Package Status::       The status of a package.
 * Package Files::        Where packages are installed.
 @end menu
 
@@ -57,19 +58,12 @@ Package Menu
 The package's status---normally one of @samp{available} (can be
 downloaded from the package archive), @samp{installed},
 @c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
-or @samp{built-in} (included in Emacs by default).  The status
-@samp{external} means the package is not built-in and not from the
-directory specified by @code{package-user-dir} (@pxref{Package
-Files}).  External packages are treated much like built-in: they
-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}.
-@xref{Package Installation}.
+or @samp{built-in} (included in Emacs by default).  For more
+details, @xref{Package Status}.
+
+@item
+Which package archive this package is from, if you have more than one
+package archive.
 
 @item
 A short description of the package.
@@ -123,7 +117,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
@@ -303,6 +297,60 @@ Package Installation
 installed will be ignored.  The @samp{muse} package will be listed in
 the package menu with the @samp{held} status.
 
+@node Package Status
+@section Package Status
+@cindex package status
+
+A package can have one of the following statuses:
+
+@table @samp
+@item available
+The package is not installed, but can be downloaded from the package
+archive.
+
+@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
+
+@item built-in
+The package is included in Emacs by default.  It cannot be deleted
+through the package menu, and is not considered for upgrading.
+
+@item installed
+The package is installed.
+
+@item dependency
+The package was installed automatically to satisfy a dependency of
+another package.
+
+@item new
+Equivalent to @samp{available}, except that the package became newly
+available on the package archive after your last invocation of
+@kbd{M-x list-packages}.
+
+@item obsolete
+The package is an outdated installed version; in addition to this
+version of the package, a newer version is also installed.
+
+@item avail-obso
+The package is available for installation, but a newer version is also
+available.  Packages with this status are hidden by default.
+
+@item disabled
+The package has been disabled using the @code{package-load-list}
+variable.
+
+@item external
+The package is not built-in and not from the directory specified by
+@code{package-user-dir} (@pxref{Package Files}).  External packages
+are treated much like built-in packages and cannot be deleted.
+
+@item incompat
+The package cannot be installed for some reason, for example because
+it depends on uninstallable packages.
+
+@item held
+The package is held, @xref{Package Installation}.
+@end table
+
 @node Package Files
 @section Package Files and Directory Layout
 @cindex package directory
-- 
2.23.0

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 20 Oct 2019 17:42:09 +0200
> Cc: Drew Adams <drew.adams@oracle.com>, 29420@debbugs.gnu.org
> 
> Thanks.  I decided to add a new section to not make the "Package Menu"
> node too cluttered.  What do you think?

It should rather be a subsection of "Package Menu", since that's where
you talk about 'status', and it should follow "Package Menu".
Otherwise, in the printed manual, the text which starts "Package
Status" will come out of the blue, with nothing to connect it to the
previous or the next section.

> +or @samp{built-in} (included in Emacs by default).  For more
> +details, @xref{Package Status}.

@xref produces a capitalize "See", so it is inappropriate in the
middle of a sentence.  You want "see @ref" here.

> +
> +@item
> +Which package archive this package is from, if you have more than one
> +package archive.
>  
>  @item
>  A short description of the package.
> @@ -123,7 +117,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
> @@ -303,6 +297,60 @@ Package Installation
>  installed will be ignored.  The @samp{muse} package will be listed in
>  the package menu with the @samp{held} status.
>  
> +@node Package Status
> +@section Package Status
> +@cindex package status
> +
> +A package can have one of the following statuses:
> +
> +@table @samp
> +@item available
> +The package is not installed, but can be downloaded from the package
> +archive.
> +
> +@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
> +
> +@item built-in
> +The package is included in Emacs by default.  It cannot be deleted
> +through the package menu, and is not considered for upgrading.
> +
> +@item installed
> +The package is installed.
> +
> +@item dependency
> +The package was installed automatically to satisfy a dependency of
> +another package.
> +
> +@item new
> +Equivalent to @samp{available}, except that the package became newly
> +available on the package archive after your last invocation of
> +@kbd{M-x list-packages}.
> +
> +@item obsolete
> +The package is an outdated installed version; in addition to this
> +version of the package, a newer version is also installed.
> +
> +@item avail-obso
> +The package is available for installation, but a newer version is also
> +available.  Packages with this status are hidden by default.
> +
> +@item disabled
> +The package has been disabled using the @code{package-load-list}
> +variable.
> +
> +@item external
> +The package is not built-in and not from the directory specified by
> +@code{package-user-dir} (@pxref{Package Files}).  External packages
> +are treated much like built-in packages and cannot be deleted.
> +
> +@item incompat
> +The package cannot be installed for some reason, for example because
> +it depends on uninstallable packages.
> +
> +@item held
> +The package is held, @xref{Package Installation}.
> +@end table

Maybe the table should be organized in alphabetical order?  Not sure.

Thanks, looks fine with these nits fixed.

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

[Stefan Kangas]

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

Eli Zaretskii <eliz@gnu.org> writes:

> > Thanks.  I decided to add a new section to not make the "Package Menu"
> > node too cluttered.  What do you think?
>
> It should rather be a subsection of "Package Menu", since that's where
> you talk about 'status', and it should follow "Package Menu".
> Otherwise, in the printed manual, the text which starts "Package
> Status" will come out of the blue, with nothing to connect it to the
> previous or the next section.

OK, fixed.  I also added a new subsection "Package Menu Commands" to
make the hierarchy clearer.

> > +or @samp{built-in} (included in Emacs by default).  For more
> > +details, @xref{Package Status}.
>
> @xref produces a capitalize "See", so it is inappropriate in the
> middle of a sentence.  You want "see @ref" here.

Fixed; I changed the reference to use @ref and @anchor (since it's now
a subsection).  Please me know if that's not the preferred way to do
it.

> Maybe the table should be organized in alphabetical order?  Not sure.

I was also conflicted, but in the end decided to go with alphabetical
rather than the somewhat arbitrary sorting in order of importance that
I had before.  If nothing else, no one can now claim that the sorting
is incorrect...

> Thanks, looks fine with these nits fixed.

Thanks for the review.  I intend to commit the attached updated patch
in a couple of days.

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Add-subsection-Package-Statuses-to-manual.patch --]
[-- Type: application/octet-stream, Size: 4173 bytes --]

From 02c94d5727951010b434e4678249e30930efa50c Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Tue, 22 Oct 2019 01:42:41 +0200
Subject: [PATCH] Add subsection "Package Statuses" to manual

* doc/emacs/package.texi (Package Menu): New subsection "Package
Statuses".  (Bug#29420)
---
 doc/emacs/package.texi | 76 ++++++++++++++++++++++++++++++++++--------
 1 file changed, 62 insertions(+), 14 deletions(-)

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index d97648af1b..e4ca0e9b0f 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -57,19 +57,11 @@ Package Menu
 The package's status---normally one of @samp{available} (can be
 downloaded from the package archive), @samp{installed},
 @c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
-or @samp{built-in} (included in Emacs by default).  The status
-@samp{external} means the package is not built-in and not from the
-directory specified by @code{package-user-dir} (@pxref{Package
-Files}).  External packages are treated much like built-in: they
-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}.
-@xref{Package Installation}.
+or @samp{built-in} (included in Emacs by default).  @xref{Package Statuses}.
+
+@item
+Which package archive this package is from, if you have more than one
+package archive enabled.
 
 @item
 A short description of the package.
@@ -81,6 +73,8 @@ Package Menu
 network is unavailable, it falls back on the most recently retrieved
 list.
 
+@subsection Package Menu Commands
+
 The following commands are available in the package menu:
 
 @table @kbd
@@ -123,7 +117,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
@@ -164,6 +158,60 @@ Package Menu
 For example, you can install a package by typing @kbd{i} on the line
 listing that package, followed by @kbd{x}.
 
+@subsection Package Statuses
+@cindex package status
+@anchor{Package Statuses}
+
+A package can have one of the following statuses:
+
+@table @samp
+@item available
+The package is not installed, but can be downloaded and installed from
+the package archive.
+
+@item avail-obso
+The package is available for installation, but a newer version is also
+available.  Packages with this status are hidden by default.
+
+@item built-in
+The package is included in Emacs by default.  It cannot be deleted
+through the package menu, and is not considered for upgrading.
+
+@item dependency
+The package was installed automatically to satisfy a dependency of
+another package.
+
+@item disabled
+The package has been disabled using the @code{package-load-list}
+variable.
+
+@item external
+The package is not built-in and not from the directory specified by
+@code{package-user-dir} (@pxref{Package Files}).  External packages
+are treated much like @samp{built-in} packages and cannot be deleted.
+
+@item held
+The package is held, @xref{Package Installation}.
+
+@item incompat
+The package cannot be installed for some reason, for example because
+it depends on uninstallable packages.
+
+@item installed
+The package is installed.
+
+@item new
+Equivalent to @samp{available}, except that the package became newly
+available on the package archive after your last invocation of
+@kbd{M-x list-packages}.
+
+@item obsolete
+The package is an outdated installed version; in addition to this
+version of the package, a newer version is also installed.
+
+@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
+@end table
+
 @node Package Installation
 @section Package Installation
 
-- 
2.23.0

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 22 Oct 2019 01:43:04 +0200
> Cc: Drew Adams <drew.adams@oracle.com>, 29420@debbugs.gnu.org
> 
> +@subsection Package Menu Commands

Maybe use @unnumberedsubsec instead of @section, as having it numbered
might confuse someone into thinking it's a node.

Otherwise, looks good, thanks.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> > +@subsection Package Menu Commands
>
> Maybe use @unnumberedsubsec instead of @section, as having it numbered
> might confuse someone into thinking it's a node.

I could do that, but I worry that it would make the manual less consistent.

I get no hits in doc/emacs for @unnumberedsubsec but 257 hits for
@subsection.  In doc/, @unnumberedsubsec is  only used in
doc/lispintro (where I get 37 hits).  Perhaps its better to lean
towards consistency in this case?

If we want to use @unnumberedsubsec more, I'm happy to do the change
though.  It's your call.

Best regards,
Stefan Kangas

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 23 Oct 2019 16:57:19 +0200
> Cc: Drew Adams <drew.adams@oracle.com>, 29420@debbugs.gnu.org
> 
> > Maybe use @unnumberedsubsec instead of @section, as having it numbered
> > might confuse someone into thinking it's a node.
> 
> I could do that, but I worry that it would make the manual less consistent.

I don't see why.  The fact that this particular manual didn't yet use
that command doesn't mean anything.  Try "grep -R" for it in all of
doc/ subdirectories, and you will see that other manuals use it (and
in general you should look for @unnumbered, as there's a family of
these commands).

And having @subsection without a @node is also quite rare, isn't it?

> If we want to use @unnumberedsubsec more, I'm happy to do the change
> though.  It's your call.

I don't mind using the "normal" combination of @node and @subsection
instead, but then it will require some more glue, including submenu
etc.  I suggested @unnumberedsubsec because it's easier: it requires
less work for you.

So it's your call ;-)

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

[Stefan Kangas]

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

Eli Zaretskii <eliz@gnu.org> writes:

> I don't mind using the "normal" combination of @node and @subsection
> instead, but then it will require some more glue, including submenu
> etc.  I suggested @unnumberedsubsec because it's easier: it requires
> less work for you.
>
> So it's your call ;-)

Thanks for laying out the options.  I think I'll go with the normal
combination in this case.

I believe the attached patch does the right things, but it would be
good if someone more familiar with texinfo had a look.

Best regards,
Stefan Kangas


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-subsection-Package-Statuses-to-manual.patch --]
[-- Type: text/x-diff, Size: 4240 bytes --]

From 94d6e9ee801fd766ae188bdfd2588eaad3fb5762 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Tue, 22 Oct 2019 01:42:41 +0200
Subject: [PATCH] Add subsection "Package Statuses" to manual

* doc/emacs/package.texi (Package Menu): New subsection "Package
Statuses".  (Bug#29420)
---
 doc/emacs/package.texi | 76 ++++++++++++++++++++++++++++++++++--------
 1 file changed, 62 insertions(+), 14 deletions(-)

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 1c0f853427..a977abcd29 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -32,6 +32,7 @@ Packages
 
 @menu
 * Package Menu::         Buffer for viewing and managing packages.
+* Package Statuses::     Which statuses a package can have.
 * Package Installation:: Options for package installation.
 * Package Files::        Where packages are installed.
 @end menu
@@ -57,19 +58,12 @@ Package Menu
 The package's status---normally one of @samp{available} (can be
 downloaded from the package archive), @samp{installed},
 @c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
-or @samp{built-in} (included in Emacs by default).  The status
-@samp{external} means the package is not built-in and not from the
-directory specified by @code{package-user-dir} (@pxref{Package
-Files}).  External packages are treated much like built-in: they
-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}.
-@xref{Package Installation}.
+or @samp{built-in} (included in Emacs by default).
+@xref{Package Statuses}.
+
+@item
+Which package archive this package is from, if you have more than one
+package archive enabled.
 
 @item
 A short description of the package.
@@ -139,7 +133,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
 @kindex x @r{(Package Menu)}
@@ -195,6 +189,60 @@ Package Menu
 For example, you can install a package by typing @kbd{i} on the line
 listing that package, followed by @kbd{x}.
 
+@node Package Statuses
+@section Package Statuses
+@cindex package status
+
+A package can have one of the following statuses:
+
+@table @samp
+@item available
+The package is not installed, but can be downloaded and installed from
+the package archive.
+
+@item avail-obso
+The package is available for installation, but a newer version is also
+available.  Packages with this status are hidden by default.
+
+@item built-in
+The package is included in Emacs by default.  It cannot be deleted
+through the package menu, and is not considered for upgrading.
+
+@item dependency
+The package was installed automatically to satisfy a dependency of
+another package.
+
+@item disabled
+The package has been disabled using the @code{package-load-list}
+variable.
+
+@item external
+The package is not built-in and not from the directory specified by
+@code{package-user-dir} (@pxref{Package Files}).  External packages
+are treated much like @samp{built-in} packages and cannot be deleted.
+
+@item held
+The package is held, @xref{Package Installation}.
+
+@item incompat
+The package cannot be installed for some reason, for example because
+it depends on uninstallable packages.
+
+@item installed
+The package is installed.
+
+@item new
+Equivalent to @samp{available}, except that the package became newly
+available on the package archive after your last invocation of
+@kbd{M-x list-packages}.
+
+@item obsolete
+The package is an outdated installed version; in addition to this
+version of the package, a newer version is also installed.
+
+@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
+@end table
+
 @node Package Installation
 @section Package Installation
 
-- 
2.20.1

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: 29420@debbugs.gnu.org,  drew.adams@oracle.com
> Date: Mon, 11 Nov 2019 15:53:33 +0100
> 
> Thanks for laying out the options.  I think I'll go with the normal
> combination in this case.
> 
> I believe the attached patch does the right things, but it would be
> good if someone more familiar with texinfo had a look.

One thing you missed is that the detailed menu in emacs.texi also
needs to be updated, exactly like you did here:

>  @menu
>  * Package Menu::         Buffer for viewing and managing packages.
> +* Package Statuses::     Which statuses a package can have.
>  * Package Installation:: Options for package installation.
>  * Package Files::        Where packages are installed.
>  @end menu

Thanks.

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

[Stefan Kangas]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> I believe the attached patch does the right things, but it would be
>> good if someone more familiar with texinfo had a look.
>
> One thing you missed is that the detailed menu in emacs.texi also
> needs to be updated, exactly like you did here:
>
>>  @menu
>>  * Package Menu::         Buffer for viewing and managing packages.
>> +* Package Statuses::     Which statuses a package can have.
>>  * Package Installation:: Options for package installation.
>>  * Package Files::        Where packages are installed.
>>  @end menu

Thanks, fixed in the attached.  I'll commit it in a couple of days if
there are no further comments.

Best regards,
Stefan Kangas


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-new-node-Package-Statuses-to-manual.patch --]
[-- Type: text/x-diff, Size: 4737 bytes --]

From d141e19f516d3f7b69f46d81504167c633941db9 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Tue, 22 Oct 2019 01:42:41 +0200
Subject: [PATCH] Add new node "Package Statuses" to manual

* doc/emacs/emacs.texi (Top):
* doc/emacs/package.texi (Package Menu): New node "Package
Statuses".  (Bug#29420)
---
 doc/emacs/emacs.texi   |  1 +
 doc/emacs/package.texi | 76 ++++++++++++++++++++++++++++++++++--------
 2 files changed, 63 insertions(+), 14 deletions(-)

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index d23e682cc8..c832d43782 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -1098,6 +1098,7 @@ Top
 Emacs Lisp Packages
 
 * Package Menu::         Buffer for viewing and managing packages.
+* Package Statuses::     Which statuses a package can have.
 * Package Installation:: Options for package installation.
 * Package Files::        Where packages are installed.
 
diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 1c0f853427..a977abcd29 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -32,6 +32,7 @@ Packages
 
 @menu
 * Package Menu::         Buffer for viewing and managing packages.
+* Package Statuses::     Which statuses a package can have.
 * Package Installation:: Options for package installation.
 * Package Files::        Where packages are installed.
 @end menu
@@ -57,19 +58,12 @@ Package Menu
 The package's status---normally one of @samp{available} (can be
 downloaded from the package archive), @samp{installed},
 @c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
-or @samp{built-in} (included in Emacs by default).  The status
-@samp{external} means the package is not built-in and not from the
-directory specified by @code{package-user-dir} (@pxref{Package
-Files}).  External packages are treated much like built-in: they
-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}.
-@xref{Package Installation}.
+or @samp{built-in} (included in Emacs by default).
+@xref{Package Statuses}.
+
+@item
+Which package archive this package is from, if you have more than one
+package archive enabled.
 
 @item
 A short description of the package.
@@ -139,7 +133,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
 @kindex x @r{(Package Menu)}
@@ -195,6 +189,60 @@ Package Menu
 For example, you can install a package by typing @kbd{i} on the line
 listing that package, followed by @kbd{x}.
 
+@node Package Statuses
+@section Package Statuses
+@cindex package status
+
+A package can have one of the following statuses:
+
+@table @samp
+@item available
+The package is not installed, but can be downloaded and installed from
+the package archive.
+
+@item avail-obso
+The package is available for installation, but a newer version is also
+available.  Packages with this status are hidden by default.
+
+@item built-in
+The package is included in Emacs by default.  It cannot be deleted
+through the package menu, and is not considered for upgrading.
+
+@item dependency
+The package was installed automatically to satisfy a dependency of
+another package.
+
+@item disabled
+The package has been disabled using the @code{package-load-list}
+variable.
+
+@item external
+The package is not built-in and not from the directory specified by
+@code{package-user-dir} (@pxref{Package Files}).  External packages
+are treated much like @samp{built-in} packages and cannot be deleted.
+
+@item held
+The package is held, @xref{Package Installation}.
+
+@item incompat
+The package cannot be installed for some reason, for example because
+it depends on uninstallable packages.
+
+@item installed
+The package is installed.
+
+@item new
+Equivalent to @samp{available}, except that the package became newly
+available on the package archive after your last invocation of
+@kbd{M-x list-packages}.
+
+@item obsolete
+The package is an outdated installed version; in addition to this
+version of the package, a newer version is also installed.
+
+@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
+@end table
+
 @node Package Installation
 @section Package Installation
 
-- 
2.20.1

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

[Stefan Kangas]

close 29420 27.1
thanks

Stefan Kangas <stefan@marxist.se> writes:

>> One thing you missed is that the detailed menu in emacs.texi also
>> needs to be updated, exactly like you did here:
>>
>>>  @menu
>>>  * Package Menu::         Buffer for viewing and managing packages.
>>> +* Package Statuses::     Which statuses a package can have.
>>>  * Package Installation:: Options for package installation.
>>>  * Package Files::        Where packages are installed.
>>>  @end menu
>
> Thanks, fixed in the attached.  I'll commit it in a couple of days if
> there are no further comments.

Two months has passed with no further comments, so I've now pushed
this to emacs-27.  Closing.

Best regards,
Stefan Kangas

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

[Drew Adams]

> > `C-h f list-packages' should give you a better description of the
> > display that results.  It wouldn't hurt to succinctly describe each
> > column.
> 
> I added the list of columns.

Thanks.

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

> Thanks.

Thank you.