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

[Eli Zaretskii <eliz@gnu.org>]

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