GNU bug report logs - #29420
26.0; doc of `list-packages'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 29420 in the body.
You can then email your comments to 29420 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.0; doc of `list-packages'
Date: Thu, 23 Nov 2017 18:05:57 -0800 (PST)

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

Message #8 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 29420 <at> debbugs.gnu.org
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Fri, 24 Nov 2017 16:52:43 +0200

> Date: Thu, 23 Nov 2017 18:05:57 -0800 (PST)
> From: Drew Adams <drew.adams <at> 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.

Message #11 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 29420 <at> debbugs.gnu.org
Subject: RE: bug#29420: 26.0; doc of `list-packages'
Date: Fri, 24 Nov 2017 09:02:46 -0800 (PST)

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

Message #14 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 29420 <at> debbugs.gnu.org
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Sat, 19 Oct 2019 04:04:21 +0200

[Message part 1 (text/plain, inline)]

tags 29420 + patch
quit

Drew Adams <drew.adams <at> 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

[0001-Document-package-statuses-better.patch (application/octet-stream, attachment)]

Message #19 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 29420 <at> debbugs.gnu.org
Subject: RE: bug#29420: 26.0; doc of `list-packages'
Date: Sat, 19 Oct 2019 05:25:28 +0000 (UTC)

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

Message #22 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 29420 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Sat, 19 Oct 2019 09:42:44 +0300

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

Message #25 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 29420 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Sun, 20 Oct 2019 17:42:09 +0200

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> 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

[0001-Add-section-on-Package-Status-to-info-manual.patch (application/octet-stream, attachment)]

Message #28 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 29420 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Sun, 20 Oct 2019 18:58:01 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sun, 20 Oct 2019 17:42:09 +0200
> Cc: Drew Adams <drew.adams <at> oracle.com>, 29420 <at> 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.

Message #31 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 29420 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Tue, 22 Oct 2019 01:43:04 +0200

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> 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

[0001-Add-subsection-Package-Statuses-to-manual.patch (application/octet-stream, attachment)]

Message #34 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 29420 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Tue, 22 Oct 2019 18:20:42 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Tue, 22 Oct 2019 01:43:04 +0200
> Cc: Drew Adams <drew.adams <at> oracle.com>, 29420 <at> 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.

Message #37 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 29420 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Wed, 23 Oct 2019 16:57:19 +0200

Eli Zaretskii <eliz <at> 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

Message #40 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 29420 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Wed, 23 Oct 2019 18:47:28 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Wed, 23 Oct 2019 16:57:19 +0200
> Cc: Drew Adams <drew.adams <at> oracle.com>, 29420 <at> 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 ;-)

Message #43 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 29420 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Mon, 11 Nov 2019 15:53:33 +0100

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> 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

[0001-Add-subsection-Package-Statuses-to-manual.patch (text/x-diff, inline)]

From 94d6e9ee801fd766ae188bdfd2588eaad3fb5762 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas <at> 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

Message #46 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 29420 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Thu, 14 Nov 2019 13:07:27 +0200

> From: Stefan Kangas <stefan <at> marxist.se>
> Cc: 29420 <at> debbugs.gnu.org,  drew.adams <at> 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.

Message #49 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 29420 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Fri, 15 Nov 2019 04:38:30 +0100

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> 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

[0001-Add-new-node-Package-Statuses-to-manual.patch (text/x-diff, inline)]

From d141e19f516d3f7b69f46d81504167c633941db9 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas <at> 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

Message #52 received at 29420 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 29420 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#29420: 26.0; doc of `list-packages'
Date: Wed, 15 Jan 2020 02:27:13 +0100

close 29420 27.1
thanks

Stefan Kangas <stefan <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.