From: Stefan Kangas <stefan@marxist.se>
To: Eli Zaretskii <eliz@gnu.org>
Cc: 29420@debbugs.gnu.org
Subject: bug#29420: 26.0; doc of `list-packages'
Date: Tue, 22 Oct 2019 01:43:04 +0200 [thread overview]
Message-ID: <CADwFkmmT5wPx_CzjwQA=pi8RKNNe67=FutTN6LCuFbeJ+CSsfA@mail.gmail.com> (raw)
In-Reply-To: <83zhhv4dfa.fsf@gnu.org>
[-- 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
next prev parent reply other threads:[~2019-10-21 23:43 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-11-24 2:05 bug#29420: 26.0; doc of `list-packages' Drew Adams
2017-11-24 14:52 ` Eli Zaretskii
2019-10-19 2:04 ` Stefan Kangas
2019-10-19 5:25 ` Drew Adams
2019-10-19 6:42 ` Eli Zaretskii
2019-10-20 15:42 ` Stefan Kangas
2019-10-20 15:58 ` Eli Zaretskii
2019-10-21 23:43 ` Stefan Kangas [this message]
2019-10-22 15:20 ` Eli Zaretskii
2019-10-23 14:57 ` Stefan Kangas
2019-10-23 15:47 ` Eli Zaretskii
2019-11-11 14:53 ` Stefan Kangas
2019-11-14 11:07 ` Eli Zaretskii
2019-11-15 3:38 ` Stefan Kangas
2020-01-15 1:27 ` Stefan Kangas
[not found] <<eb6a7e65-28f5-4a3a-86af-c4cca01e0427@default>
[not found] ` <<838tevafus.fsf@gnu.org>
2017-11-24 17:02 ` Drew Adams
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CADwFkmmT5wPx_CzjwQA=pi8RKNNe67=FutTN6LCuFbeJ+CSsfA@mail.gmail.com' \
--to=stefan@marxist.se \
--cc=29420@debbugs.gnu.org \
--cc=eliz@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.