procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of package-menu commands

Browse source 
* doc/emacs/package.texi (Package Menu): Document that some
package-menu filters accept lists of values interactively.

* lisp/emacs-lisp/package.el (package-menu-execute)
(package-menu-hide-package, package-menu-describe-package)
(package-menu-mark-delete, package-menu-mark-install)
(package-menu-mark-unmark, package-menu-backup-unmark)
(package-menu-quick-help, package-menu-get-status)
(package-menu--find-upgrades, package-menu-mark-upgrades)
(package-menu-filter-by-archive)
(package-menu-filter-by-description)
(package-menu-filter-by-keyword)
(package-menu-filter-by-name-or-description)
(package-menu-filter-by-name, package-menu-filter-by-status)
(package-menu-filter-by-version, package-menu-filter-marked)
(package-menu-describe-package): Doc fixes.
This commit is contained in:
Eli Zaretskii 2023-05-18 09:41:59 +03:00
parent d879847cd4
commit af3b0dc53f
2 changed files with 71 additions and 58 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
doc/emacs/package.texi
View file

@ -207,7 +207,8 @@ from lower-priority archives (@code{package-menu-toggle-hiding}).
@findex package-menu-filter-by-archive @findex package-menu-filter-by-archive
Filter package list by archive (@code{package-menu-filter-by-archive}). Filter package list by archive (@code{package-menu-filter-by-archive}).
This prompts for a package archive (e.g., @samp{gnu}), then shows only This prompts for a package archive (e.g., @samp{gnu}), then shows only
packages from that archive. packages from that archive. You can specify several archives by
typing their names separated by commas.
@item / d @item / d
@kindex / d @r{(Package Menu)} @kindex / d @r{(Package Menu)}
@ -222,7 +223,8 @@ matching that regexp.
@findex package-menu-filter-by-keyword @findex package-menu-filter-by-keyword
Filter package list by keyword (@code{package-menu-filter-by-keyword}). Filter package list by keyword (@code{package-menu-filter-by-keyword}).
This prompts for a keyword (e.g., @samp{games}), then shows only This prompts for a keyword (e.g., @samp{games}), then shows only
packages with that keyword. packages with that keyword. You can specify several keywords by
typing them separated by commas.
@item / N @item / N
@kindex / N @r{(Package Menu)} @kindex / N @r{(Package Menu)}
@ -243,16 +245,19 @@ with names matching that regexp.
@kindex / s @r{(Package Menu)} @kindex / s @r{(Package Menu)}
@findex package-menu-filter-by-status @findex package-menu-filter-by-status
Filter package list by status (@code{package-menu-filter-by-status}). Filter package list by status (@code{package-menu-filter-by-status}).
This prompts for one or more statuses (e.g., @samp{available}), then This prompts for one or more statuses (e.g., @samp{available},
shows only packages with matching status. @pxref{Package Statuses}), then shows only packages with matching
status. You can specify several status values by typing them
separated by commas.
@item / v @item / v
@kindex / v @r{(Package Menu)} @kindex / v @r{(Package Menu)}
@findex package-menu-filter-by-version @findex package-menu-filter-by-version
Filter package list by version (@code{package-menu-filter-by-version}). Filter package list by version (@code{package-menu-filter-by-version}).
This prompts first for one of the qualifiers @samp{<}, @samp{>} or This prompts first for one of the comparison symbols @samp{<},
@samp{=}, and then a package version, and shows packages that has a @samp{>} or @samp{=} and for a version string, and then shows packages
lower, equal or higher version than the one specified. whose versions are correspondingly lower, equal or higher than the
version you typed.
@item / m @item / m
@kindex / m @r{(Package Menu)} @kindex / m @r{(Package Menu)}

110
lisp/emacs-lisp/package.el
View file

