branch: externals/emms commit 675fba101a075c412c31e991b66dadc67a45e55d Author: Yoni Rabkin <y...@gnu.org> Commit: Yoni Rabkin <y...@gnu.org>
Escape single quotes in documentation strings. This is to avoid compilation warnings post Emacs 29.1. --- emms-browser.el | 43 +++++++++++++++---------------- emms-info-native.el | 2 +- emms-lyrics.el | 20 +++++++-------- emms-player-mpd.el | 4 +-- emms-player-mpv.el | 68 +++++++++++++++++++++++++------------------------- emms-playlist-limit.el | 14 +++++------ emms-tag-editor.el | 18 ++++++------- emms.el | 4 +-- 8 files changed, 87 insertions(+), 86 deletions(-) diff --git a/emms-browser.el b/emms-browser.el index 0b334aba48..e0dcc41ac7 100644 --- a/emms-browser.el +++ b/emms-browser.el @@ -364,7 +364,7 @@ Called once for each directory." (make-variable-buffer-local 'emms-browser-top-level-hash) (defvar emms-browser-top-level-type nil - "The current mapping type, eg. 'info-artist.") + "The current mapping type, eg. \\='info-artist.") (make-variable-buffer-local 'emms-browser-top-level-type) (defvar emms-browser-current-indent nil @@ -587,10 +587,10 @@ This function can be used as (defun emms-browser-get-track-field-albumartist (track type) "Return TYPE from TRACK with an albumartist-oriented heuristic. -For 'info-artist TYPE, use 'info-albumartistsort, 'info-albumartist, -'info-artistsort. -For 'info-year TYPE, use 'info-originalyear, 'info-originaldate and -'info-date symbols." +For \\='info-artist TYPE, use \\='info-albumartistsort, +\\='info-albumartist, \\='info-artistsort. +For \\='info-year TYPE, use \\='info-originalyear, \\='info-originaldate and +\\='info-date symbols." (cond ((eq type 'info-artist) (or (emms-track-get track 'info-albumartist) (emms-track-get track 'info-albumartistsort) @@ -701,7 +701,8 @@ browser, and hit 'b 1' to refresh."))) (defun emms-browser-next-mapping-type (current-mapping) "Return the next sensible mapping. -Eg. if CURRENT-MAPPING is currently 'info-artist, return 'info-album." +Eg. if CURRENT-MAPPING is currently \\='info-artist, return + \\='info-album." (cond ((eq current-mapping 'info-artist) 'info-album) ((eq current-mapping 'info-composer) 'info-album) @@ -720,7 +721,7 @@ Eg. if CURRENT-MAPPING is currently 'info-artist, return 'info-album." (defun emms-browser-make-bdata-tree-recurse (type level tracks) "Build a tree of alists based on a list of tracks, TRACKS. -For example, if TYPE is 'info-year, return an alist like: +For example, if TYPE is \\='info-year, return an alist like: artist1 -> album1 -> *track* 1.." (let* ((next-type (emms-browser-next-mapping-type type)) (next-level (1+ level)) @@ -778,8 +779,8 @@ return an empty string." discnum))) (defun emms-browser-year-number (track) - "Return a string representation of a track's year. -This will be in the form '(1998) '." + "Return a string representation of a track\\='s year. +This will be in the form \\='(1998) \\='." (let ((year (emms-track-get-year track))) (if (or (not (stringp year)) (string= year "0")) "" @@ -800,7 +801,7 @@ If no duration is available, return an empty string." "Return a browser data item from ALIST. DATA should be a list of DB items, or a list of tracks. NAME is a name for the DB item. -TYPE is a category the data is organised by, such as 'info-artist. +TYPE is a category the data is organised by, such as \\='info-artist. LEVEL is the number of the sublevel the db item will be placed in." (list (cons 'type type) (cons 'level level) @@ -809,7 +810,7 @@ LEVEL is the number of the sublevel the db item will be placed in." (defun emms-browser-make-alist (type tracks) "Make an alist mapping of TYPE -> TRACKS. -Items with no metadata for TYPE will be placed in 'misc'" +Items with no metadata for TYPE will be placed in \\='misc\\='" (let (db key existing tracknum) (dolist (track tracks) (setq key (emms-browser-get-track-field track type)) @@ -831,8 +832,8 @@ Items with no metadata for TYPE will be placed in 'misc'" (defun emms-browser-make-sorted-alist (type tracks) "Return a sorted alist of TRACKS. -TYPE is the metadata to make the alist by - eg. if it's -'info-artist, an alist of artists will be made." +TYPE is the metadata to make the alist by - eg. if it\\='s +\\='info-artist, an alist of artists will be made." (emms-browser-sort-alist (emms-browser-make-alist type tracks) type)) @@ -2067,10 +2068,10 @@ If the track is not of TYPE, return t." width nor height exceed this dimension.") (defun emms-browser-thumbnail-filter-default (dir) - "Select covers containing 'front' or 'cover' in DIR. -If none was found, fallback on `emms-browser-thumbnail-filter-all'. + "Select covers containing \\='front\\=' or \\='cover\\=' in DIR. +If none was found, fallback on `emms-browser-thumbnail-filter-all\\='. -See `emms-browser-thumbnail-filter'." +See `emms-browser-thumbnail-filter\\='." (when (file-directory-p dir) (let ((ls (directory-files dir t nil t)) (case-fold-search t) @@ -2082,7 +2083,7 @@ See `emms-browser-thumbnail-filter'." covers))) (defun emms-browser-thumbnail-filter-all (dir) - "Return the list of all files with `emms-browser-covers-file-extensions' in DIR. + "Return the list of all files with `emms-browser-covers-file-extensions\\=' in DIR. See `emms-browser-thumbnail-filter'." (let (covers) @@ -2102,19 +2103,19 @@ See also `emms-browser-thumbnail-filter-default'.") (defun emms-browser-cache-thumbnail (dir size) "Return cached cover SIZE for album in DIR. -SIZE must be 'small, 'medium or 'large. It will determine the +SIZE must be \\='small, \\='medium or \\='large. It will determine the resolution of the cached file. See the variables -`emms-browser-thumbnail-SIZE-size'. +`emms-browser-thumbnail-SIZE-size\\='. If cover is not cached or if cache is out-of-date, re-cache it. If both the width and the height of the cover are smaller than -`emms-browser-thumbnail-SIZE-size', it need not be cached and +`emms-browser-thumbnail-SIZE-size\\=', it need not be cached and will be used directly. Emms assumes that you have one album per folder. This function will always use the same cover per folder. -`emms-browser-covers' can be `fset' to this function." +`emms-browser-covers\\=' can be `fset\\=' to this function." (if (eq size 'large) ;; 'large is unused for now. Return empty. nil diff --git a/emms-info-native.el b/emms-info-native.el index e17df9126a..15f2d4cfae 100644 --- a/emms-info-native.el +++ b/emms-info-native.el @@ -717,7 +717,7 @@ Sources: (defun emms-info-native--checked-id3v2-size (elt bytes) "Calculate id3v2 element ELT size from BYTES. -ELT must be either 'tag or 'frame. +ELT must be either \\='tag or \\='frame. Return the size. Signal an error if the size is zero." (let ((size (cond ((eq elt 'tag) diff --git a/emms-lyrics.el b/emms-lyrics.el index 8d482ec55f..34c2afda79 100644 --- a/emms-lyrics.el +++ b/emms-lyrics.el @@ -247,7 +247,7 @@ If we can't find it from local disk, then search it from internet." ;;; EMMS Lyrics (defvar emms-lyrics-alist nil - "a list of the form: '((time0 . lyric0) (time1 . lyric1)...)). In + "a list of the form: \\='((time0 . lyric0) (time1 . lyric1)...)). In short, at time-i, display lyric-i.") (defvar emms-lyrics-timers nil @@ -267,7 +267,7 @@ short, at time-i, display lyric-i.") (defun emms-lyrics-read-file (file &optional catchup) "Read a lyric file(LRC format). -Optional CATCHUP is for recognizing `emms-lyrics-catchup'. +Optional CATCHUP is for recognizing `emms-lyrics-catchup\\='. FILE should end up with \".lrc\", its content looks like one of the following: @@ -276,7 +276,7 @@ following: [00:39.67]I love you, Emacs! FILE should be under the same directory as the music file, or under -`emms-lyrics-dir'." +`emms-lyrics-dir\\='." (or catchup (setq file (funcall emms-lyrics-find-lyric-function file))) (when (and file (file-exists-p file)) @@ -310,7 +310,7 @@ FILE should be under the same directory as the music file, or under t))) (defun emms-lyrics-create-buffer () - "Create `emms-lyrics-buffer' dedicated to lyrics. " + "Create `emms-lyrics-buffer\\=' dedicated to lyrics. " ;; leading white space in buffer name to hide the buffer (setq emms-lyrics-buffer (get-buffer-create " *EMMS Lyrics*")) (set-buffer emms-lyrics-buffer) @@ -447,15 +447,15 @@ job." (defun emms-lyrics-display-handler (lyric next-lyric line diff) "DIFF is the timestamp differences between current LYRIC and -NEXT-LYRIC; LINE corresponds line number for LYRIC in `emms-lyrics-buffer'." +NEXT-LYRIC; LINE corresponds line number for LYRIC in `emms-lyrics-buffer\\='." (emms-lyrics-display (format emms-lyrics-display-format lyric) line) (when (and emms-lyrics-display-on-modeline emms-lyrics-scroll-p) (emms-lyrics-scroll lyric next-lyric diff))) (defun emms-lyrics-display (lyric line) "Display LYRIC now. -See `emms-lyrics-display-on-modeline' and -`emms-lyrics-display-on-minibuffer' on how to config where to +See `emms-lyrics-display-on-modeline\\=' and +`emms-lyrics-display-on-minibuffer\\=' on how to config where to display." (when emms-lyrics-alist (when emms-lyrics-display-on-modeline @@ -481,8 +481,8 @@ display." (defun emms-lyrics-find-lyric (file) "Return full path of found lrc FILE, or nil if not found. -Use `emms-source-file-directory-tree-function' to find lrc FILE under -current directory and `emms-lyrics-dir'. +Use `emms-source-file-directory-tree-function\\=' to find lrc FILE under +current directory and `emms-lyrics-dir\\='. e.g., (emms-lyrics-find-lyric \"abc.lrc\")" (let* ((track (emms-playlist-current-selected-track)) (lyric-under-curr-dir @@ -530,7 +530,7 @@ NEXT-LYRIC." (define-key map "n" #'emms-lyrics-next-line) (define-key map "i" #'emms-lyrics-insert-time) map) - "Keymap for `emms-lyrics-mode'.") + "Keymap for `emms-lyrics-mode\\='.") (defun emms-lyrics-rem* (x y) "The remainder of X divided by Y, with the same sign as X." diff --git a/emms-player-mpd.el b/emms-player-mpd.el index 7a692b5584..d1d6257d4b 100644 --- a/emms-player-mpd.el +++ b/emms-player-mpd.el @@ -130,10 +130,10 @@ :type '(cons symbol alist)) (defcustom emms-player-mpd-music-directory nil - "The value of 'music_directory' in your MusicPD configuration file. + "The value of \\='music_directory\\=' in your MusicPD configuration file. Unless your MusicPD is configured to use absolute file names, you must -set this variable to the value of 'music_directory' in your MusicPD +set this variable to the value of \\='music_directory\\=' in your MusicPD config." ;; The :format part ensures that entering directories happens on the ;; next line, where there is more space to work with diff --git a/emms-player-mpv.el b/emms-player-mpv.el index 86436af22b..4b7b9084fc 100644 --- a/emms-player-mpv.el +++ b/emms-player-mpv.el @@ -110,11 +110,11 @@ in the list." (defcustom emms-player-mpv-ipc-method nil "Switch for which IPC method to use with mpv. Possible symbols: detect, ipc-server, unix-socket, file. -Defaults to nil value, which will cause `emms-player-mpv-ipc-detect' +Defaults to nil value, which will cause `emms-player-mpv-ipc-detect\\=' to pick one based on mpv --version output. Using JSON-IPC variants (ipc-server and unix-socket) enables support for various feedback and metadata options from mpv. -Use of 'file value here is deprecated and will be removed in the future." +Use of \\='file value here is deprecated and will be removed in the future." :type '(choice (const :tag "Auto-detect from mpv --version" nil) (const :tag "Use --input-ipc-server JSON IPC (v0.17.0 2016-04-11)" ipc-server) @@ -234,35 +234,35 @@ Should be fine with both mpv and Emacs, and probably never reached anyway.") "Internal flag to track when stop command starts/finishes before next loadfile. Set to either nil, t or the playback start function to call on end-file event after stop command. -This is a workaround for mpv-0.30+ behavior, where 'stop + loadfile' only -runs 'stop'.") +This is a workaround for mpv-0.30+ behavior, where \\='stop + loadfile\\=' only +runs \\='stop\\='.") (defvar emms-player-mpv-event-connect-hook nil "Normal hook run right after establishing new JSON IPC connection to mpv. -Runs before `emms-player-mpv-ipc-connect-command', if any. -Best place to send any `observe_property', `request_log_messages', -`enable_event' commands. -Use `emms-player-mpv-ipc-id-get' to get unique id values for these. -See also `emms-player-mpv-event-functions'.") +Runs before `emms-player-mpv-ipc-connect-command\\=', if any. +Best place to send any `observe_property\\=', `request_log_messages\\=', +`enable_event\\=' commands. +Use `emms-player-mpv-ipc-id-get\\=' to get unique id values for these. +See also `emms-player-mpv-event-functions\\='.") (defvar emms-player-mpv-event-functions nil "List of functions to call for each event emitted from JSON IPC. One argument is passed to each function - JSON line, -as sent by mpv and decoded by `json-read-from-string'. -See also `emms-player-mpv-event-connect-hook'.") +as sent by mpv and decoded by `json-read-from-string\\='. +See also `emms-player-mpv-event-connect-hook\\='.") (defvar emms-player-mpv-stopped nil "Non-nil if playback was stopped by call from emms. -Similar to `emms-player-stopped-p', but set for future async events, +Similar to `emms-player-stopped-p\\=', but set for future async events, to indicate that playback should stop instead of switching to next track.") (defvar emms-player-mpv-idle-timer (timer-create) - "Timer to delay `emms-player-stopped' when mpv unexpectedly goes idle.") + "Timer to delay `emms-player-stopped\\=' when mpv unexpectedly goes idle.") (defvar emms-player-mpv-idle-delay 0.5 - "Delay before issuing `emms-player-stopped' when mpv unexpectedly goes idle.") + "Delay before issuing `emms-player-stopped\\=' when mpv unexpectedly goes idle.") (defvar emms-player-mpv-ipc-conn-emacs-26.1-workaround @@ -278,10 +278,10 @@ are used there instead.") (defvar emms-player-mpv-debug nil "Enable to print sent/received JSON lines and process -start/stop events to *Messages* buffer using `emms-player-mpv-debug-msg'.") +start/stop events to *Messages* buffer using `emms-player-mpv-debug-msg\\='.") (defvar emms-player-mpv-debug-ts-offset nil - "Timestamp offset for `emms-player-mpv-debug-msg'. + "Timestamp offset for `emms-player-mpv-debug-msg\\='. Set on first use, with intent to both shorten and obfuscate time in logs.") (defun emms-player-mpv-debug-trim (s) @@ -290,7 +290,7 @@ Set on first use, with intent to both shorten and obfuscate time in logs.") s)) (defun emms-player-mpv-debug-msg (tpl-or-msg &rest tpl-values) - "Print debug message to *Messages* if `emms-player-mpv-debug' is non-nil. + "Print debug message to *Messages* if `emms-player-mpv-debug\\=' is non-nil. Message is only formatted if TPL-VALUES is non-empty. Strips whitespace from start/end of TPL-OR-MSG and strings in TPL-VALUES." (when emms-player-mpv-debug @@ -309,8 +309,8 @@ Strips whitespace from start/end of TPL-OR-MSG and strings in TPL-VALUES." (defun emms-player-mpv-ipc-fifo-p () "Returns non-nil if --input-file fifo should be used. -Runs `emms-player-mpv-ipc-detect' to detect/set -`emms-player-mpv-ipc-method' if necessary." +Runs `emms-player-mpv-ipc-detect\\=' to detect/set +`emms-player-mpv-ipc-method\\=' if necessary." (unless emms-player-mpv-ipc-method (setq emms-player-mpv-ipc-method (emms-player-mpv-ipc-detect emms-player-mpv-command-name))) @@ -319,7 +319,7 @@ Runs `emms-player-mpv-ipc-detect' to detect/set (defun emms-player-mpv-ipc-detect (cmd) "Run mpv --version and return symbol for best IPC method supported. CMD should be either name of mpv binary to use or full path to it. -Return values correspond to `emms-player-mpv-ipc-method' options. +Return values correspond to `emms-player-mpv-ipc-method\\=' options. Error is signaled if mpv binary fails to run." (with-temp-buffer (let ((exit-code (call-process cmd nil '(t t) @@ -347,14 +347,14 @@ Error is signaled if mpv binary fails to run." ;; ----- mpv process (defun emms-player-mpv-proc-playing-p (&optional proc) - "Return whether playback in PROC or `emms-player-mpv-proc' is started, -which is distinct from 'start-command sent' and 'process is running' states. -Used to signal emms via `emms-player-started' and `emms-player-stopped' calls." + "Return whether playback in PROC or `emms-player-mpv-proc\\=' is started, +which is distinct from \\='start-command sent\\=' and \\='process is running\\=' states. +Used to signal emms via `emms-player-started\\=' and `emms-player-stopped\\=' calls." (let ((proc (or proc emms-player-mpv-proc))) (and proc (process-get proc 'mpv-playing)))) (defun emms-player-mpv-proc-playing (state &optional proc) - "Set process mpv-playing state flag for `emms-player-mpv-proc-playing-p'." + "Set process mpv-playing state flag for `emms-player-mpv-proc-playing-p\\='." (let ((proc (or proc emms-player-mpv-proc))) (when proc (process-put proc 'mpv-playing state)))) @@ -592,16 +592,16 @@ follow-up command should be stored to (defun emms-player-mpv-ipc-req-send (cmd &optional handler proc) "Send JSON IPC request and assign HANDLER to response for it, if any. -CMD value is encoded via `json-encode'. +CMD value is encoded via `json-encode\\='. HANDLER func will be called with decoded response JSON as (handler data err), where ERR will be either nil on -\"success\", 'connection-error or whatever is in JSON. If -HANDLER is nil, default `emms-player-mpv-ipc-req-error-printer' +\"success\", \\='connection-error or whatever is in JSON. If +HANDLER is nil, default `emms-player-mpv-ipc-req-error-printer\\=' will be used to at least log errors. Multiple commands can be -batched in one list as '(batch (cmd1 . handler1) ...), in which +batched in one list as \\='(batch (cmd1 . handler1) ...), in which case common HANDLER argument is ignored. PROC can be specified -to avoid `emms-player-mpv-ipc' call (e.g. from sentinel/filter +to avoid `emms-player-mpv-ipc\\=' call (e.g. from sentinel/filter funcs)." (dolist (cmd-and-handler @@ -814,8 +814,8 @@ track duration from mpv." (defun emms-player-mpv-cmd (cmd &optional handler) "Send mpv command to process/connection if both are running, or otherwise schedule start/connect and set -`emms-player-mpv-ipc-connect-command' for `emms-player-mpv-ipc-sentinel'. -Multiple commands can be batched in one list as '(batch (cmd1 . handler1) ...), +`emms-player-mpv-ipc-connect-command\\=' for `emms-player-mpv-ipc-sentinel\\='. +Multiple commands can be batched in one list as \\='(batch (cmd1 . handler1) ...), in which case common HANDLER argument is ignored." (setq emms-player-mpv-ipc-connect-command nil) (let ((proc (emms-player-mpv-ipc))) @@ -826,14 +826,14 @@ in which case common HANDLER argument is ignored." (setq emms-player-mpv-ipc-connect-command cmd)))) (defmacro emms-player-mpv-cmd-prog (cmd &rest handler-body) - "Obsolete macro around `emms-player-mpv-cmd' that creates handler -callback (see `emms-player-mpv-ipc-req-send') from HANDLER-BODY + "Obsolete macro around `emms-player-mpv-cmd\\=' that creates handler +callback (see `emms-player-mpv-ipc-req-send\\=') from HANDLER-BODY forms, which have following bindings: - mpv-cmd for CMD. - mpv-data for response data (decoded json, nil if none). - mpv-error for response error (nil if no error, decoded json or - 'connection-error). + \\='connection-error). Do not use it with new code - it will raise warnings when used with lexical bindings, and will be removed in a future EMMS diff --git a/emms-playlist-limit.el b/emms-playlist-limit.el index f21f4f84a5..df283746ad 100644 --- a/emms-playlist-limit.el +++ b/emms-playlist-limit.el @@ -147,12 +147,12 @@ If this playlist is current, make the playlist we switch to current." (defun emms-playlist-limit-track-get (track type) "Return the value of TYPE from TRACK. -Here TYPE is a field available to `emms-track-get' or -'description which gives the result of -`emms-track-description-function'. +Here TYPE is a field available to `emms-track-get\\=' or +\\='description which gives the result of +`emms-track-description-function\\='. -When type is 'info-year, also tries 'info-originalyear, - 'info-originaldate and 'info-date to get a usable date." +When type is \\='info-year, also tries \\='info-originalyear, + \\='info-originaldate and \\='info-date to get a usable date." (cond ((eq type 'info-year) (let ((date (or (emms-track-get track 'info-originaldate) (emms-track-get track 'info-originalyear) @@ -192,9 +192,9 @@ is non-nil." (defun emms-playlist-limit-do (type regexp) "Switch to a derived playlist containing the tracks with TYPE matching REGEXP. e.g., - (emms-playlist-limit-do 'info-artist \"Jane Zhang\") + (emms-playlist-limit-do \\='info-artist \"Jane Zhang\") -See `emms-info-mp3find-arguments' for possible options for TYPE." +See `emms-info-mp3find-arguments\\=' for possible options for TYPE." (emms-playlist-ensure-playlist-buffer) (let* ((curr (emms-playlist-selected-track)) (old-buf (current-buffer)) diff --git a/emms-tag-editor.el b/emms-tag-editor.el index 13fb57e292..8c50df59cf 100644 --- a/emms-tag-editor.el +++ b/emms-tag-editor.el @@ -118,14 +118,14 @@ the track, and returns a string to insert in used for inserting the track.") (defvar emms-tag-editor-parse-function 'emms-tag-editor-default-parser - "Function to parse tags in `emms-tag-editor-edit-buffer'. + "Function to parse tags in `emms-tag-editor-edit-buffer\\='. It should find all modified tags, and return all the tracks. The tracks for which a tag has been modified should set a property -'tag-modified to t. If the track name has been changed, the -function should set a new property 'newname instead of setting -the 'name directly. +\\='tag-modified to t. If the track name has been changed, the +function should set a new property \\='newname instead of setting +the \\='name directly. -See also `emms-tag-editor-default-parser'.") +See also `emms-tag-editor-default-parser\\='.") (defvar emms-tag-editor-tagfile-functions '(("mp3" "mid3v2" @@ -832,15 +832,15 @@ A pipe is defined like below: :arguments is a list or a function return list, for example: (\"--track-name\" name (\"--year\" info-year)) - (lambda (track) (list (emms-track-name track 'name))) + (lambda (track) (list (emms-track-name track \\='name))) -1. symbols can be 'name or elements of (mapcar 'car emms-tag-editor-tags), +1. symbols can be \\='name or elements of (mapcar \\='car emms-tag-editor-tags), which will be replaced to track info before run command. 2. sublist used to deal with group args, for example, (\"--year\" info-year), when - track's info-year is nil, the \"--year\" will be removed too.") + track\\='s info-year is nil, the \"--year\" will be removed too.") (defun emms-tag-editor-pipe-get (pipe-name key) - "Get the pipe value of KEY named PIPE-NAME in `emms-tag-editor-pipe-config'." + "Get the pipe value of KEY named PIPE-NAME in `emms-tag-editor-pipe-config\\='." (let ((config emms-tag-editor-pipe-config)) (plist-get (cdr (assoc pipe-name config)) key))) diff --git a/emms.el b/emms.el index 4c592a4df4..398ee9d2fe 100644 --- a/emms.el +++ b/emms.el @@ -784,8 +784,8 @@ string), a confusing error message would result." (defun emms-track-get-year (track) "Get year of TRACK for display. -There is the separation between the 'release date' and the -'original date'. This difference matters e.g. for +There is the separation between the \\='release date\\=' and the +\\='original date\\='. This difference matters e.g. for re-releases (anniversaries and such) where the release date is more recent than the original release date. In such cases the user probably wants the original release date so this is what we