@@ -107,7 +107,7 @@ Return nil if the image cannot be found."
(bui-newline)))))))
(defun guix-about-insert-content ()
- "Insert Emacs-Guix 'about' info into the current buffer."
+ "Insert Emacs-Guix \\='about\\=' info into the current buffer."
(guix-insert-logo)
(apply #'fancy-splash-insert guix-about-specifications)
(goto-char (point-min))
@@ -18,6 +18,8 @@
;; You should have received a copy of the GNU General Public License
;; along with Emacs-Guix. If not, see <http://www.gnu.org/licenses/>.
+;;; Commentary:
+
;;; Code:
(defconst guix-config-name "@PACKAGE_NAME@"
@@ -65,8 +67,7 @@
"Directory with Guix compiled (*.go) files.")
(defconst guix-config-guile-program "@GUILE@"
- "Name of the 'guile' executable defined at configure time.")
+ "Name of the \\='guile\\=' executable defined at configure time.")
(provide 'guix-build-config)
-
-;;; guix-build-config.el ends here
+;;; guix-build-config.el.in ends here
@@ -93,12 +93,12 @@
(defface guix-build-log-phase-success
'((t))
- "Face for the 'succeeded' word of a phase line."
+ "Face for the \"succeeded\" word of a phase line."
:group 'guix-build-log-faces)
(defface guix-build-log-phase-fail
'((t :inherit error))
- "Face for the 'failed' word of a phase line."
+ "Face for the \"failed\" word of a phase line."
:group 'guix-build-log-faces)
(defface guix-build-log-phase-seconds
@@ -116,7 +116,7 @@
(defvar guix-build-log-phase-start-regexp
(concat "^starting phase " guix-build-log-phase-name-regexp)
- "Regexp for the start line of a 'build' phase.")
+ "Regexp for the start line of a \\='build\\=' phase.")
(defvar guix-build-log-imenu-generic-expression
`((nil ,guix-build-log-phase-start-regexp 1))
@@ -125,8 +125,8 @@
(defun guix-build-log-title-regexp (&optional state)
"Return regexp for the log title.
STATE is a symbol denoting a state of the title. It should be
-`start', `fail', `success' or `nil' (for a regexp matching any
-state)."
+\\='start\\=', \\='fail\\=', \\='success\\=' or \\='nil\\=' (for a
+regexp matching any state)."
(let* ((word-rx (rx (1+ (any word "-"))))
(state-rx (cond ((eq state 'start) (concat word-rx "started"))
((eq state 'success) (concat word-rx "succeeded"))
@@ -137,9 +137,10 @@ state)."
t)))
(defun guix-build-log-phase-end-regexp (&optional state)
- "Return regexp for the end line of a 'build' phase.
+ "Return regexp for the end line of a \\='build\\=' phase.
STATE is a symbol denoting how a build phase was ended. It should be
-`fail', `success' or `nil' (for a regexp matching any state)."
+\\='fail\\=', \\='success\\=' or \\='nil\\=' (for a regexp matching
+any state)."
(let ((state-rx (cond ((eq state 'success) "succeeded")
((eq state 'fail) "failed")
(t (regexp-opt '("succeeded" "failed"))))))
@@ -153,7 +154,7 @@ STATE is a symbol denoting how a build phase was ended. It should be
;; For efficiency, it is better to have a regexp for the general line
;; of the phase end, then to call the function all the time.
(guix-build-log-phase-end-regexp)
- "Regexp for the end line of a 'build' phase.")
+ "Regexp for the end line of a \\='build\\=' phase.")
(defvar guix-build-log-font-lock-keywords
`((,(guix-build-log-title-regexp 'start)
@@ -192,9 +193,9 @@ STATE is a symbol denoting how a build phase was ended. It should be
(define-key map (kbd "<backtab>") 'guix-build-log-phase-toggle-all)
(define-key map [(shift tab)] 'guix-build-log-phase-toggle-all)
map)
- "Parent keymap for 'build-log' buffers.
+ "Parent keymap for \\='build-log\\=' buffers.
For `guix-build-log-mode' this map is used as is.
-For `guix-build-log-minor-mode' this map is prefixed with 'C-c'.")
+For `guix-build-log-minor-mode' this map is prefixed with \`C-c'.")
(defvar guix-build-log-mode-map
(let ((map (make-sparse-keymap)))
@@ -214,8 +215,9 @@ For `guix-build-log-minor-mode' this map is prefixed with 'C-c'.")
(defun guix-build-log-phase-start (&optional with-header?)
"Return the start point of the current build phase.
-If WITH-HEADER? is non-nil, do not skip 'starting phase ...' header.
-Return nil, if there is no phase start before the current point."
+If WITH-HEADER? is non-nil, do not skip \\='starting phase ...\\='
+header. Return nil, if there is no phase start before the current
+point."
(save-excursion
(end-of-line)
(when (re-search-backward guix-build-log-phase-start-regexp nil t)
@@ -343,7 +345,7 @@ When Guix Build Log minor mode is enabled, it highlights build
log in the current buffer. This mode can be enabled
programmatically using hooks, like this:
- (add-hook 'shell-mode-hook 'guix-build-log-minor-mode)
+ (add-hook \\='shell-mode-hook \\='guix-build-log-minor-mode)
\\{guix-build-log-minor-mode-map}"
:init-value nil
@@ -80,7 +80,7 @@
(defvar guix-command-complex-with-shared-arguments
'("potluck" "system")
"List of guix commands which have subcommands with shared options.
-I.e., 'guix foo --help' is the same as 'guix foo bar --help'.")
+I.e., \\='guix foo --help\\=' is the same as \\='guix foo bar --help\\='.")
(defun guix-command-action-name (&optional commands &rest name-parts)
"Return name of action function for guix COMMANDS."
@@ -484,7 +484,7 @@ to be modified."
argument))
(defun guix-command-improve-arguments (arguments commands)
- "Return ARGUMENTS for 'guix COMMANDS ...' modified for transient interface."
+ "Return ARGUMENTS for \\='guix COMMANDS ...\\=' modified for transient interface."
(let ((improvers (cons 'guix-command-improve-common-argument
(bui-assoc-value guix-command-argument-improvers
commands))))
@@ -493,7 +493,7 @@ to be modified."
arguments)))
(defun guix-command-parse-arguments (&optional commands)
- "Return a list of parsed 'guix COMMANDS ...' arguments."
+ "Return a list of parsed \\='guix COMMANDS ...\\=' arguments."
(with-temp-buffer
(insert (guix-help-string commands))
(let (args)
@@ -585,7 +585,7 @@ to be modified."
:doc "build inputs of the specified packages"
:fun 'guix-read-package-names-string)))
"Alist of guix commands and additional arguments for them.
-These are 'fake' arguments that are not presented in 'guix' shell
+These are \\='fake\\=' arguments that are not presented in \\='guix\\=' shell
commands.")
(defun guix-command-additional-arguments (&optional commands)
@@ -601,7 +601,7 @@ commands.")
;; commands.
(defun guix-command--all-arguments (&optional commands)
- "Return list of all arguments for 'guix COMMANDS ...'."
+ "Return list of all arguments for \\='guix COMMANDS ...\\='."
(let ((parsed (guix-command-parse-arguments commands)))
(append (guix-command-improve-arguments parsed commands)
(guix-command-additional-arguments commands))))
@@ -612,7 +612,7 @@ commands.")
(defun guix-command-all-arguments (&optional commands)
;; Note: `guix-command-arguments' name cannot be used because function
;; with this name is generated by `transient-define-prefix'.
- "Return list of arguments for 'guix COMMANDS ...'."
+ "Return list of arguments for \\='guix COMMANDS ...\\='."
(let ((command (car commands)))
(if (member command
guix-command-complex-with-shared-arguments)
@@ -700,7 +700,7 @@ Each function is called on the returned arguments in turn.")
(defvar guix-command-rest-arg-regexp
(rx string-start "-- " (group (+ any)))
- "Regexp to match a string with the 'rest' arguments.")
+ "Regexp to match a string with the \\='rest\\=' arguments.")
(defun guix-command-replace-args (args predicate modifier)
"Replace arguments matching PREDICATE from ARGS.
@@ -740,39 +740,37 @@ arguments into multiple subarguments."
:group 1))
(defun guix-command-post-process-rest-multiple (args)
- "Modify ARGS by splitting '-- ARG ...' into multiple subarguments
-and moving them to the end of ARGS list.
-Remove '-- ' string."
+ "Modify ARGS and remove '-- ' string.
+Do that by splitting \\='-- ARG ...\\=' into multiple subarguments
+and moving them to the end of ARGS list."
(guix-command-post-process-matching-args
args guix-command-rest-arg-regexp
:group 1
:split? t))
(defun guix-command-post-process-rest-multiple-leave (args)
- "Modify ARGS by splitting '-- ARG ...' into multiple subarguments
-and moving them to the end of ARGS list.
-Leave '--' string as a separate argument."
+ "Modify ARGS and leave '--' string as a separate argument.
+Do that by splitting \\='-- ARG ...\\=' into multiple subarguments
+and moving them to the end of ARGS list."
(guix-command-post-process-matching-args
args guix-command-rest-arg-regexp
:split? t))
(defun guix-command-post-process-package-args (args)
- "Adjust transient ARGS for 'guix package' command."
+ "Adjust transient ARGS for \\='guix package\\=' command."
(guix-command-post-process-matching-args
args (rx string-start (or "--install " "--remove ") (+ any))
:split? t))
(defun guix-command-post-process-environment-packages (args)
- "Adjust transient ARGS for specified packages of 'guix environment'
-command."
+ "Adjust ARGS for specified packages of \\='guix environment\\=' command."
(guix-command-post-process-matching-args
args (rx string-start "++packages " (group (+ any)))
:group 1
:split? t))
(defun guix-command-post-process-environment-ad-hoc (args)
- "Adjust transient ARGS for '--ad-hoc' argument of 'guix environment'
-command."
+ "Adjust ARGS for '--ad-hoc' argument of \\='guix environment\\=' command."
(guix-command-post-process-matching-args
args (rx string-start "--ad-hoc " (+ any))
:split? t))
@@ -799,7 +797,7 @@ command."
:name "shell" :char ?s :doc "Run in shell")
(guix-command-make-argument
:name "copy" :char ?c :doc "Copy command line"))
- "List of default 'execute' action arguments.")
+ "List of default \\='execute\\=' action arguments.")
(defvar guix-command-additional-execute-arguments
(let ((graph-arg (guix-command-make-argument
@@ -813,10 +811,10 @@ command."
:name "view" :char ?v :doc "View map"))
(("system" "shepherd-graph") ,graph-arg)
(("system" "extension-graph") ,graph-arg)))
- "Alist of guix commands and additional 'execute' action arguments.")
+ "Alist of guix commands and additional \\='execute\\=' action arguments.")
(defun guix-command-execute-arguments (commands)
- "Return a list of 'execute' action arguments for COMMANDS."
+ "Return a list of \\='execute\\=' action arguments for COMMANDS."
(mapcar (lambda (arg)
(guix-command-modify-argument arg
:action? t
@@ -856,7 +854,7 @@ See also `guix-command-default-executors'.")
(bui-assoc-value guix-command-default-executors name)))
(defun guix-run-environment-command-in-repl (args)
- "Run 'guix ARGS ...' environment command in Guix REPL."
+ "Run \\='guix ARGS ...\\=' environment command in Guix REPL."
;; As 'guix environment' usually tries to run another process, it may
;; be fun but not wise to run this command in Geiser REPL.
(when (or (member "--dry-run" args)
@@ -871,7 +869,7 @@ Do you really want to execute this command in Geiser REPL? "
(guix-run-command-in-repl args)))
(defun guix-run-pull-command-in-repl (args)
- "Run 'guix ARGS ...' pull command in Guix REPL.
+ "Run \\='guix ARGS ...\\=' pull command in Guix REPL.
Perform pull-specific actions after operation, see
`guix-after-pull-hook' and `guix-update-after-pull'."
(guix-eval-in-repl
@@ -882,8 +880,8 @@ Perform pull-specific actions after operation, see
'pull)))
(defun guix-run-view-build-log (args)
- "Add --log-file to ARGS, run 'guix ARGS ...' build command, and
-open the log file(s)."
+ "Add --log-file to ARGS, run \\='guix ARGS ...\\=' build command.
+Then open the log file(s)."
(let* ((args (if (member "--log-file" args)
args
(cl-list* (car args) "--log-file" (cdr args))))
@@ -895,7 +893,7 @@ open the log file(s)."
(declare-function guix-make-view-graph "guix-graph" t)
(defun guix-run-view-graph (args)
- "Run 'guix ARGS ...' graph command, make the image and open it."
+ "Run \\='guix ARGS ...\\=' graph command, make the image and open it."
(require 'guix-graph)
(guix-make-view-graph
(if (member "--backend=d3js" args) "d3js" "graphviz")
@@ -909,7 +907,7 @@ open the log file(s)."
'guix-output-to-file args graph-file)))))))
(defun guix-run-view-size-map (args)
- "Run 'guix ARGS ...' size command, and open the map file."
+ "Run \\='guix ARGS ...\\=' size command, and open the map file."
(let* ((wished-map-file
(cl-some (lambda (arg)
(and (string-match "--map-file=\\(.+\\)" arg)
@@ -955,7 +953,7 @@ EXECUTOR function is called with the current command line arguments."
',commands (transient-args (transient-current-command))))))))
(defun guix-command-generate-popup-actions (actions &optional commands)
- "Generate 'popup' commands from ACTIONS arguments for guix COMMANDS."
+ "Generate \\='popup\\=' commands from ACTIONS arguments for guix COMMANDS."
(dolist (action actions)
(let ((fun (guix-command-argument-fun action)))
(unless (fboundp fun)
@@ -964,7 +962,7 @@ EXECUTOR function is called with the current command line arguments."
(list (guix-command-argument-name action)))))))))
(defun guix-command-generate-execute-actions (actions &optional commands)
- "Generate 'execute' commands from ACTIONS arguments for guix COMMANDS."
+ "Generate \\='execute\\=' commands from ACTIONS arguments for guix COMMANDS."
(dolist (action actions)
(let ((fun (guix-command-argument-fun action)))
(unless (fboundp fun)
@@ -974,7 +972,7 @@ EXECUTOR function is called with the current command line arguments."
,commands))))))
(defun guix-command-generate-prefix (name &optional commands)
- "Define NAME prefix with 'guix COMMANDS ...' interface."
+ "Define NAME prefix with \\='guix COMMANDS ...\\=' interface."
(let* ((command (car commands))
(man-page (concat "guix" (and command (concat "-" command))))
(doc (format "Transient for '%s' command."
@@ -59,7 +59,7 @@
nil))
"Directory with Scheme files for Emacs-Guix package.
It should be a directory where Guile modules are placed, i.e. a
-directory with 'emacs-guix' sub-directory.")
+directory with \\='emacs-guix\\=' sub-directory.")
(defvar guix-image-directory
(or guix-config-image-directory
@@ -59,7 +59,7 @@
"Directory with Guix compiled (*.go) files.")
(defconst guix-config-guile-program nil
- "Name of the 'guile' executable defined at configure time.")
+ "Name of the \\='guile\\=' executable defined at configure time.")
(provide 'guix-default-config)
@@ -38,7 +38,7 @@
;; Avoid auto-compilation as it is slow and error-prone:
;; <https://notabug.org/alezost/emacs-guix/issues/2>.
"--no-auto-compile")
- "Name of the 'guile' executable used for Guix REPL.
+ "Name of the \\='guile\\=' executable used for Guix REPL.
May be either a string (the name of the executable) or a list of
strings of the form:
@@ -50,18 +50,18 @@ Where ARGS is a list of arguments to the guile program."
(defcustom guix-dot-program
(executable-find "dot")
- "Name of the 'dot' executable."
+ "Name of the \\='dot\\=' executable."
:type 'string
:group 'guix-external)
(defcustom guix-dot-default-arguments
'("-Tpng")
- "Default arguments for 'dot' program."
+ "Default arguments for \\='dot\\=' program."
:type '(repeat string)
:group 'guix-external)
(defcustom guix-dot-file-name-function #'guix-png-file-name
- "Function used to define a file name of a temporary 'dot' file.
+ "Function used to define a file name of a temporary \\='dot\\=' file.
The function is called without arguments."
:type '(choice (function-item guix-png-file-name)
(function :tag "Other function"))
@@ -82,11 +82,11 @@ If ARGS is nil, use `guix-dot-default-arguments'."
(funcall guix-dot-file-name-function))
(defun guix-png-file-name ()
- "Return '.png' file name in the `guix-temporary-directory'."
+ "Return '.png' file name in the variable `guix-temporary-directory'."
(guix-temporary-file-name "graph-" ".png"))
(defun guix-html-file-name ()
- "Return '.html' file name in the `guix-temporary-directory'."
+ "Return '.html' file name in the variable `guix-temporary-directory'."
(guix-temporary-file-name "graph-" ".html"))
(provide 'guix-external)
@@ -53,7 +53,7 @@ Return a list of strings with result values of evaluation."
Sorry, the evaluation is aborted because it has taken too much time.
Try to increase the value of `guix-geiser-connection-timeout'
variable if you have a slow machine, or please report if you
-think this command takes unreasonably long time to run."))
+think this command takes unreasonably long time to run"))
(if (geiser-eval--retort-error res)
(error "Error in evaluating guile expression: %s"
(geiser-eval--retort-output res))
@@ -76,9 +76,10 @@ If NO-DISPLAY is non-nil, do not switch to the REPL buffer."
(defun guix-geiser-eval-in-repl-synchronously (str &optional repl
no-history no-display)
- "Evaluate STR in Geiser REPL synchronously, i.e. wait until the
-REPL operation will be finished.
-See `guix-geiser-eval-in-repl' for the meaning of arguments."
+ "Evaluate STR in Geiser REPL synchronously.
+The evaluation is blocked until the REPL operation completes.
+See `guix-geiser-eval-in-repl' for the meaning of arguments NO-HISTORY
+and NO-DISPLAY."
(let* ((repl (if repl (get-buffer repl) (guix-geiser-repl)))
(running? nil)
(filter (lambda (output)
@@ -52,7 +52,7 @@ See `guix-graph-backend->graph-type' for the meaning of GRAPH-TYPE."
(browse-url (browse-url-file-url graph-file)))))
(defun guix-make-view-graph (backend graph-maker)
- "Make graph using GRAPH-MAKER procedure and view it.
+ "Make graph with BACKEND using GRAPH-MAKER procedure and view it.
GRAPH-MAKER is called with GRAPH-TYPE and GRAPH-FILE arguments.
It should return non-nil on success.
See `guix-graph-backend->graph-type' for the meaning of GRAPH-TYPE."
@@ -105,7 +105,7 @@ PROC and ARGS should be strings."
(string-match-p geiser-guile--debugger-prompt-regexp string)))
(defun guix-guile-read ()
- "Read guile code from the current buffer and 'transform' it into elisp.
+ "Read guile code from the current buffer and \\='transform\\=' it into elisp.
The contents of the current buffer may be modified."
(goto-char (point-min))
(cond
@@ -120,13 +120,13 @@ The contents of the current buffer may be modified."
(read (current-buffer)))))
(defun guix-guile-read-from-file (file-name)
- "Read guile code from FILE-NAME and 'transform' it into elisp."
+ "Read guile code from FILE-NAME and \\='transform\\=' it into elisp."
(with-temp-buffer
(insert-file-contents file-name)
(guix-guile-read)))
(defun guix-guile-read-from-string (string)
- "Read guile code from string and 'transform' it into elisp."
+ "Read guile code from STRING and \\='transform\\=' it into elisp."
(with-temp-buffer
(insert string)
(guix-guile-read)))
@@ -69,8 +69,7 @@ guix subcommand, system action, importer, etc.")
"Regexp used to find various lists (lint checkers, graph types).")
(defvar guix-help-parse-regexp-group 1
- "Parenthesized expression of regexps used to find commands and
-options.")
+ "Parenthesized expression of regexps to find commands and options.")
;;; Non-receivable lists
@@ -85,7 +84,7 @@ options.")
(defvar guix-help-refresh-subsets
'("core" "non-core")
- "List of supported 'refresh' subsets.")
+ "List of supported \\='refresh\\=' subsets.")
(defvar guix-help-key-policies
'("interactive" "always" "never")
@@ -93,7 +92,7 @@ options.")
(defvar guix-help-verify-options
'("repair" "contents")
- "List of supported 'verify' options")
+ "List of supported \\='verify\\=' options.")
(defvar guix-help-elpa-archives
'("gnu" "melpa" "melpa-stable")
@@ -101,66 +100,66 @@ options.")
(defvar guix-help-size-sort-keys
'("closure" "self")
- "List of supported sort keys for 'guix size' command.")
+ "List of supported sort keys for \\='guix size\\=' command.")
(defvar guix-help-search-paths-types
'("exact" "prefix" "suffix")
- "List of supported search-paths types for 'guix package' command.")
+ "List of supported search-paths types for \\='guix package\\=' command.")
(defvar guix-help-repl-types
'("guile" "machine")
- "List of supported types for 'guix repl' command.")
+ "List of supported types for \\='guix repl\\=' command.")
(defvar guix-help-describe-formats
'("human" "channels" "json" "recutils")
- "List of supported formats for 'guix describe' command.")
+ "List of supported formats for \\='COMMAND describe\\=' command.")
(defvar guix-help-on-error-strategies
'("nothing-special" "backtrace" "debug")
- "List of on-error strategies for 'guix system' command.")
+ "List of on-error strategies for \\='guix system\\=' command.")
;;; Default values of various options
(defvar guix-default-hash-format
"nix-base32"
- "Default format for 'guix hash' command.")
+ "Default format for \\='guix hash\\=' command.")
(defvar guix-default-key-policy
"interactive"
- "Default key download policy used by 'guix refresh' command.")
+ "Default key download policy used by \\='guix refresh\\=' command.")
(defvar guix-default-elpa-archive
"gnu"
- "Default ELPA archive for 'guix import elpa' command.")
+ "Default ELPA archive for \\='guix import elpa\\=' command.")
(defvar guix-default-size-sort-key
"closure"
- "Default sort key for 'guix size' command.")
+ "Default sort key for \\='guix size\\=' command.")
(defvar guix-default-search-paths-type
"exact"
- "Default search-paths type for 'guix package' command.")
+ "Default search-paths type for \\='guix package\\=' command.")
(defvar guix-default-repl-type
"guile"
- "Default type for 'guix repl' command.")
+ "Default type for \\='guix repl\\=' command.")
(defvar guix-default-describe-format
"human"
- "Default format for 'guix describe' command.")
+ "Default format for \\='guix describe\\=' command.")
(defvar guix-default-graph-backend
"graphviz"
- "Default backend for 'guix graph' command.")
+ "Default backend for \\='guix graph\\=' command.")
(defvar guix-default-graph-node-type
"package"
- "Default node type for 'guix graph' command.")
+ "Default node type for \\='guix graph\\=' command.")
(defvar guix-default-on-error-strategy
"nothing-special"
- "Default on-error strategy for 'guix system' command.")
+ "Default on-error strategy for \\='guix system\\=' command.")
(provide 'guix-help-vars)
@@ -48,7 +48,7 @@ If ARG is non-nil (interactively with prefix), show Guix info manual."
:group 'guix-help)
(defcustom guix-help-doc-column 40
- "Column at which 'doc' button is inserted."
+ "Column at which \\='doc\\=' button is inserted."
:type 'integer
:group 'guix-help)
@@ -186,7 +186,7 @@ COMMAND-NAME is a symbol.
COMMAND-BUTTON? is a boolean value; it defines whether
COMMAND-NAME is buttonized or not.
-INFO-BUTTON? is a boolean value; it defines whether 'info' button
+INFO-BUTTON? is a boolean value; it defines whether \\='info\\=' button
should be displayed or not.")
(defvar guix-help-mode-map
@@ -229,7 +229,7 @@ INFO-NODE is the name passed to `info' function."
'symbol symbol))
(defun guix-insert-command-button (command)
- "Insert button to run 'M-x COMMAND'."
+ "Insert button to run \\[COMMAND]."
(let ((command-string (symbol-name command)))
(bui-insert-button
command-string 'button
@@ -255,8 +255,8 @@ INFO-NODE is the name passed to `info' function."
(guix-goto-index-topic "Command Index" topic))
(defun guix-help-insert-doc-buttons (command &optional info-button?)
- "Insert 'doc' button for COMMAND at `guix-help-doc-column'.
-If INFO-BUTTON? is non-nil, insert 'info' button as well."
+ "Insert \\='doc\\=' button for COMMAND at `guix-help-doc-column'.
+If INFO-BUTTON? is non-nil, insert \\='info\\=' button as well."
(indent-to guix-help-doc-column 2)
(guix-insert-doc-button "doc" command)
(when info-button?
@@ -309,7 +309,7 @@ See `guix-help-specifications' for the meaning of SPEC."
(funcall content-function)))
(defun guix-help-make-revert-function (content-function)
- "Return a revert function for `revert-buffer-function'."
+ "Return a revert CONTENT-FUNCTION for `revert-buffer-function'."
(lambda (_ignore-auto noconfirm)
(when (or noconfirm
(y-or-n-p (format "Revert %s buffer? " (buffer-name))))
@@ -29,7 +29,8 @@
(defun guix-license-file (&optional directory)
"Return name of the file with license definitions.
-DIRECTORY is a directory with Guix source (`guix-directory' by default)."
+DIRECTORY is a directory with Guix source (variable`guix-directory'
+by default)."
(expand-file-name "guix/licenses.scm"
(or directory (guix-directory))))
@@ -56,7 +56,7 @@
"If non-nil, do not perform the real actions, just simulate.")
(defvar guix-temp-buffer-name " *Guix temp*"
- "Name of a buffer used for displaying info before executing operation.")
+ "Name of a buffer used to display info before executing operation.")
(defvar guix-operation-option-true-string "yes"
"String displayed in the mode-line when operation option is t.")
@@ -130,7 +130,8 @@ Ask a user with PROMPT for continuing an operation."
(message "")))))
(defun guix-operation-prompt-1 (prompt keys)
- "This function is internal for `guix-operation-prompt'."
+ "This function is internal for `guix-operation-prompt'.
+See its documentation for meaning of PROMPT and KEYS."
(guix-operation-set-mode-line)
(let ((key (read-char-choice prompt (cons ?\C-g keys) t)))
(cl-case key
@@ -163,7 +164,7 @@ Ask a user with PROMPT for continuing an operation."
;;;###autoload
(defun guix-apply-manifest (profile file &optional operation-buffer)
"Apply manifest from FILE to PROFILE.
-This function has the same meaning as 'guix package --manifest' command.
+This function has the same meaning as \\='guix package --manifest\\=' command.
See Info node `(guix) Invoking guix package' for details.
Interactively, use the current profile and prompt for manifest
@@ -189,12 +190,13 @@ FILE. With a prefix argument, also prompt for PROFILE."
operation-buffer)))
(defcustom guix-search-paths-buffer-name "*Guix Search Paths*"
- "Name of a buffer for displaying 'search paths' environment variables."
+ "Name of a buffer to display \\='search paths\\=' environment variables."
:type 'string
:group 'guix)
(defun guix-show-search-paths (profiles &optional type)
- "Display 'search paths' environment variables for PROFILES."
+ "Display \\='search paths\\=' environment variables for PROFILES.
+TYPE defaults to \\='exact\\='."
(let* ((profiles (mapcar #'guix-package-profile profiles))
(type (or type "exact"))
(type-symbol (intern type))
@@ -230,7 +232,7 @@ PROFILE can be a named profile (like '~/.guix-profile',
store, like GUIX_ENVIRONMENT variable (see Info node `(guix)
Invoking guix environment' for details).
-If PROFILE is nil, use `guix-current-profile'."
+If PROFILE is nil, use variable `guix-current-profile'."
(interactive (list (guix-read-profile)))
(let ((specs (guix-eval-read
(guix-make-guile-expression
@@ -283,18 +285,18 @@ The function is called with a single argument - a command line string."
(eshell-send-input))
(defun guix-run-command-in-shell (args)
- "Execute 'guix ARGS ...' command in a shell buffer."
+ "Execute \\='guix ARGS ...\\=' command in a shell buffer."
(funcall guix-run-in-shell-function
(guix-command-string args)))
(defun guix-run-command-in-repl (args)
- "Execute 'guix ARGS ...' command in Guix REPL."
+ "Execute \\='guix ARGS ...\\=' command in Guix REPL."
(guix-eval-in-repl
(apply #'guix-make-guile-expression
'guix-command args)))
(defun guix-command-output (args)
- "Return string with 'guix ARGS ...' output."
+ "Return string with \\='guix ARGS ...\\=' output."
(cl-multiple-value-bind (output error)
(guix-eval (apply #'guix-make-guile-expression
'guix-command-output args))
@@ -303,7 +305,7 @@ The function is called with a single argument - a command line string."
(read output)))
(defun guix-help-string (&optional commands)
- "Return string with 'guix COMMANDS ... --help' output."
+ "Return string with \\='guix COMMANDS ... --help\\=' output."
(guix-eval-read
(apply #'guix-make-guile-expression
'help-string commands)))
@@ -358,7 +360,7 @@ If VERBOSE is non-nil (with prefix argument), produce verbose output."
;;;###autoload
(defun guix-report-bug (subject)
"Report GNU Guix bug.
-Prompt for bug subject and open a mail buffer."
+Prompt for bug SUBJECT and open a mail buffer."
(interactive "sBug Subject: ")
(compose-mail guix-bug-address subject))
@@ -73,7 +73,7 @@
'package-store-path package-id)))
(defvar guix-after-source-download-hook nil
- "Hook run after successful performing a 'source-download' operation.")
+ "Hook run after successful performing a \\='source-download\\=' operation.")
(defun guix-package-source-build-derivation (package-id &optional prompt)
"Build source derivation of a package PACKAGE-ID.
@@ -38,7 +38,7 @@
(defun guix-pcomplete-search-in-help (regexp &optional group
&rest args)
- "Search for REGEXP in 'guix ARGS... --help' output.
+ "Search for REGEXP in \\='guix ARGS... --help\\=' output.
Return a list of strings matching REGEXP.
GROUP specifies a parenthesized expression used in REGEXP."
(with-temp-buffer
@@ -53,9 +53,10 @@ GROUP specifies a parenthesized expression used in REGEXP."
"Define function NAME to receive guix options and commands.
The defined function takes rest COMMANDS argument. This function
-will search for REGEXP in 'guix COMMANDS... --help' output (or
-'guix --help' if COMMANDS is nil) using
-`guix-pcomplete-search-in-help' and will return its result.
+will search for REGEXP in \\='guix COMMANDS... --help\\=' output (or
+\\='guix --help\\=' if COMMANDS is nil) using
+`guix-pcomplete-search-in-help' and will return its result. The
+function is defined with DOCSTRING.
If FILTER is specified, it should be a function. The result is
passed to this FILTER as argument and the result value of this
@@ -72,15 +73,15 @@ function call is returned."
(guix-pcomplete-define-options-finder guix-pcomplete-commands
"If COMMANDS is nil, return a list of available guix commands.
If COMMANDS is non-nil (it should be a list of strings), return
-available subcommands, actions, etc. for 'guix COMMANDS'."
+available subcommands, actions, etc. for \\='guix COMMANDS\\='."
guix-help-parse-command-regexp)
(guix-pcomplete-define-options-finder guix-pcomplete-long-options
- "Return a list of available long options for 'guix COMMANDS'."
+ "Return a list of available long options for \\='guix COMMANDS\\='."
guix-help-parse-long-option-regexp)
(guix-pcomplete-define-options-finder guix-pcomplete-short-options
- "Return a string with available short options for 'guix COMMANDS'."
+ "Return a string with available short options for \\='guix COMMANDS\\='."
guix-help-parse-short-option-regexp
(lambda (list)
(guix-concat-strings list "")))
@@ -25,7 +25,7 @@
;; replaced with '/gnu/store/…-foo-0.1' in the current buffer. There is
;; also `global-guix-prettify-mode' for global prettifying.
-;; To install, add the following to your emacs init file:
+;; To install, add the following to your Emacs init file:
;;
;; (add-to-list 'load-path "/path/to/dir-with-guix-prettify")
;; (autoload 'guix-prettify-mode "guix-prettify" nil t)
@@ -166,7 +166,7 @@ file names (see `guix-prettify-regexp') are displayed as
This mode can be enabled programmatically using hooks:
- (add-hook 'shell-mode-hook 'guix-prettify-mode)
+ (add-hook \\='shell-mode-hook \\='guix-prettify-mode)
It is possible to enable the mode in any buffer, however not any
buffer's highlighting may survive after adding new elements to
@@ -57,7 +57,7 @@
(expand-file-name "guix/current"
(or (getenv "XDG_CONFIG_HOME")
(expand-file-name "~/.config")))
- "Profile populated by 'guix pull' command.")
+ "Profile populated by \\='guix pull\\=' command.")
(defvar guix-default-user-profile
(or (file-symlink-p guix-user-profile)
@@ -71,7 +71,7 @@ also contain profile generations.")
(or (file-symlink-p guix-pulled-profile)
(expand-file-name "current-guix"
(guix-user-profiles-directory)))
- "Default profile populated by 'guix pull' command.
+ "Default profile populated by \\='guix pull\\=' command.
Unlike `guix-pulled-profile', directory with this profile should
also contain profile generations.")
@@ -96,7 +96,7 @@ It is used by various commands as the default working profile.")
(rx-to-string `(or ,guix-pulled-profile
,guix-default-pulled-profile)
t)
- "Regexp matching 'guix pull'-ed profile.")
+ "Regexp matching \\='guix pull\\='-ed profile.")
(defvar guix-generation-file-name-regexp
(rx (group (one-or-more any))
@@ -105,7 +105,7 @@ It is used by various commands as the default working profile.")
The first parenthesized group should match profile file name.")
(defun guix-current-profile? (profile)
- "Return non-nil, if PROFILE is `guix-current-profile'."
+ "Return non-nil, if PROFILE is the variable `guix-current-profile'."
(string= (guix-profile profile)
(guix-profile guix-current-profile)))
@@ -118,7 +118,7 @@ The first parenthesized group should match profile file name.")
(string-match-p guix-home-profile-regexp profile))
(defun guix-pulled-profile? (profile)
- "Return non-nil, if PROFILE is populated by 'guix pull'."
+ "Return non-nil, if PROFILE is populated by \\='guix pull\\='."
(string-match-p guix-pulled-profile-regexp profile))
(defun guix-assert-non-system-profile (profile)
@@ -126,7 +126,7 @@ The first parenthesized group should match profile file name.")
(when (guix-system-profile? profile)
(user-error "\
Packages cannot be installed or removed to/from profile '%s'.
-Use 'guix system reconfigure' shell command to modify a system profile."
+Use 'guix system reconfigure' shell command to modify a system profile"
profile)))
(defun guix-generation-file (profile generation)
@@ -155,15 +155,15 @@ and `guix-default-user-profile' instead of `guix-user-profile'."
(defun guix-generation-profile (profile &optional generation)
"Return file name of PROFILE or its GENERATION.
-The returned file name is the one that have generations in the
-same parent directory.
+
+The returned file name is the one that have generations in the same
+parent directory.
If PROFILE matches `guix-system-profile-regexp' or
-`guix-home-profile-regexp', then it is considered to be a system
-or home profile. Unlike usual profiles, for a system/home
-profile, packages are placed in 'profile' sub-directory, so the
-returned file name does not contain this potential trailing
-'/profile'."
+`guix-home-profile-regexp', then it is considered to be a system or
+home profile. Unlike usual profiles, for a system/home profile,
+packages are placed in \\='profile\\=' sub-directory, so the returned
+file name does not contain this potential trailing \\='/profile\\='."
(let* ((profile (guix-profile profile))
(profile (if (and (or (guix-system-profile? profile)
(guix-home-profile? profile))
@@ -234,7 +234,7 @@ is not a guix profile)."
(defun guix-read-profile (&optional default)
"Prompt for profile and return it.
Use DEFAULT as a start directory. If it is nil, use
-`guix-current-profile'."
+the variable `guix-current-profile'."
(guix-read-file-name "Profile: "
(file-name-directory
(or default guix-current-profile))))
@@ -252,13 +252,13 @@ See `guix-read-profile' for the meaning of DEFAULT, and
(guix-generation-profile (guix-read-profile default)))
(defun guix-read-manifest-file-name (&optional prompt)
- "Prompt for a manifest file name and return it."
+ "PROMPT for a manifest file name and return it."
(guix-read-file-name (or prompt "File with manifest: ")))
;;;###autoload
(defun guix-set-current-profile (file-name)
- "Set `guix-current-profile' to FILE-NAME.
+ "Set the variable `guix-current-profile' to FILE-NAME.
Interactively, prompt for FILE-NAME. With prefix, use
`guix-user-profile'."
(interactive
@@ -129,7 +129,9 @@ initial-contents."
(defun guix-read-package-name-at-point (&optional prompt initial-contents)
"Read symbol at point and if it is a package name, return it.
If it is not a package name or if current command has a prefix
-argument, read the name from minibuffer."
+argument, read the name from minibuffer.
+See `guix-read-package-name-default' for the meaning of options PROMPT
+and INITIAL-CONTENTS."
(if current-prefix-arg
(guix-read-package-name-default prompt initial-contents)
(let* ((at-point (thing-at-point 'symbol))
@@ -142,7 +144,9 @@ argument, read the name from minibuffer."
initial-contents)))))
(defun guix-read-package-name (&optional prompt initial-contents)
- "Read a package name using `guix-read-package-name-function'."
+ "Read a package name using `guix-read-package-name-function'.
+See the value of `guix-read-package-name-function' for the meaning of
+options PROMPT and INITIAL-CONTENTS."
(funcall guix-read-package-name-function
prompt initial-contents))
@@ -59,13 +59,12 @@
(require 'guix-utils)
(defvar guix-load-path nil
- "Directory or a list of directories prepended to Guile's
-`%load-path' when Guix REPL is started.
+ "Directory or a list of directories prepended to Guile's `%load-path'.
-These directories take precedence over any other
-directory (including Guile modules of Emacs-Guix and Guix
-itself). So this variable may be useful if you prefer to use
-guix from a git checkout:
+These directories are prepended when Guix REPL is started. They take
+precedence over any other directory (including Guile modules of
+Emacs-Guix and Guix itself). So this variable may be useful if you
+prefer to use guix from a git checkout:
(setq guix-load-path \"/path/to/guix-from-git\")
@@ -73,10 +72,10 @@ These directories are also prepended to `%load-compiled-path'
unless `guix-load-compiled-path' is specified.")
(defvar guix-load-compiled-path nil
- "List of directories prepended to Guile's `%load-compiled-path'
-when Guix REPL is started.
+ "List of directories prepended to Guile's `%load-compiled-path'.
-See `guix-load-path' for details.")
+These directories are prepended when Guix REPL is started. See
+`guix-load-path' for details.")
;;; REPL
@@ -108,9 +107,9 @@ If you have a slow system, try to increase this time."
'guix-repl-use-server "0.2")
(defcustom guix-repl-use-server t
- "If non-nil, start guile with '--listen' argument.
+ "If non-nil, start guile with \\='--listen\\=' argument.
This allows to receive information about packages using an
-additional (so called 'internal') REPL while some packages are
+additional (so called \\='internal\\=') REPL while some packages are
being installed/removed in the main Guix REPL."
:type 'boolean
:group 'guix-repl)
@@ -181,8 +180,8 @@ executed after the current operation succeeds.
See `guix-eval-in-repl' for details.")
(defvar guix-repl-max-returned-list-size 10
- "Maximal length of a list that is passed from the Guile side to
-the Emacs side directly through Geiser.
+ "Maximal length of a list passed from Guile to Emacs side.
+This list is passed directly through Geiser.
This is a performance variable: passing big chunks of data
through Geiser may be slow, so to improve the speed, the Guile
@@ -191,7 +190,7 @@ file, and then this file is read directly by Emacs.
So if a list is lesser than the value of this variable, it is
passed through Geiser. If it is bigger, it is written to a
-file (in `guix-temporary-directory').
+file (variable `guix-temporary-directory').
Set this variable to nil, if you want to pass a list of any size
through Geiser (not recommended).
@@ -336,7 +335,7 @@ this address (it should be defined by
geiser-repl-query-on-kill-p)))))
(defun guix-repl-output-filter (str)
- "Filter function suitable for `comint-output-filter-functions'.
+ "Filter STR for `comint-output-filter-functions'.
This is a replacement for `geiser-repl--output-filter'."
(cond
((string-match-p geiser-guile--prompt-regexp str)
@@ -431,7 +430,7 @@ automatically when needed. However, you can still set it if you
really want; your value will not be overwritten.")
(defun guix-directory ()
- "Set if needed and return `guix-directory'."
+ "Set if needed and return the variable `guix-directory'."
(or guix-directory
(let* ((guix.scm (guix-eval-read "(%search-load-path \"guix\")"))
(dir (and guix.scm
@@ -439,7 +438,7 @@ really want; your value will not be overwritten.")
(setq guix-directory dir))))
(defun guix-read-directory ()
- "Return `guix-directory' or prompt for it.
+ "Return the variable `guix-directory' or prompt for it.
This function is intended for using in `interactive' forms."
(if current-prefix-arg
(read-directory-name "Directory with Guix modules: "
@@ -450,7 +449,7 @@ This function is intended for using in `interactive' forms."
;; compatibility (in the past "guix pull" populated
;; "~/.config/guix/latest").
(defun guix-latest-directory ()
- "Return 'guix pull'-ed directory or nil if it does not exist."
+ "Return \\='guix pull\\='-ed directory or nil if it does not exist."
(let* ((config-dir (or (getenv "XDG_CONFIG_HOME")
(expand-file-name "~/.config")))
(latest-dir (expand-file-name "guix/latest" config-dir)))
@@ -511,7 +510,7 @@ If MODES is nil, use modes for Guix package management."
(defun guix-operation-buffers (&optional modes)
"Return a list of all buffers with major modes derived from MODES.
-If MODES is nil, return list of all Guix 'list' and 'info' buffers."
+If MODES is nil, return list of all Guix \\='list\\=' and \\='info\\=' buffers."
(--filter (guix-operation-buffer? it modes)
(buffer-list)))
@@ -1,4 +1,4 @@
-;;; guix-ui-generation.el --- Interface for displaying generations -*- lexical-binding: t -*-
+;;; guix-ui-generation.el --- Interface to display generations -*- lexical-binding: t -*-
;; Copyright © 2014–2018 Alex Kost <alezost@gmail.com>
@@ -19,7 +19,7 @@
;;; Commentary:
-;; This file provides an interface for displaying profile generations in
+;; This file provides an interface to display profile generations in
;; 'list' and 'info' buffers, and commands for working with them.
;;; Code:
@@ -42,9 +42,9 @@
(defun guix-generation-get-entries (proc profile search-type
search-values params)
- "Return 'generation' or 'system-generation' entries.
-PROC is the name of a Scheme procedure (either 'generation-sexps'
-or 'system-generation-sexps')."
+ "Return \\='generation\\=' or \\='system-generation\\=' entries.
+PROC is the name of a Scheme procedure (either \\='generation-sexps\\='
+or \\='system-generation-sexps\\=')."
(apply #'guix-modify-objects
(guix-eval-read (guix-make-guile-expression
proc profile search-type search-values params))
@@ -63,10 +63,8 @@ or 'system-generation-sexps')."
(defun guix-generation-get-display (profile search-type &rest search-values)
"Search for generations and show results.
-If PROFILE is nil, use `guix-current-profile'.
-
-See `guix-ui-get-entries' for the meaning of SEARCH-TYPE and
-SEARCH-VALUES."
+If PROFILE is nil, use the variable `guix-current-profile'.
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(apply #'bui-list-get-display-entries
'guix-generation
(or profile guix-current-profile)
@@ -91,7 +89,9 @@ Each element from GENERATIONS is a generation number."
(defun guix-switch-to-generation (profile generation
&optional operation-buffer)
- "Switch PROFILE to GENERATION."
+ "Switch PROFILE to GENERATION.
+
+Argument OPERATION-BUFFER is passed to `guix-eval-in-repl'."
(when (or (not guix-operation-confirm)
(y-or-n-p (format "Switch profile '%s' to generation %d? "
profile generation)))
@@ -101,8 +101,9 @@ Each element from GENERATIONS is a generation number."
operation-buffer)))
(defun guix-generation-current-package-profile (&optional generation)
- "Return a directory where packages are installed for the
-current profile's GENERATION."
+ "Return a directory where packages are installed.
+
+If GENERATION is provided, do that for the current profile's GENERATION."
(guix-package-profile (guix-ui-current-profile) generation))
@@ -146,7 +147,9 @@ current profile's GENERATION."
(defun guix-generation-info-get-entries (profile search-type
&rest search-values)
- "Return 'generation' entries for displaying them in 'info' buffer."
+ "Return PROFILE \\='generation\\=' entries to display them in `info' buffer.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(guix-generation-get-entries
'generation-sexps
profile search-type search-values
@@ -182,7 +185,7 @@ current profile's GENERATION."
(bui-newline)))
(defun guix-generation-info-insert-previous (prev-number entry)
- "Insert PREV-NUMBER and button to compare generations."
+ "Insert PREV-NUMBER and button in ENTRY to compare generations."
(bui-format-insert prev-number)
(bui-insert-indent)
(when (> prev-number 0)
@@ -201,7 +204,7 @@ current profile's GENERATION."
'number number))))
(defun guix-generation-info-insert-packages (number entry)
- "Insert the NUMBER of packages and button to display packages."
+ "Insert the NUMBER of packages and button in ENTRY to display packages."
(bui-format-insert number)
(bui-insert-indent)
(let ((number (bui-entry-non-void-value entry 'number)))
@@ -216,7 +219,9 @@ current profile's GENERATION."
'number number)))
(defun guix-generation-info-insert-current (val entry)
- "Insert boolean value VAL showing whether this generation is current."
+ "Insert in ENTRY the boolean value VAL.
+
+This value shows whether this generation is current."
(if val
(bui-info-insert-value-format "Yes" 'guix-generation-info-current)
(bui-info-insert-value-format "No" 'guix-generation-info-not-current)
@@ -302,7 +307,9 @@ If nothing is marked, return a list with generation at point."
(defun guix-generation-list-get-entries (profile search-type
&rest search-values)
- "Return 'generation' entries for displaying them in 'list' buffer."
+ "Return \\='generation\\=' entries to display them in \\='list\\=' buffer.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information for PROFILE."
(guix-generation-get-entries
'generation-sexps
profile search-type search-values
@@ -333,8 +340,10 @@ VAL is a boolean value."
'installed))
(defun guix-generation-list-show-search-paths (&optional type)
- "Display 'search paths' environment variables for the marked generations.
-If nothing is marked, use generation on the current line."
+ "Display \\='search paths\\=' environment variables for the marked generations.
+
+If nothing is marked, use generation on the current line.
+Optionally get the search-path TYPE interactively."
(interactive (list (guix-read-search-paths-type)))
(guix-show-search-paths
(guix-generation-list-marked-file-names)
@@ -487,20 +496,22 @@ and its store file name."
(string< (car a) (car b)))))
(defun guix-generation-packages-buffer-name-default (profile generation)
- "Return name of a buffer for displaying GENERATION's package outputs.
+ "Return name of a buffer to display GENERATION's package outputs.
Use base name of PROFILE file name."
(let ((profile-name (file-name-base (guix-file-name profile))))
(format "*Guix %s: generation %s*"
profile-name generation)))
(defun guix-generation-packages-buffer-name-long (profile generation)
- "Return name of a buffer for displaying GENERATION's package outputs.
+ "Return name of a buffer to display GENERATION's package outputs.
Use the full PROFILE file name."
(format "*Guix generation %s (%s)*"
generation profile))
(defun guix-generation-packages-buffer-name (profile generation)
- "Return name of a buffer for displaying GENERATION's package outputs."
+ "Return name of a buffer to display GENERATION's package outputs.
+
+This is done for PROFILE."
(funcall guix-generation-packages-buffer-name-function
profile generation))
@@ -554,7 +565,7 @@ GENERATION is a generation number of the current profile."
;;;###autoload
(defun guix-generations (&optional profile)
"Display information about all generations.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use the variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive (list (guix-ui-read-generation-profile)))
(let ((profile (guix-profile profile)))
@@ -565,7 +576,7 @@ Interactively with prefix, prompt for PROFILE."
;;;###autoload
(defun guix-last-generations (number &optional profile)
"Display information about last NUMBER generations.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use the variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive
(list (read-number "The number of last generations: ")
@@ -579,7 +590,7 @@ Interactively with prefix, prompt for PROFILE."
(defun guix-generations-by-time (from to &optional profile)
"Display information about generations created between FROM and TO.
FROM and TO should be time values.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use the variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive
(list (guix-read-date "Find generations (from): ")
@@ -1,4 +1,4 @@
-;;; guix-ui-license.el --- Interface for displaying licenses -*- lexical-binding: t -*-
+;;; guix-ui-license.el --- Interface to display licenses -*- lexical-binding: t -*-
;; Copyright © 2016–2017 Alex Kost <alezost@gmail.com>
@@ -19,7 +19,7 @@
;;; Commentary:
-;; This file provides 'list'/'info' interface for displaying licenses of
+;; This file provides 'list'/'info' interface to display licenses of
;; Guix packages.
;;; Code:
@@ -38,14 +38,18 @@
:titles '((url . "URL")))
(defun guix-license-get-entries (search-type &rest args)
- "Receive 'license' entries.
-SEARCH-TYPE may be one of the following symbols: `all', `id', `name'."
+ "Receive \\='license\\=' entries.
+
+SEARCH-TYPE may be one of the following symbols: \\='all\\=',\\='id\\=',
+\\='name\\='. ARGS are passed to `guix-make-guile-expression'."
(guix-eval-read
(apply #'guix-make-guile-expression
'license-sexps search-type args)))
(defun guix-license-get-display (search-type &rest args)
- "Search for licenses and show results."
+ "Search for licenses and show results.
+
+SEARCH-TYPE and ARGS are passed to `bui-list-get-display-entries'."
(apply #'bui-list-get-display-entries
'guix-license search-type args))
@@ -87,7 +91,7 @@ SEARCH-TYPE may be one of the following symbols: `all', `id', `name'."
(bui-newline))
(defun guix-license-insert-comment (entry)
- "Insert 'comment' of a license ENTRY."
+ "Insert \\='comment\\=' of a license ENTRY."
(let ((comment (bui-entry-value entry 'comment)))
(if (and comment
(string-match-p "^http" comment))
@@ -97,7 +101,7 @@ SEARCH-TYPE may be one of the following symbols: `all', `id', `name'."
(bui-newline))
(defun guix-license-insert-file (entry)
- "Insert button to open license definition."
+ "Insert button to open license definition of ENTRY."
(let ((license (bui-entry-value entry 'name)))
(bui-insert-button
(guix-license-file) 'bui-file
@@ -1,4 +1,4 @@
-;;; guix-ui-lint-checker.el --- Interface for displaying package lint checkers -*- lexical-binding: t -*-
+;;; guix-ui-lint-checker.el --- Interface to display package lint checkers -*- lexical-binding: t -*-
;; Copyright © 2019 Alex Kost <alezost@gmail.com>
@@ -39,20 +39,23 @@
:message-function 'guix-lint-checker-message)
(defun guix-lint-checker-get-entries (search-type &rest args)
- "Receive 'lint-checker' entries.
-SEARCH-TYPE may be one of the following symbols: `all', `local',
-`id', `name'."
+ "Receive \\='lint-checker\\=' entries.
+
+SEARCH-TYPE may be one of the following symbols: \\='all\\=', \\='local\\=',
+\\='id\\=', \\='name\\='. ARGS are passed to `guix-make-guile-expression'."
(guix-eval-read
(apply #'guix-make-guile-expression
'lint-checker-sexps search-type args)))
(defun guix-lint-checker-get-display (search-type &rest args)
- "Search for lint checkers and show results."
+ "Search for lint checkers and show results.
+
+SEARCH-TYPE and ARGS are passed to `bui-list-get-display-entries'."
(apply #'bui-list-get-display-entries
'guix-lint-checker search-type args))
(defun guix-lint-checker-message (entries search-type &rest args)
- "Display a message after showing lint-checker ENTRIES."
+ "Display a message after showing lint-checker ENTRIES for SEARCH-TYPE."
(when (null entries)
(cond
((memq search-type '(all local))
@@ -154,11 +154,11 @@
guix-message-generations-by-time))))
(defun guix-message-string-name (name)
- "Return a quoted name string."
+ "Return a quoted NAME string."
(concat "'" name "'"))
(defun guix-message-string-entry-type (entry-type &optional plural)
- "Return a string denoting an ENTRY-TYPE."
+ "Return a string denoting an ENTRY-TYPE, optionally using PLURAL."
(cl-ecase entry-type
(package
(if plural "packages" "package"))
@@ -181,8 +181,10 @@
(guix-message-string-entry-type
entry-type 'plural)))))
-(defun guix-message-packages-by-id (entries entry-type ids)
- "Display a message for packages or outputs searched by IDS."
+(defun guix-message-packages-by-id (entries _entry-type ids)
+ "Display a message for packages or outputs searched by IDS.
+
+ENTRIES are packages or outputs."
(let ((count (length entries)))
(if (= 0 count)
(message (substitute-command-keys "\
@@ -199,7 +201,9 @@ Try \"\\[guix-packages-by-name-regexp]\" to find this package.")
(message ""))))
(defun guix-message-packages-by-name (entries entry-type names)
- "Display a message for packages or outputs searched by NAMES."
+ "Display a message for ENTRIES searched by NAMES.
+
+ENTRIES are packages or outputs of ENTRY-TYPE."
(let* ((count (length entries))
(str-beg (guix-message-string-entries count entry-type))
(str-end (if (cdr names)
@@ -249,7 +253,7 @@ DEPEND-TYPE should a symbol `direct' or `all'."
str-beg profile time-beg time-end)))
(defun guix-message-outputs-by-diff (_ entries profiles)
- "Display a message for outputs searched by PROFILES difference."
+ "Display a message for ENTRIES outputs searched by PROFILES difference."
(let* ((count (length entries))
(str-beg (guix-message-string-entries count 'output))
(profile1 (car profiles))
@@ -1,4 +1,4 @@
-;;; guix-ui-package-location.el --- Interface for displaying package locations -*- lexical-binding: t -*-
+;;; guix-ui-package-location.el --- Interface to display package locations -*- lexical-binding: t -*-
;; Copyright © 2016–2018 Alex Kost <alezost@gmail.com>
@@ -19,7 +19,7 @@
;;; Commentary:
-;; This file provides a 'list' interface for displaying locations of Guix
+;; This file provides a 'list' interface to display locations of Guix
;; packages.
;;; Code:
@@ -33,7 +33,7 @@
(guix-define-groups package-location)
(defun guix-package-location-get-entries ()
- "Receive 'package location' entries."
+ "Receive \\='package location\\=' entries."
(guix-eval-read "(package-location-sexps)"))
@@ -1,4 +1,4 @@
-;;; guix-ui-package.el --- Interface for displaying packages -*- lexical-binding: t -*-
+;;; guix-ui-package.el --- Interface to display packages -*- lexical-binding: t -*-
;; Copyright © 2014–2019, 2021 Alex Kost <alezost@gmail.com>
@@ -19,7 +19,7 @@
;;; Commentary:
-;; This file provides an interface for displaying packages and outputs
+;; This file provides an interface to display packages and outputs
;; in 'list' and 'info' buffers, and commands for working with them.
;;; Code:
@@ -44,23 +44,23 @@
(guix-ui-define-entry-type output)
(defcustom guix-package-list-type 'output
- "Define how to display packages in 'list' buffer.
-Should be a symbol `package' or `output' (if `output', display each
-output on a separate line; if `package', display each package on
+ "Define how to display packages in \\='list\\=' buffer.
+Should be a symbol \\='package\\=' or \\='output\\=' (if \\='output\\=', display
+ each output on a separate line; if \\='package\\=', display each package on
a separate line)."
:type '(choice (const :tag "List of packages" package)
(const :tag "List of outputs" output))
:group 'guix-package)
(defcustom guix-package-use-name-at-point t
- "If non-nil, \\[guix-packages-by-name] uses symbol at point as default
+ "If non-nil, \\[guix-packages-by-name] uses symbol at point as default.
if it is a package name.
If nil, then no default name is used."
:type 'boolean
:group 'guix-package)
(defun guix-package-list-type ()
- "Return BUI list entry-type by `guix-package-list-type' variable."
+ "Return BUI list entry-type by variable `guix-package-list-type'."
(guix-make-symbol guix-package-list-type))
;; To avoid compilation warning: this variable is actually defined later
@@ -70,7 +70,7 @@ If nil, then no default name is used."
(defun guix-package-get-display (profile search-type &rest search-values)
"Search for packages/outputs and show results.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use the variable `guix-current-profile'.
See `guix-ui-get-entries' for the meaning of SEARCH-TYPE and
SEARCH-VALUES.
@@ -136,7 +136,7 @@ OUTPUTS, prompt for it."
(car outputs)))
(defun guix-read-package-entry-and-output (&optional entries)
- "Return a list with package entry and output.
+ "Return a list with package ENTRIES and outputs.
See `guix-read-package-entry-by-name' and
`guix-read-package-output' for details."
(let* ((entry (guix-read-package-entry-by-name entries))
@@ -183,9 +183,9 @@ PACKAGE-SPEC should have the following form: (ID [OUTPUT] ...)."
(cl-defun guix-continue-package-operation-p (profile
&key install upgrade remove)
- "Return non-nil if a package operation should be continued.
+ "Return non-nil if a package operation should be continued in PROFILE.
Ask a user if needed (see `guix-operation-confirm').
-INSTALL, UPGRADE, REMOVE are 'package action specifications'.
+INSTALL, UPGRADE, REMOVE are \\='package action specifications\\='.
See `guix-process-package-actions' for details."
(or (null guix-operation-confirm)
(let* ((entries (guix-ui-get-entries
@@ -398,10 +398,10 @@ a newer version (probably it's time to update)."
(((class color) (min-colors 8))
:foreground "blue"))
"Face used for packages from the future.
-'From the future' means there is a Guix package with this name
+\\='From the future\\=' means there is a Guix package with this name
but with an older version, i.e. the installed package is newer
than available from Guix! This is rather unusual, it may happen,
-for example, if you installed a package after 'guix pull' (see
+for example, if you installed a package after \\='guix pull\\=' (see
Info node `(guix) Invoking guix pull') and then you removed the
pulled directory, so Guix searches for packages in its original
directory with the old package recipes."
@@ -509,7 +509,9 @@ formatted with this string, an action button is inserted.")
(defun guix-package-info-get-entries (profile search-type
&rest search-values)
- "Return 'package' entries for displaying them in 'info' buffer."
+ "Return PROFILE \\='package\\=' entries to display them in `info' buffer.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(guix-eval-read
(guix-make-guile-expression
'package/output-sexps
@@ -544,7 +546,7 @@ formatted with this string, an action button is inserted.")
'location location-file)))))
(defun guix-package-info-insert-systems (systems entry)
- "Insert supported package SYSTEMS at point."
+ "Insert supported package SYSTEMS for ENTRY at point."
(if (require 'build-farm-build nil t)
(bui-info-insert-value-format
systems 'build-farm-system
@@ -578,7 +580,7 @@ Face name is `guix-package-info-TYPE-inputs'."
(guix-package-info-define-insert-inputs propagated)
(defun guix-package-info-insert-name-buttons (values &optional button)
- "Insert package name buttons at point.
+ "Insert package name BUTTON at point.
Each element from VALUES should either be a specification string
or (id spec) list."
(bui-insert-non-nil values
@@ -603,7 +605,8 @@ or (id spec) list."
(concat "\n" bui-info-multiline-prefix)))))
(defun guix-package-info-insert-name-button (value &optional button)
- "Insert package name button at point."
+ "Insert package name BUTTON at point.
+VALUE should either be a specification string or (id spec) list."
(guix-package-info-insert-name-buttons (list value) button))
(defun guix-package-info-insert-outputs (outputs entry)
@@ -634,7 +637,7 @@ or (id spec) list."
(pull (guix-package-info-insert-pull-text name entry))))))
(defun guix-package-info-insert-unknown-text (name)
- "Insert a message about unknown package at point."
+ "Insert a message about unknown package NAME at point."
(insert "This package is ")
(bui-format-insert "unknown" 'guix-package-info-unknown)
(insert ", i.e. there are no packages with\n"
@@ -658,7 +661,7 @@ is newer than the available package recipe for ")
(insert "."))
(defun guix-package-info-insert-pull-text (name entry)
- "Insert a message that NAME package was 'guix pull'-ed."
+ "Insert a message that NAME package ENTRY was \\='guix pull\\='-ed."
(insert "This ")
(bui-insert-button name 'guix-package-name)
(insert " package was installed by 'guix pull' command")
@@ -799,7 +802,7 @@ PACKAGE-ID is an ID of the package which store path to show."
(bui-newline))))
(defun guix-package-info-insert-build-button (id full-name)
- "Insert button to build a package defined by ID."
+ "Insert button to build package FULL-NAME defined by ID."
(bui-insert-action-button
"Build"
(lambda (btn)
@@ -911,7 +914,7 @@ SOURCE is a list of URLs."
(bui-info-insert-value-indent source 'guix-package-source))))
(defun guix-package-info-redisplay-after-download ()
- "Redisplay an 'info' buffer after downloading the package source.
+ "Redisplay an `info' buffer after downloading the package source.
This function is used to hide a \"Download\" button if needed."
(when (buffer-live-p guix-package-info-download-buffer)
(with-current-buffer guix-package-info-download-buffer
@@ -1097,7 +1100,7 @@ See `guix-package-info-hidden' face for details."
:group 'guix-package-list-faces)
(defcustom guix-package-list-generation-marking-enabled nil
- "If non-nil, allow putting marks in a list with 'generation packages'.
+ "If non-nil, allow putting marks in a list with \\='generation packages\\='.
By default this is disabled, because it may be confusing. For
example, a package is installed in some generation, so a user can
@@ -1131,7 +1134,9 @@ likely)."
(defun guix-package-list-get-entries (profile search-type
&rest search-values)
- "Return 'package' entries for displaying them in 'list' buffer."
+ "Return PROFILE \\='package\\=' entries to display them in \\='list\\=' buffer.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(guix-eval-read
(guix-make-guile-expression
'package/output-sexps
@@ -1395,7 +1400,9 @@ Interactively, with prefix argument, prompt for NUMBER and ARGS."
(defun guix-output-list-get-entries (profile search-type
&rest search-values)
- "Return 'output' entries for displaying them in 'list' buffer."
+ "Return PROFILE \\='output\\=' entries to display them in \\='list\\=' buffer.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(guix-eval-read
(guix-make-guile-expression
'package/output-sexps
@@ -1516,7 +1523,7 @@ See `guix-package-lint' for details."
NAME is a string with name specification. It may optionally contain
a version number. Examples: \"guile\", \"guile@2.0.11\".
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive
(let (default-pkg)
@@ -1536,7 +1543,7 @@ Interactively with prefix, prompt for PROFILE."
PARAMS are package parameters that should be searched.
If PARAMS are not specified, use `guix-package-search-params'.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive
(list (read-regexp "Regexp: " nil 'guix-package-search-history)
@@ -1551,7 +1558,7 @@ Interactively with prefix, prompt for PROFILE."
;;;###autoload
(defun guix-packages-by-name-regexp (regexp &optional profile)
"Search for Guix packages matching REGEXP in a package name.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive
(list (read-string "Package name by regexp: "
@@ -1567,7 +1574,7 @@ Interactively with prefix, prompt for PROFILE."
(defun guix-packages-by-license (license &optional profile)
"Display Guix packages with LICENSE.
LICENSE is a license name string.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive
(list (guix-read-license-name)
@@ -1577,7 +1584,7 @@ Interactively with prefix, prompt for PROFILE."
;;;###autoload
(defun guix-packages-by-location (location &optional profile)
"Display Guix packages placed in LOCATION file.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive
(list (guix-read-package-location-file)
@@ -1587,7 +1594,7 @@ Interactively with prefix, prompt for PROFILE."
;;;###autoload
(defun guix-package-from-file (file &optional profile)
"Display Guix package that the code from FILE evaluates to.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use variable `guix-current-profile'.
Interactively prompt for FILE (see also `guix-support-dired').
With prefix argument, prompt for PROFILE as well."
(interactive
@@ -1602,7 +1609,7 @@ With prefix argument, prompt for PROFILE as well."
(defun guix-packages-from-system-config-file (file &optional profile)
"Display Guix packages from the operating system configuration FILE.
-Make sure FILE has a proper 'operating-system' declaration. You
+Make sure FILE has a proper \\='operating-system\\=' declaration. You
may check it, for example, by running the following shell command:
guix system build --dry-run FILE
@@ -1616,9 +1623,9 @@ Interactively, prompt for FILE (see also `guix-support-dired').
With prefix argument, prompt for PROFILE as well.
Note: This command displays only those packages that are placed
-in 'packages' field of the 'operating-system' declaration. An
-installed system also contains packages installed by
-services (like 'guix' or 'shepherd'). To see all the packages
+in \\='packages\\=' field of the \\='operating-system\\=' declaration.
+An installed system also contains packages installed by
+services (like \\='guix\\=' or \\='shepherd\\='). To see all the packages
installed in a system profile, use
'\\[guix-installed-system-packages]' command."
(interactive
@@ -1631,7 +1638,7 @@ installed in a system profile, use
;;;###autoload
(defun guix-installed-packages (&optional profile)
"Display information about installed Guix packages.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive (list (guix-ui-read-package-profile)))
(guix-package-get-display profile 'installed))
@@ -1651,7 +1658,7 @@ Interactively with prefix, prompt for PROFILE."
;;;###autoload
(defun guix-obsolete-packages (&optional profile)
"Display information about obsolete (or unknown) Guix packages.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive (list (guix-ui-read-package-profile)))
(guix-package-get-display profile 'unknown))
@@ -1659,7 +1666,7 @@ Interactively with prefix, prompt for PROFILE."
;;;###autoload
(defun guix-superseded-packages (&optional profile)
"Display information about superseded Guix packages.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive (list (guix-ui-read-package-profile)))
(guix-package-get-display profile 'superseded))
@@ -1674,13 +1681,14 @@ Interactively with prefix, prompt for PROFILE."
;;;###autoload
(defun guix-dependent-packages (packages &optional type profile)
"Display Guix packages that depend on PACKAGES.
-This is similar to 'guix refresh --list-dependent PACKAGES ...'.
+
+This is similar to \\='guix refresh --list-dependent PACKAGES ...\\='.
See Info node `(guix) Invoking guix refresh' for details.
-TYPE should be a symbol `all' or `direct'. Interactively, prompt
+TYPE should be a symbol \\='all\\=' or \\='direct\\='. Interactively, prompt
for it.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive
(list (guix-read-package-names)
@@ -1691,14 +1699,14 @@ Interactively with prefix, prompt for PROFILE."
;;;###autoload
(defun guix-hidden-packages (&optional profile)
"Display hidden Guix packages.
-If PROFILE is nil, use `guix-current-profile'."
+If PROFILE is nil, use variable `guix-current-profile'."
(interactive (list (guix-ui-read-package-profile)))
(guix-package-get-display profile 'hidden))
;;;###autoload
(defun guix-all-packages (&optional profile)
"Display all available Guix packages.
-If PROFILE is nil, use `guix-current-profile'.
+If PROFILE is nil, use variable `guix-current-profile'.
Interactively with prefix, prompt for PROFILE."
(interactive (list (guix-ui-read-package-profile)))
(guix-package-get-display profile 'all))
@@ -1,4 +1,4 @@
-;;; guix-ui-profile.el --- Interface for displaying profiles -*- lexical-binding: t -*-
+;;; guix-ui-profile.el --- Interface to display profiles -*- lexical-binding: t -*-
;; Copyright © 2016–2019 Alex Kost <alezost@gmail.com>
@@ -19,7 +19,7 @@
;;; Commentary:
-;; This file provides a 'list' interface for displaying Guix profiles
+;; This file provides a 'list' interface to display Guix profiles
;; with `guix-profiles' command.
;;
;; `guix-profiles' variable controls what profiles are displayed.
@@ -67,7 +67,7 @@ properly.")
(guix-eval-read "(user-profiles)")))))))
(defun guix-profile->entry (profile)
- "Return 'guix-profile' entry by PROFILE file-name."
+ "Return \\='guix-profile\\=' entry by PROFILE file-name."
(let* ((profile (guix-profile profile))
(number-of-packages (guix-profile-number-of-packages
profile)))
@@ -81,7 +81,10 @@ properly.")
(error "No packages in '%s'. Is it a real profile?" profile))))
(defun guix-profile-get-entries (&optional search-type &rest args)
- "Return 'guix-profile' entries."
+ "Return \\='guix-profile\\=' entries.
+
+SEARCH-TYPE define how to get the information. If SEARCH-TYPE is not
+\\='all\\=', use ARGS defines the candidate profiles."
(let ((profiles (cond
((or (null search-type)
(eq search-type 'all))
@@ -174,8 +177,10 @@ If nothing is marked, return a list with profile at point."
(guix-generations (guix-profile-list-current-profile)))
(defun guix-profile-list-show-search-paths (&optional type)
- "Display 'search paths' environment variables for the marked profiles.
-If nothing is marked, use profile on the current line."
+ "Display \\='search paths\\=' environment variables for the marked profiles.
+
+If nothing is marked, use profile on the current line. TYPE defines how to
+get the information."
(interactive (list (guix-read-search-paths-type)))
(guix-show-search-paths (guix-profile-list-marked-profiles) type))
@@ -191,7 +196,7 @@ If nothing is marked, use profile on the current line."
(if value "(current)" ""))
(defun guix-profile-list-set-current ()
- "Set `guix-current-profile' to the profile on the current line."
+ "Set the variable `guix-current-profile' to the profile on the current line."
(interactive)
(guix-set-current-profile (guix-profile-list-current-profile))
;; Now updating "Current" column is needed. It can be done simply by
@@ -288,7 +293,7 @@ If nothing is marked, use profile on the current line."
(bui-newline)))
(defun guix-profile-info-insert-current (value entry)
- "Insert boolean VALUE showing whether this profile is current."
+ "Insert boolean VALUE showing whether this profile ENTRY is current."
(if value
(bui-info-insert-value-format "Yes" 'guix-profile-info-current)
(bui-info-insert-value-format "No" 'guix-profile-info-not-current)
@@ -337,7 +342,9 @@ If nothing is marked, use profile on the current line."
(guix-generations profile))
(defun guix-profile-info-show-search-paths (profile &optional type)
- "Display 'search paths' environment variables for PROFILE."
+ "Display \\='search paths\\=' environment variables for PROFILE.
+
+TYPE defines how to get the information."
(interactive
(list (guix-read-profile-from-entries)
(guix-read-search-paths-type)))
@@ -351,7 +358,7 @@ If nothing is marked, use profile on the current line."
(guix-apply-manifest profile file (current-buffer)))
(defun guix-profile-info-set-current (profile)
- "Set `guix-current-profile' to PROFILE."
+ "Set variable `guix-current-profile' to PROFILE."
(interactive (list (guix-read-profile-from-entries)))
(guix-set-current-profile profile)
(bui-revert nil t))
@@ -361,7 +368,7 @@ If nothing is marked, use profile on the current line."
(defun guix-profiles-show ()
"Display Guix profiles.
-Unlike `guix-profiles', this command always recreates
+Unlike the function `guix-profiles', this command always recreates
`guix-profile-list-buffer-name' buffer."
(interactive)
(bui-list-get-display-entries 'guix-profile))
@@ -372,28 +379,28 @@ Unlike `guix-profiles', this command always recreates
Switch to the `guix-profile-list-buffer-name' buffer if it
already exists.
-Modify `guix-profiles' variable to add more profiles."
+Modify the variable `guix-profiles' to add more profiles."
(interactive)
(guix-switch-to-buffer-or-funcall
guix-profile-list-buffer-name #'guix-profiles-show 'message))
;;;###autoload
(defun guix-system-profile ()
- "Display interface for `guix-system-profile'."
+ "Display interface for the variable `guix-system-profile'."
(interactive)
(bui-get-display-entries 'guix-profile 'info
(list 'profile guix-system-profile)))
;;;###autoload
(defun guix-home-profile ()
- "Display interface for `guix-home-profile'."
+ "Display interface for the variable `guix-home-profile'."
(interactive)
(bui-get-display-entries 'guix-profile 'info
(list 'profile guix-home-profile)))
;;;###autoload
(defun guix-current-profile ()
- "Display interface for `guix-current-profile'."
+ "Display interface for the variable `guix-current-profile'."
(interactive)
(bui-get-display-entries 'guix-profile 'info
(list 'profile guix-current-profile)))
@@ -1,4 +1,4 @@
-;;; guix-ui-service-location.el --- Interface for displaying service locations -*- lexical-binding: t -*-
+;;; guix-ui-service-location.el --- Interface to display service locations -*- lexical-binding: t -*-
;; Copyright © 2018 Alex Kost <alezost@gmail.com>
@@ -19,7 +19,7 @@
;;; Commentary:
-;; This file provides a 'list' interface for displaying locations of
+;; This file provides a 'list' interface to display locations of
;; Guix System services.
;;; Code:
@@ -33,7 +33,7 @@
(guix-define-groups service-location)
(defun guix-service-location-get-entries ()
- "Receive 'service location' entries."
+ "Receive \\='service location\\=' entries."
(guix-eval-read "(service-location-sexps)"))
@@ -1,4 +1,4 @@
-;;; guix-ui-service.el --- Interface for displaying services -*- lexical-binding: t -*-
+;;; guix-ui-service.el --- Interface to display services -*- lexical-binding: t -*-
;; Copyright © 2017–2018 Alex Kost <alezost@gmail.com>
@@ -38,20 +38,26 @@
:message-function 'guix-service-message)
(defun guix-service-get-entries (search-type search-values params)
- "Receive 'service' entries.
-SEARCH-TYPE may be one of the following symbols: `id', `all',
-`name', `regexp', `location', `from-os-file', `from-expression'."
+ "Receive \\='service\\=' entries.
+SEARCH-TYPE may be one of the following symbols: \\='id\\=', \\='all\\=',
+\\='name\\=', \\='regexp\\=', \\='location\\=', \\='from-os-file\\=',
+\\='from-expression\\='. SEARCH-TYPE and SEARCH-VALUES define how to
+get the information. PARAMS is passed to `guix-make-guile-expression'."
(guix-eval-read
(guix-make-guile-expression
'service-sexps search-type search-values params)))
(defun guix-service-get-display (search-type &rest search-values)
- "Search for services and show results."
+ "Search for services and show results.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(apply #'bui-list-get-display-entries
'guix-service search-type search-values))
(defun guix-service-message (entries search-type &rest search-values)
- "Display a message after showing service ENTRIES."
+ "Display a message after showing service ENTRIES.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(if (null entries)
(message "Couldn't find services")
(let ((count (length entries)))
@@ -110,7 +116,7 @@ SEARCH-TYPE may be one of the following symbols: `id', `all',
(defface guix-service-info-heading
'((t :inherit bui-info-heading))
- "Face used for 'info' buffer heading (service name)."
+ "Face used for `info' buffer heading (service name)."
:group 'guix-service-info-faces)
(defface guix-service-info-description
@@ -125,7 +131,7 @@ SEARCH-TYPE may be one of the following symbols: `id', `all',
(defvar guix-service-info-required-params
'(id)
- "List of the required 'service' parameters.
+ "List of the required \\='service\\=' parameters.
These parameters are received from the Scheme side
along with the displayed parameters.
@@ -143,7 +149,9 @@ identifying an entry.")
'add)))
(defun guix-service-info-get-entries (search-type &rest search-values)
- "Return 'service' entries for displaying them in 'info' buffer."
+ "Return \\='service\\=' entries to display them in `info' buffer.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(guix-service-get-entries
search-type search-values
(cl-union guix-service-info-required-params
@@ -194,7 +202,7 @@ identifying an entry.")
(defvar guix-service-list-required-params
'(id)
- "List of the required 'service' parameters.
+ "List of the required \\='service\\=' parameters.
These parameters are received from the Scheme side
along with the displayed parameters.
@@ -213,7 +221,9 @@ identifying an entry.")
(bui-default-hint)))
(defun guix-service-list-get-entries (search-type &rest search-values)
- "Return 'service' entries for displaying them in 'list' buffer."
+ "Return \\='service\\=' entries to display them in \\='list\\=' buffer.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(guix-service-get-entries
search-type search-values
(cl-union guix-service-list-required-params
@@ -1,6 +1,7 @@
-;;; guix-ui-store-item.el --- Interface for displaying store items -*- lexical-binding: t -*-
+;;; guix-ui-store-item.el --- Interface to display store items -*- lexical-binding: t -*-
;; Copyright © 2018 Alex Kost <alezost@gmail.com>
+;; Copyright © 2025 Nicolas Graves <ngraves@ngraves.fr>
;; This file is part of Emacs-Guix.
@@ -93,21 +94,26 @@ of the file names are ignored."
(defun guix-store-item-get-entries (search-type
&optional search-values params)
- "Receive 'store-item' entries.
-SEARCH-TYPE may be one of the following symbols: `id', `live',
-`dead', `referrers', `references', `derivers', `requisites',
-`failures'."
+ "Receive \\='store-item\\=' entries.
+SEARCH-TYPE may be one of the following symbols: \\='id\\=', \\='live\\=',
+\\='dead\\=', \\='referrers\\=', \\='references\\=', \\='derivers\\=',
+\\='requisites\\=',\\='failures\\='. SEARCH-TYPE and SEARCH-VALUES define how
+to get the information. PARAMS are passed to `guix-make-guile-expression'."
(guix-eval-read
(guix-make-guile-expression
'store-item-sexps search-type search-values params)))
(defun guix-store-item-get-display (search-type &rest search-values)
- "Search for store items and show results."
+ "Search for store items and show results.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(apply #'bui-list-get-display-entries
'guix-store-item search-type search-values))
(defun guix-store-item-message (entries search-type &rest search-values)
- "Display a message after showing store item ENTRIES."
+ "Display a message after showing store item ENTRIES.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(let ((count (length entries))
(val (car search-values)))
(cl-flet ((msg (str &rest args)
@@ -189,7 +195,7 @@ SEARCH-TYPE may be one of the following symbols: `id', `live',
(defvar guix-store-item-info-required-params
'(id)
- "List of the required 'store-item' parameters.
+ "List of the required \\='store-item\\=' parameters.
These parameters are received from the Scheme side
along with the displayed parameters.
@@ -197,7 +203,9 @@ Do not remove `id' from this info as it is required for
identifying an entry.")
(defun guix-store-item-info-get-entries (search-type &rest search-values)
- "Return 'store-item' entries for displaying them in 'info' buffer."
+ "Return \\='store-item\\=' entries to display them in `info' buffer.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(guix-store-item-get-entries
search-type search-values
(cl-union guix-store-item-info-required-params
@@ -310,7 +318,7 @@ See `guix-store-item-info-insert-type-button' for the meaning of TYPE."
(defvar guix-store-item-list-required-params
'(id)
- "List of the required 'store-item' parameters.
+ "List of the required \\='store-item\\=' parameters.
These parameters are received from the Scheme side
along with the displayed parameters.
@@ -343,7 +351,9 @@ identifying an entry.")
(bui-default-hint)))
(defun guix-store-item-list-get-entries (search-type &rest search-values)
- "Return 'store-item' entries for displaying them in 'list' buffer."
+ "Return \\='store-item\\=' entries to display them in \\='list\\=' buffer.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(guix-store-item-get-entries
search-type search-values
(cl-union guix-store-item-list-required-params
@@ -435,7 +445,7 @@ Interactively, prompt for a single file name."
;;;###autoload
(defun guix-store-item-referrers (&rest file-names)
"Display referrers of the FILE-NAMES store item.
-This is analogous to 'guix gc --referrers FILE-NAMES' shell
+This is analogous to \\='guix gc --referrers FILE-NAMES\\=' shell
command. See Info node `(guix) Invoking guix gc'."
(interactive (list (guix-store-file-name-read)))
(apply #'guix-assert-files-exist file-names)
@@ -444,7 +454,7 @@ command. See Info node `(guix) Invoking guix gc'."
;;;###autoload
(defun guix-store-item-references (&rest file-names)
"Display references of the FILE-NAMES store item.
-This is analogous to 'guix gc --references FILE-NAMES' shell
+This is analogous to \\='guix gc --references FILE-NAMES\\=' shell
command. See Info node `(guix) Invoking guix gc'."
(interactive (list (guix-store-file-name-read)))
(apply #'guix-assert-files-exist file-names)
@@ -453,7 +463,7 @@ command. See Info node `(guix) Invoking guix gc'."
;;;###autoload
(defun guix-store-item-requisites (&rest file-names)
"Display requisites of the FILE-NAMES store item.
-This is analogous to 'guix gc --requisites FILE-NAMES' shell
+This is analogous to \\='guix gc --requisites FILE-NAMES\\=' shell
command. See Info node `(guix) Invoking guix gc'."
(interactive (list (guix-store-file-name-read)))
(apply #'guix-assert-files-exist file-names)
@@ -462,7 +472,7 @@ command. See Info node `(guix) Invoking guix gc'."
;;;###autoload
(defun guix-store-item-derivers (&rest file-names)
"Display derivers of the FILE-NAMES store item.
-This is analogous to 'guix gc --derivers FILE-NAMES' shell
+This is analogous to \\='guix gc --derivers FILE-NAMES\\=' shell
command. See Info node `(guix) Invoking guix gc'."
(interactive (list (guix-store-file-name-read)))
(apply #'guix-assert-files-exist file-names)
@@ -471,7 +481,7 @@ command. See Info node `(guix) Invoking guix gc'."
;;;###autoload
(defun guix-store-failures ()
"Display store items corresponding to cached build failures.
-This is analogous to 'guix gc --list-failures' shell command.
+This is analogous to \\='guix gc --list-failures\\=' shell command.
See Info node `(guix) Invoking guix gc'."
(interactive)
(guix-store-item-get-display 'failures))
@@ -479,7 +489,7 @@ See Info node `(guix) Invoking guix gc'."
;;;###autoload
(defun guix-store-live-items ()
"Display live store items.
-This is analogous to 'guix gc --list-live' shell command.
+This is analogous to \\='guix gc --list-live\\=' shell command.
See Info node `(guix) Invoking guix gc'."
(interactive)
(guix-store-item-get-display 'live))
@@ -487,7 +497,7 @@ See Info node `(guix) Invoking guix gc'."
;;;###autoload
(defun guix-store-dead-items ()
"Display dead store items.
-This is analogous to 'guix gc --list-dead' shell command.
+This is analogous to \\='guix gc --list-dead\\=' shell command.
See Info node `(guix) Invoking guix gc'."
(interactive)
(guix-store-item-get-display 'dead))
@@ -1,4 +1,4 @@
-;;; guix-ui-system-generation.el --- Interface for displaying system generations -*- lexical-binding: t -*-
+;;; guix-ui-system-generation.el --- Interface to display system generations -*- lexical-binding: t -*-
;; Copyright © 2016–2018 Alex Kost <alezost@gmail.com>
@@ -19,7 +19,7 @@
;;; Commentary:
-;; This file provides an interface for displaying system generations
+;; This file provides an interface to display system generations
;; in 'list' and 'info' buffers, and commands for working with them.
;;; Code:
@@ -39,10 +39,10 @@
(rx-to-string `(and ,guix-store-directory "/"
(+ alnum) "-shepherd.conf")
t)
- "Regexp matching 'shepherd.conf' file placed in the store.")
+ "Regexp matching \\='shepherd.conf\\=' file placed in the store.")
(defun guix-system-generation-add-kernel-config (entry)
- "Return ENTRY with 'kernel-config' parameter."
+ "Return ENTRY with \\='kernel-config\\=' parameter."
(let* ((kernel (bui-entry-value entry 'kernel))
(dir (file-name-directory kernel))
;; Nowadays kernel config has ".config" name, but before
@@ -54,7 +54,7 @@
,@entry)))
(defun guix-system-generation-add-shepherd-config (entry)
- "Return ENTRY with 'shepherd-config' parameter."
+ "Return ENTRY with \\='shepherd-config\\=' parameter."
(let* ((file-name (bui-entry-value entry 'file-name))
(boot-file (expand-file-name "boot" file-name)))
(with-temp-buffer
@@ -68,7 +68,10 @@
(defun guix-system-generation-get-entries (profile search-type
search-values params)
- "Return 'system-generation' entries."
+ "Return PROFILE \\='system-generation\\=' entries.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information.
+PARAMS are passed to `guix-generation-get-entries' after processing."
(let* ((add-kernel-config? (or (null params)
(memq 'kernel-config params)))
(add-shepherd-config? (or (null params)
@@ -129,7 +132,10 @@ SEARCH-VALUES."
(defun guix-system-generation-info-get-entries (profile search-type
&rest search-values)
- "Return 'system-generation' entries for displaying them in 'info' buffer."
+ "Return \\='system-generation\\=' entries to display them in `info' buffer.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information for
+profile PROFILE."
(guix-system-generation-get-entries
profile search-type search-values
(cl-union guix-system-generation-info-required-params
@@ -165,7 +171,9 @@ SEARCH-VALUES."
(defun guix-system-generation-list-get-entries (profile search-type
&rest search-values)
- "Return 'system-generation' entries for displaying them in 'list' buffer."
+ "Return \\='system-generation\\=' entries to display them in \\='list\\=' buffer.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information for PROFILE."
(guix-system-generation-get-entries
profile search-type search-values
(cl-union guix-system-generation-list-required-params
@@ -40,8 +40,11 @@
(number-of-services . "Services")))
(defun guix-system-get-entries (search-type search-values params)
- "Receive 'system' entries.
-SEARCH-TYPE may be one of the following symbols: `from-file'."
+ "Receive \\='system\\=' entries.
+
+SEARCH-TYPE may be one of the following symbols: \\='from-file\\='.
+SEARCH-TYPE and SEARCH-VALUES define how to get the information.
+PARAMS are passed to `guix-make-guile-expression'."
(let ((sexps (guix-eval-read
(guix-make-guile-expression
'system-sexps search-type search-values params))))
@@ -53,7 +56,9 @@ SEARCH-TYPE may be one of the following symbols: `from-file'."
sexps)))
(defun guix-system-get-display (search-type &rest search-values)
- "Search for systems and show results."
+ "Search for systems and show results.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(bui-get-display-entries
'guix-system 'info (cl-list* search-type search-values)))
@@ -76,7 +81,9 @@ SEARCH-TYPE may be one of the following symbols: `from-file'."
(initrd-modules format (format))))
(defun guix-system-info-get-entries (search-type &rest search-values)
- "Return 'system' entries for displaying them in 'info' buffer."
+ "Return \\='system\\=' entries to display them in `info' buffer.
+
+SEARCH-TYPE and SEARCH-VALUES define how to get the information."
(guix-system-get-entries
search-type search-values
(bui-info-displayed-params 'guix-system)))
@@ -111,7 +118,7 @@ SEARCH-TYPE may be one of the following symbols: `from-file'."
;;;###autoload
(defun guix-system-from-file (file)
- "Display info on 'operating-system' declaration from FILE.
+ "Display info on \\='operating-system\\=' declaration from FILE.
See `guix-packages-from-system-config-file' for more details on FILE.
Interactively, prompt for FILE (see also `guix-support-dired')."
(interactive (list (guix-read-os-file-name)))
@@ -50,14 +50,14 @@ See `bui-hint' for details.")
guix-ui-current profile search-type search-values)
(defun guix-ui-read-package-profile ()
- "Return `guix-current-profile' or prompt for it.
+ "Return variable `guix-current-profile' or prompt for it.
This function is intended for using in `interactive' forms."
(if current-prefix-arg
(guix-read-package-profile)
guix-current-profile))
(defun guix-ui-read-generation-profile ()
- "Return `guix-current-profile' or prompt for it.
+ "Return variable `guix-current-profile' or prompt for it.
This function is intended for using in `interactive' forms."
(if current-prefix-arg
(guix-read-generation-profile)
@@ -83,7 +83,7 @@ with all available parameters."
profile entry-type search-type search-values params)))
(defun guix-ui-list-describe (&rest ids)
- "Describe 'ui' entries with IDS (list of identifiers)."
+ "Describe \\='ui\\=' entries with IDS (list of identifiers)."
(bui-get-display-entries
(bui-current-entry-type) 'info
(cl-list* (guix-ui-current-profile) 'id ids)
@@ -116,7 +116,7 @@ The function is called with 2 arguments: BASE-NAME and PROFILE."
(guix-compose-buffer-name base-name profile))
(defun guix-ui-buffer-name (base-name profile)
- "Return Guix buffer name based on BASE-NAME and profile.
+ "Return Guix buffer name based on BASE-NAME and PROFILE.
See `guix-ui-buffer-name-function' for details."
(funcall guix-ui-buffer-name-function
base-name profile))
@@ -141,7 +141,7 @@ This macro also defines:
(defun ,message-fun (entries profile search-type
&rest search-values)
,(format "\
-Display a message after showing '%s' entries.
+Display a message after showing \\='%s\\=' entries.
This is a wrapper for `guix-result-message'."
entry-type-str)
(guix-result-message profile entries ',entry-type
@@ -154,7 +154,7 @@ This is a wrapper for `guix-result-message'."
,@args))))
(defmacro guix-ui-define-interface (entry-type buffer-type &rest args)
- "Define BUFFER-TYPE interface for displaying ENTRY-TYPE entries.
+ "Define BUFFER-TYPE interface to display ENTRY-TYPE entries.
Remaining arguments (ARGS) should have a form [KEYWORD VALUE] ...
In the following description TYPE means ENTRY-TYPE-BUFFER-TYPE.
@@ -200,7 +200,7 @@ Along with the mentioned definitions, this macro also defines:
(defvar ,required-var ,required-val
,(format "\
-List of the required '%s' parameters.
+List of the required \\='%s\\=' parameters.
These parameters are received from the Scheme side
along with the displayed parameters.
@@ -210,7 +210,7 @@ identifying an entry."
(defun ,buffer-name-fun (profile &rest _)
,(format "\
-Return a name of '%s' buffer for displaying '%s' entries.
+Return a name of \\='%s\\=' buffer to display \\='%s\\=' entries.
See `guix-ui-buffer-name' for details."
buffer-type-str entry-type-str)
(guix-ui-buffer-name ,buffer-name-val profile))
@@ -67,17 +67,17 @@ This function is similar to `shell-quote-argument', but less strict."
(rx (not (any alnum "-=,./\n"))) "\\\\\\&" argument))))
(defun guix-command-symbol (&optional args)
- "Return symbol by concatenating 'guix-command' and ARGS (strings)."
+ "Return symbol by concatenating \\='guix-command\\=' and ARGS (strings)."
(intern (guix-concat-strings (cons "guix-command" args) "-")))
(defun guix-command-string (&optional args)
- "Return 'guix ARGS ...' string with quoted shell arguments."
+ "Return \\='guix ARGS ...\\=' string with quoted shell arguments."
(let ((args (mapcar #'guix-shell-quote-argument args)))
(guix-concat-strings (cons "guix" args) " ")))
(defun guix-copy-command-as-kill (args &optional no-message?)
- "Put 'guix ARGS ...' string into `kill-ring'.
-See also `guix-copy-as-kill'."
+ "Put \\='guix ARGS ...\\=' string into `kill-ring'.
+See also `bui-copy-as-kill' for NO-MESSAGE?."
(bui-copy-as-kill (guix-command-string args) no-message?))
(defun guix-compose-buffer-name (base-name postfix)
@@ -106,37 +106,36 @@ If BASE-NAME is wrapped by '*', then the result is:
(concat "*" name-body ": " postfix "*")
(concat base-name ": " postfix)))))
-(defun guix-completing-read (prompt table &optional predicate
- require-match initial-input
- hist def inherit-input-method)
- "Same as `completing-read' but return nil instead of an empty string."
- (let ((res (completing-read prompt table predicate
- require-match initial-input
- hist def inherit-input-method)))
+(defun guix-completing-read (prompt table &rest completing-read-rest)
+ "Same as `completing-read' but return nil instead of an empty string.
+
+Pass PROMPT, TABLE and the COMPLETING-READ-REST arguments to `completing-read'."
+ (let ((res (apply #'completing-read prompt table completing-read-rest)))
(unless (string= "" res) res)))
-(defun guix-completing-read-multiple (prompt table &optional predicate
- require-match initial-input
- hist def inherit-input-method)
- "Same as `completing-read-multiple' but remove duplicates in result."
+(defun guix-completing-read-multiple (prompt table &rest completing-read-rest)
+ "Same as `completing-read-multiple', but remove duplicates in result.
+
+Pass PROMPT, TABLE and the COMPLETING-READ-REST arguments to
+`completing-read-multiple'."
(cl-remove-duplicates
- (completing-read-multiple prompt table predicate
- require-match initial-input
- hist def inherit-input-method)
+ (apply #'completing-read-multiple prompt table completing-read-rest)
:test #'string=))
(declare-function org-read-date "org" t)
(defun guix-read-date (prompt)
- "Prompt for a date or time using `org-read-date'.
-Return time value."
+ "PROMPT for a date or time using `org-read-date'.
+Return a time value."
(require 'org)
(org-read-date nil t nil prompt))
(declare-function pcmpl-unix-user-names "pcmpl-unix")
(defun guix-read-user-name (&optional prompt initial-input)
- "Prompt for a user name using completions."
+ "Prompt for a user name using completions.
+
+Optionally takes PROMPT and INITIAL-INPUT arguments of `completing-read'."
(require 'pcmpl-unix)
(guix-completing-read (or prompt "User name: ")
(pcmpl-unix-user-names)
@@ -246,12 +245,12 @@ See `guix-modify' for details."
objects))
(defun guix-make-symbol (&rest symbols)
- "Return `guix-SYMBOLS-...' symbol."
+ "Return \\='guix-symbols-...\\=' SYMBOLS."
(apply #'bui-make-symbol 'guix symbols))
(defmacro guix-define-groups (name &rest args)
- "Define `guix-NAME' and `guix-NAME-faces' customization groups.
-See `bui-define-groups' for details."
+ "Define `guix-name' and `guix-name-faces' customization groups from NAME.
+See `bui-define-groups' for ARGS and details."
(declare (indent 1))
`(bui-define-groups ,(bui-make-symbol 'guix name)
:parent-group guix
@@ -309,30 +308,29 @@ argument."
"Expand FILE-NAME and remove trailing slash if needed."
(directory-file-name (expand-file-name file-name)))
-(defun guix-read-file-name (&optional prompt dir default-filename
- mustmatch initial predicate)
+(defun guix-read-file-name (&optional prompt &rest read-file-name-rest)
"Read file name.
This function is similar to `read-file-name' except it also
-expands the file name."
+expands the file name. Pass PROMPT and READ-FILE-NAME-REST arguments
+to `read-file-name'."
(expand-file-name
- (read-file-name (or prompt "File: ")
- dir default-filename
- mustmatch initial predicate)))
+ (apply #'read-file-name (or prompt "File: ") read-file-name-rest)))
(declare-function dired-get-filename "dired" t)
-(defun guix-read-file-name-maybe (&optional prompt dir default-filename
- mustmatch initial predicate)
+(defun guix-read-file-name-maybe (&optional prompt &rest read-file-name-rest)
"Read file name or get it from `dired-mode'.
-See `guix-support-dired' for details. See also `guix-read-file-name'."
+See `guix-support-dired' for details. See also `guix-read-file-name'.
+This function is similar to `read-file-name' except it also
+expands the file name. Pass PROMPT and READ-FILE-NAME-REST arguments
+to `read-file-name'."
(if (and guix-support-dired
(derived-mode-p 'dired-mode))
(dired-get-filename)
- (guix-read-file-name prompt dir default-filename
- mustmatch initial predicate)))
+ (apply #'guix-read-file-name prompt read-file-name-rest)))
(defun guix-read-os-file-name ()
- "Read file name with Guix System 'operating-system' declaration."
+ "Read file name with Guix System \\='operating-system\\=' declaration."
(guix-read-file-name-maybe "System configuration file: "))
(defun guix-find-file (file)
@@ -373,8 +371,7 @@ example:
However, if COMPILED is non-nil, the directory with
compiled (.go) files is returned, for example:
- ROOT/lib/guile/2.2/site-ccache
-"
+ ROOT/lib/guile/2.2/site-ccache"
(let* ((dir (expand-file-name (if compiled
"lib/guile"
"share/guile/site")
@@ -398,7 +395,7 @@ If nil, it will be set when it will be used the first time.
This directory will be deleted on Emacs exit.")
(defun guix-temporary-directory ()
- "Return `guix-temporary-directory' (set it if needed)."
+ "Return the variable `guix-temporary-directory' (set it if needed)."
(or (and guix-temporary-directory
(file-exists-p guix-temporary-directory)
guix-temporary-directory)
@@ -406,7 +403,7 @@ This directory will be deleted on Emacs exit.")
(make-temp-file "emacs-guix-" 'dir))))
(defun guix-temporary-file-name (name &optional suffix)
- "Return file NAME from `guix-temporary-directory'.
+ "Return file NAME from the variable `guix-temporary-directory'.
If such file name already exists, or if SUFFIX string is
specified, make the returned name unique."
(let* ((file-name (expand-file-name name (guix-temporary-directory)))
@@ -418,7 +415,7 @@ specified, make the returned name unique."
file-name)))
(defun guix-delete-temporary-directory ()
- "Delete `guix-temporary-directory' if it exists."
+ "Delete the variable `guix-temporary-directory' if it exists."
(when (and guix-temporary-directory
(file-exists-p guix-temporary-directory))
(condition-case nil
@@ -458,7 +455,9 @@ If nil, do not perform refontifying.")
"A string or list of strings specifying switches to be passed to diff.")
(defun guix-diff (old new &optional switches no-async)
- "Same as `diff', but use `guix-diff-switches' as default."
+ "Same as `diff', but use `guix-diff-switches' as default.
+
+OLD, NEW, SWITCHES and NO-ASYNC are passed to `diff'."
(diff old new (or switches guix-diff-switches) no-async))
@@ -468,7 +467,8 @@ If nil, do not perform refontifying.")
&optional require-match default)
"Define NAME function to read from minibuffer.
READ-FUN may be `completing-read', `completing-read-multiple' or
-another function with the same arguments."
+another function with the same arguments. COMPLETIONS, PROMPT,
+REQUIRE-MATCH and DEFAULT are passed to this function."
(declare (indent 1))
`(defun ,name (&optional prompt initial-contents)
(,read-fun (or prompt ,prompt)
@@ -558,7 +558,7 @@ keywords are available:
(defmacro guix-memoized-defun (name arglist docstring &rest body)
"Define a memoized function NAME.
-See `defun' for the meaning of arguments."
+See `defun' for the meaning of arguments ARGLIST, DOCSTRING and BODY."
(declare (doc-string 3) (indent 2))
`(defalias ',name
(guix-memoize (lambda ,arglist ,@body))
@@ -572,7 +572,8 @@ See `defun' for the meaning of arguments."
docstring)))
(defmacro guix-memoized-defalias (symbol definition &optional docstring)
- "Set SYMBOL's function definition to memoized version of DEFINITION."
+ "Set SYMBOL's function definition to memoized version of DEFINITION.
+Optionally provide DOCSTRING."
(declare (doc-string 3) (indent 1))
`(defalias ',symbol
(guix-memoize #',definition)