@ -3588,7 +3588,8 @@ The regexp is added to the list in the user option
`package-hidden-regexps' and saved for future sessions. `package-hidden-regexps' and saved for future sessions.
To unhide a package, type To unhide a package, type
`\\[customize-variable] RET package-hidden-regexps'. `\\[customize-variable] RET package-hidden-regexps', and then modify
the regexp such that it no longer matches the package's name.
Type \\[package-menu-toggle-hiding] to toggle package hiding." Type \\[package-menu-toggle-hiding] to toggle package hiding."
(declare (interactive-only "change `package-hidden-regexps' instead.")) (declare (interactive-only "change `package-hidden-regexps' instead."))
@ -3615,7 +3616,9 @@ Type \\[package-menu-toggle-hiding] to toggle package hiding."
(defun package-menu-describe-package (&optional button) (defun package-menu-describe-package (&optional button)
"Describe the current package. "Describe the current package.
If optional arg BUTTON is non-nil, describe its associated package." The current package is the package at point.
If optional arg BUTTON is non-nil, describe its associated
package(s); this is always nil in interactive invocations."
(interactive nil package-menu-mode) (interactive nil package-menu-mode)
(let ((pkg-desc (if button (button-get button 'package-desc) (let ((pkg-desc (if button (button-get button 'package-desc)
(tabulated-list-get-id)))) (tabulated-list-get-id))))
@ -3625,7 +3628,8 @@ If optional arg BUTTON is non-nil, describe its associated package."
;; fixme numeric argument ;; fixme numeric argument
(defun package-menu-mark-delete (&optional _num) (defun package-menu-mark-delete (&optional _num)
"Mark a package for deletion and move to the next line." "Mark the current package for deletion and move to the next line.
The current package is the package at point."
(interactive "p" package-menu-mode) (interactive "p" package-menu-mode)
(package--ensure-package-menu-mode) (package--ensure-package-menu-mode)
(if (member (package-menu-get-status) (if (member (package-menu-get-status)
@ -3634,7 +3638,8 @@ If optional arg BUTTON is non-nil, describe its associated package."
(forward-line))) (forward-line)))
(defun package-menu-mark-install (&optional _num) (defun package-menu-mark-install (&optional _num)
"Mark a package for installation and move to the next line." "Mark the current package for installation and move to the next line.
The current package is the package at point."
(interactive "p" package-menu-mode) (interactive "p" package-menu-mode)
(package--ensure-package-menu-mode) (package--ensure-package-menu-mode)
(if (member (package-menu-get-status) '("available" "avail-obso" "new" "dependency")) (if (member (package-menu-get-status) '("available" "avail-obso" "new" "dependency"))
@ -3642,13 +3647,14 @@ If optional arg BUTTON is non-nil, describe its associated package."
(forward-line))) (forward-line)))
(defun package-menu-mark-unmark (&optional _num) (defun package-menu-mark-unmark (&optional _num)
"Clear any marks on a package and move to the next line." "Clear any marks on the current package and move to the next line.
The current package is the package at point."
(interactive "p" package-menu-mode) (interactive "p" package-menu-mode)
(package--ensure-package-menu-mode) (package--ensure-package-menu-mode)
(tabulated-list-put-tag " " t)) (tabulated-list-put-tag " " t))
(defun package-menu-backup-unmark () (defun package-menu-backup-unmark ()
"Back up one line and clear any marks on that package." "Back up one line and clear any marks on that line's package."
(interactive nil package-menu-mode) (interactive nil package-menu-mode)
(package--ensure-package-menu-mode) (package--ensure-package-menu-mode)
(forward-line -1) (forward-line -1)
@ -3686,15 +3692,15 @@ If optional arg BUTTON is non-nil, describe its associated package."
(package--prettify-quick-help-key (cons desc 0)))) (package--prettify-quick-help-key (cons desc 0))))
(defun package-menu-quick-help () (defun package-menu-quick-help ()
"Show short key binding help for `package-menu-mode'. "Show short help for key bindings in `package-menu-mode'.
The full list of keys can be viewed with \\[describe-mode]." You can view the full list of keys with \\[describe-mode]."
(interactive nil package-menu-mode) (interactive nil package-menu-mode)
(package--ensure-package-menu-mode) (package--ensure-package-menu-mode)
(message (mapconcat #'package--prettify-quick-help-key (message (mapconcat #'package--prettify-quick-help-key
package--quick-help-keys "\n"))) package--quick-help-keys "\n")))
(defun package-menu-get-status () (defun package-menu-get-status ()
"Return status text of package at point in Package Menu." "Return status description of package at point in Package Menu."
(package--ensure-package-menu-mode) (package--ensure-package-menu-mode)
(let* ((id (tabulated-list-get-id)) (let* ((id (tabulated-list-get-id))
(entry (and id (assoc id tabulated-list-entries)))) (entry (and id (assoc id tabulated-list-entries))))
@ -3723,8 +3729,8 @@ consideration."
(defun package-menu--find-upgrades () (defun package-menu--find-upgrades ()
"In Package Menu, return an alist of packages that can be upgraded. "In Package Menu, return an alist of packages that can be upgraded.
The alist has the same form as `package-alist', namely a list The alist has the same form as `package-alist', namely a list
of (PKG . DESCS), but where DESCS is the `package-desc' object of elements of the form (PKG . DESCS), but where DESCS is the `package-desc'
corresponding to the newer version." object corresponding to the newer version."
(let (installed available upgrades) (let (installed available upgrades)
;; Build list of installed/available packages in this buffer. ;; Build list of installed/available packages in this buffer.
(dolist (entry tabulated-list-entries) (dolist (entry tabulated-list-entries)
@ -3775,10 +3781,10 @@ Implementation of `package-menu-mark-upgrades'."
(defun package-menu-mark-upgrades () (defun package-menu-mark-upgrades ()
"Mark all upgradable packages in the Package Menu. "Mark all upgradable packages in the Package Menu.
For each installed package with a newer version available, place For each installed package for which a newer version is available,
an (I)nstall flag on the available version and a (D)elete flag on place an (I)nstall flag on the available version and a (D)elete flag
the installed version. A subsequent \\[package-menu-execute] on the installed version. A subsequent \\[package-menu-execute] command will upgrade
call will upgrade the package. the marked packages.
If there's an async refresh operation in progress, the flags will If there's an async refresh operation in progress, the flags will
be placed as part of `package-menu--post-refresh' instead of be placed as part of `package-menu--post-refresh' instead of
@ -3897,17 +3903,19 @@ packages list, respectively."
(package--save-selected-packages package-selected-packages))) (package--save-selected-packages package-selected-packages)))
(defun package-menu-execute (&optional noquery) (defun package-menu-execute (&optional noquery)
"Perform marked Package Menu actions. "Perform Package Menu actions on marked packages.
Packages marked for installation are downloaded and installed, Packages marked for installation are downloaded and installed,
packages marked for deletion are removed, and packages marked for packages marked for deletion are removed, and packages marked for
upgrading are downloaded and upgraded. upgrading are downloaded and upgraded.
If no packages are marked, the action taken depends on the state If no packages are marked, the action taken depends on the state
of the package under point. If it's not already installed, this of the current package, the one at point. If it's not already
command will install the package, and if it's installed, it will installed, this command will install the package; if it's installed,
delete the package. the command will delete the package.
Optional argument NOQUERY non-nil means do not ask the user to confirm." Optional argument NOQUERY non-nil means do not ask the user to
confirm the installations/deletions; this is always nil in interactive
invocations."
(interactive nil package-menu-mode) (interactive nil package-menu-mode)
(package--ensure-package-menu-mode) (package--ensure-package-menu-mode)
(let (install-list delete-list cmd pkg-desc) (let (install-list delete-list cmd pkg-desc)
@ -4158,13 +4166,12 @@ the header line of the first column."
(defun package-menu-filter-by-archive (archive) (defun package-menu-filter-by-archive (archive)
"Filter the \"*Packages*\" buffer by ARCHIVE. "Filter the \"*Packages*\" buffer by ARCHIVE.
Display only packages from package archive ARCHIVE. Display only packages from package archive ARCHIVE.
ARCHIVE can be the name of a single archive (a string), or
a list of archive names. If ARCHIVE is nil or an empty
string, show all packages.
When called interactively, prompt for ARCHIVE, which can be a When called interactively, prompt for ARCHIVE. To specify
comma-separated string. If ARCHIVE is empty, show all packages. several archives, type their names separated by commas."
When called from Lisp, ARCHIVE can be a string or a list of
strings. If ARCHIVE is nil or the empty string, show all
packages."
(interactive (list (completing-read-multiple (interactive (list (completing-read-multiple
"Filter by archive (comma separated): " "Filter by archive (comma separated): "
(mapcar #'car package-archives))) (mapcar #'car package-archives)))
@ -4180,9 +4187,9 @@ packages."
(concat "archive:" (string-join archives ","))))) (concat "archive:" (string-join archives ",")))))
(defun package-menu-filter-by-description (description) (defun package-menu-filter-by-description (description)
"Filter the \"*Packages*\" buffer by DESCRIPTION regexp. "Filter the \"*Packages*\" buffer by the regexp DESCRIPTION.
Display only packages with a description that matches regexp Display only packages whose description matches the regexp
DESCRIPTION. given as DESCRIPTION.
When called interactively, prompt for DESCRIPTION. When called interactively, prompt for DESCRIPTION.
@ -4199,14 +4206,16 @@ If DESCRIPTION is nil or the empty string, show all packages."
(defun package-menu-filter-by-keyword (keyword) (defun package-menu-filter-by-keyword (keyword)
"Filter the \"*Packages*\" buffer by KEYWORD. "Filter the \"*Packages*\" buffer by KEYWORD.
Display only packages with specified KEYWORD. Display only packages whose keywords match the specified KEYWORD.
KEYWORD can be a string or a list of strings. If KEYWORD is nil
or the empty string, show all packages.
When called interactively, prompt for KEYWORD, which can be a In addition to package keywords, KEYWORD can include the name(s)
comma-separated string. If KEYWORD is empty, show all packages. of archive(s) and the package status, such as \"available\"
or \"built-in\" or \"obsolete\".
When called from Lisp, KEYWORD can be a string or a list of When called interactively, prompt for KEYWORD. To specify several
strings. If KEYWORD is nil or the empty string, show all keywords, type them separated by commas."
packages."
(interactive (list (completing-read-multiple (interactive (list (completing-read-multiple
"Keywords (comma separated): " "Keywords (comma separated): "
(package-all-keywords))) (package-all-keywords)))
@ -4224,8 +4233,8 @@ packages."
'package-menu-filter #'package-menu-filter-by-keyword "27.1") 'package-menu-filter #'package-menu-filter-by-keyword "27.1")
(defun package-menu-filter-by-name-or-description (name-or-description) (defun package-menu-filter-by-name-or-description (name-or-description)
"Filter the \"*Packages*\" buffer by NAME-OR-DESCRIPTION regexp. "Filter the \"*Packages*\" buffer by the regexp NAME-OR-DESCRIPTION.
Display only packages with a name-or-description that matches regexp Display only packages whose name or description matches the regexp
NAME-OR-DESCRIPTION. NAME-OR-DESCRIPTION.
When called interactively, prompt for NAME-OR-DESCRIPTION. When called interactively, prompt for NAME-OR-DESCRIPTION.
@ -4246,8 +4255,8 @@ packages."
(format "name-or-desc:%s" name-or-description)))) (format "name-or-desc:%s" name-or-description))))
(defun package-menu-filter-by-name (name) (defun package-menu-filter-by-name (name)
"Filter the \"*Packages*\" buffer by NAME regexp. "Filter the \"*Packages*\" buffer by the regexp NAME.
Display only packages with name that matches regexp NAME. Display only packages whose name matches the regexp NAME.
When called interactively, prompt for NAME. When called interactively, prompt for NAME.
@ -4265,13 +4274,11 @@ If NAME is nil or the empty string, show all packages."
(defun package-menu-filter-by-status (status) (defun package-menu-filter-by-status (status)
"Filter the \"*Packages*\" buffer by STATUS. "Filter the \"*Packages*\" buffer by STATUS.
Display only packages with specified STATUS. Display only packages with specified STATUS.
STATUS can be a single status, a string, or a list of strings.
If STATUS is nil or the empty string, show all packages.
When called interactively, prompt for STATUS, which can be a When called interactively, prompt for STATUS. To specify
comma-separated string. If STATUS is empty, show all packages. several possible status values, type them seperated by commas."
When called from Lisp, STATUS can be a string or a list of
strings. If STATUS is nil or the empty string, show all
packages."
(interactive (list (completing-read "Filter by status: " (interactive (list (completing-read "Filter by status: "
'("avail-obso" '("avail-obso"
"available" "available"
@ -4300,12 +4307,12 @@ packages."
(defun package-menu-filter-by-version (version predicate) (defun package-menu-filter-by-version (version predicate)
"Filter the \"*Packages*\" buffer by VERSION and PREDICATE. "Filter the \"*Packages*\" buffer by VERSION and PREDICATE.
Display only packages with a matching version. Display only packages whose version satisfies the condition
defined by VERSION and PREDICATE.
When called interactively, prompt for one of the qualifiers `<', When called interactively, prompt for one of the comparison operators
`>' or `=', and a package version. Show only packages that has a `<', `>' or `=', and for a version. Show only packages whose version
lower (`<'), equal (`=') or higher (`>') version than the is lower (`<'), equal (`=') or higher (`>') than the specified VERSION.
specified one.
When called from Lisp, VERSION should be a version string and When called from Lisp, VERSION should be a version string and
PREDICATE should be the symbol `=', `<' or `>'. PREDICATE should be the symbol `=', `<' or `>'.
@ -4343,7 +4350,8 @@ If VERSION is nil or the empty string, show all packages."
(format "versions:%s%s" predicate version))))) (format "versions:%s%s" predicate version)))))
(defun package-menu-filter-marked () (defun package-menu-filter-marked ()
"Filter \"*Packages*\" buffer by non-empty upgrade mark. "Filter \"*Packages*\" buffer by non-empty mark.
Show only the packages that have been marked for installation or deletion.
Unlike other filters, this leaves the marks intact." Unlike other filters, this leaves the marks intact."
(interactive nil package-menu-mode) (interactive nil package-menu-mode)
(package--ensure-package-menu-mode) (package--ensure-package-menu-mode)