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

[Stefan Kangas <stefan@marxist.se>]

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