branch: elpa/subed commit 3289584686c3dc770fe64304a0a18ee00c47cf14 Author: Random User <rnd...@posteo.de> Commit: Random User <rnd...@posteo.de>
Pacify checkdoc --- subed/subed-config.el | 61 ++++++++++---------- subed/subed-mpv.el | 29 +++++++--- subed/subed-srt.el | 45 ++++++++++----- subed/subed.el | 154 ++++++++++++++++++++++++++++---------------------- 4 files changed, 167 insertions(+), 122 deletions(-) diff --git a/subed/subed-config.el b/subed/subed-config.el index 49041cb..4688490 100644 --- a/subed/subed-config.el +++ b/subed/subed-config.el @@ -19,9 +19,13 @@ ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, ;; Boston, MA 02110-1301, USA. -;;; Code: -;; Key bindings +;;; Commentary: + +;; Customization variables, hooks, keybindings, etc for subed-mode. + + +;;; Code: (defvar subed-mode-map (let ((subed-mode-map (make-keymap))) @@ -51,7 +55,7 @@ (define-key subed-mode-map (kbd "C-c .") #'subed-toggle-sync-point-to-player) (define-key subed-mode-map (kbd "C-c ,") #'subed-toggle-sync-player-to-point) subed-mode-map) - "Keymap for subed-mode") + "Keymap for ‘subed-mode’.") ;; Syntax highlighting @@ -104,29 +108,31 @@ This is set by `subed-mode-enable' and `subed-mode-disable'.") :group 'subed) (defcustom subed-auto-find-video t - "Whether to open the video automatically when opening a subtitle file. -The corresponding video is found by replacing the file extension -of `buffer-file-name' with those in `subed-video-extensions'. -The first existing file is then passed to `subed-open-video'." + "Whether to open the video automatically when opening a subtitle file." :type 'boolean :group 'subed) (defcustom subed-milliseconds-adjust 100 - "Number of milliseconds to add/subtract to subtitle start/stop -times when adjust, moving or shifting subtitles. + "Milliseconds to add or subtract from start/stop time. -This variable is set if the functions that use this variable are -called with a prefix argument. That makes the value of this -variable persistent for the duration of the sessio. Use -`setq-default' to change the default value." +This variable is used when adjusting, moving or shifting +subtitles without a prefix argument. + +This variable is set when adjusting, moving or shifting subtitles +with a prefix argument. See `subed-increase-start-time' for +details. + +Use `setq-default' to change the default value of this variable." :type 'float :group 'subed) (defun subed-get-milliseconds-adjust (arg) - "Set `subed-milliseconds-adjust' to `arg' if it's a number. If -`arg' is non-nil, reset `subed-milliseconds-adjust' to its + "Set `subed-milliseconds-adjust' to ARG if it's a number. + +If ARG is non-nil, reset `subed-milliseconds-adjust' to its default. + Return new `subed-milliseconds-adjust' value." (cond ((integerp arg) (setq subed-milliseconds-adjust arg)) ;; Custom adjustment @@ -136,20 +142,18 @@ Return new `subed-milliseconds-adjust' value." (defcustom subed-playback-speed-while-typing 0 - "Video playback speed while the user is editing the buffer. If -set to zero or smaller, playback is paused." + "Video playback speed while the user is editing the buffer. +If set to zero or smaller, playback is paused." :type 'float :group 'subed) (defcustom subed-playback-speed-while-not-typing 1.0 - "Video playback speed while the user is not editing the -buffer." + "Video playback speed while the user is not editing the buffer." :type 'float :group 'subed) (defcustom subed-unpause-after-typing-delay 1.0 - "Number of seconds to wait after typing stopped before -unpausing the player." + "Number of seconds to wait after typing stopped before unpausing the player." :type 'float :group 'subed) @@ -158,26 +162,22 @@ unpausing the player." (defcustom subed-subtitle-spacing 100 - "How many milliseconds to keep between subtitles when adjusting -or inserting subtitles." + "Milliseconds between subtitles when adjusting or inserting subtitles." :type 'integer :group 'subed) (defcustom subed-default-subtitle-length 1.0 - "How long to make subtitles in seconds when inserted after the -last subtitle." + "How long to make subtitles in seconds when inserted after the last subtitle." :type 'float :group 'subed) (defcustom subed-loop-seconds-before 0 - "When looping over subtitle(s), start the loop this many -earlier." + "Prelude in seconds when looping over subtitle(s)." :type 'float :group 'subed) (defcustom subed-loop-seconds-after 0 - "When looping over subtitle(s), end the loop this many seconds -later." + "Addendum in seconds when looping over subtitle(s)." :type 'float :group 'subed) @@ -189,8 +189,7 @@ later." (defcustom subed-point-sync-delay-after-motion 1.0 - "Number of seconds the player can't adjust point after point -was moved by the user." + "Number of seconds the player can't adjust point after point was moved by the user." :type 'float :group 'subed) diff --git a/subed/subed-mpv.el b/subed/subed-mpv.el index 587f107..c2f08fc 100644 --- a/subed/subed-mpv.el +++ b/subed/subed-mpv.el @@ -70,7 +70,10 @@ See also `subed-mpv-socket-base'." (buffer-hash))) (defun subed-mpv--server-start (&rest args) - "Run mpv in JSON IPC mode." + "Run mpv in JSON IPC mode. + +Pass ARGS as command line arguments. \"--idle\" and +\"--input-ipc-server\" are hardcoded." (subed-mpv--server-stop) (let ((argv (append (list subed-mpv-executable (format "--input-ipc-server=%s" (subed-mpv--socket)) @@ -100,7 +103,7 @@ See also `subed-mpv-socket-base'." ;;; Client (elisp process that connects to server's IPC socket) (defun subed-mpv--client-buffer () - "Unique name of buffer that stores RPC responses." + "Unique name of buffer that store RPC responses." (if subed-debugging-enabled-p (format "*subed-mpv-buffer:%s-%s*" (file-name-base (or (buffer-file-name) "unnamed")) @@ -111,8 +114,8 @@ See also `subed-mpv-socket-base'." (defun subed-mpv--client-connect (delays) "Try to connect to `subed-mpv--socket'. -If a connection attempt fails, wait (car delays) seconds and try -again, passing (cdr delays)." +If a connection attempt fails, wait (car DELAYS) seconds and try +again with (cdr DELAYS) as arguments." (subed-debug "Attempting to connect to IPC socket: %s" (subed-mpv--socket)) (subed-mpv--client-disconnect) ;; NOTE: make-network-process doesn't fail when the socket file doesn't exist @@ -177,7 +180,10 @@ CMD to `subed-mpv--client-command-queue' which is evaluated by t))) (defun subed-mpv--client-filter (proc response) - "Handle response from the server." + "Handle response from the server. + +PROC is the mpv process and RESPONSE is the response as a JSON +string." ;; JSON-STRING contains zero or more lines with JSON encoded objects, e.g.: ;; {"data":"mpv 0.29.1","error":"success"} ;; {"data":null,"request_id":1,"error":"success"} @@ -209,7 +215,7 @@ CMD to `subed-mpv--client-command-queue' which is evaluated by (subed-mpv--client-handle-json line))))))))) (defun subed-mpv--client-handle-json (json-string) - "Process a single JSON object from the server." + "Process server response JSON-STRING." (let* ((json-data (condition-case err (json-read-from-string json-string) (error @@ -222,6 +228,10 @@ CMD to `subed-mpv--client-command-queue' which is evaluated by (defun subed-mpv--handle-event (json-data) "Handler for relevant mpv events. + +JSON-DATA is mpv's JSON response in the form of an association +list. + See \"List of events\" in mpv(1)." (let ((event (alist-get 'event json-data))) (pcase event @@ -267,11 +277,11 @@ See \"List of events\" in mpv(1)." (setq subed-mpv-playback-speed factor)))) (defun subed-mpv-seek (msec) - "Move playback position SEC seconds relative to current position." + "Move playback position MSEC milliseconds relative to current position." (subed-mpv--client-send `(seek ,(/ msec 1000.0) relative+exact))) (defun subed-mpv-jump (msec) - "Move playback position to absolute position SEC seconds." + "Move playback position to absolute position MSEC milliseconds." (subed-mpv--client-send `(seek ,(/ msec 1000.0) absolute+exact))) (defun subed-mpv-reload-subtitles () @@ -286,7 +296,8 @@ See \"List of events\" in mpv(1)." (member (file-name-extension filename) subed-video-extensions))))) (defun subed-mpv-find-video (file) - "Open video file in mpv. + "Open video file FILE in mpv. + Video files are expected to have any of the extensions listed in `subed-video-extensions'." (interactive (list (read-file-name "Find video: " nil nil t nil #'subed-mpv--is-video-file-p))) diff --git a/subed/subed-srt.el b/subed/subed-srt.el index 7f350bd..b1052d2 100644 --- a/subed/subed-srt.el +++ b/subed/subed-srt.el @@ -19,6 +19,12 @@ ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, ;; Boston, MA 02110-1301, USA. + +;;; Commentary: + +;; SubRip/srt implementation for subed-mode. + + ;;; Code: ;;; Syntax highlighting @@ -29,7 +35,7 @@ '("[0-9]+:[0-9]+:[0-9]+,[0-9]+" . 'subed-srt-time-face) '(",[0-9]+ \\(-->\\) [0-9]+:" 1 'subed-srt-time-separator-face t) '("^.*$" . 'subed-srt-text-face)) - "Highlighting expressions for subed-mode") + "Highlighting expressions for `subed-mode'.") ;;; Parsing @@ -97,7 +103,8 @@ after MSECS if there is one and its start time is >= MSECS + (subed-srt--subtitle-id)))) (defun subed-srt--subtitle-msecs-start (&optional sub-id) - "Subtitle start time in milliseconds or nil if it can't be found." + "Subtitle start time in milliseconds or nil if it can't be found. +If SUB-ID is not given, use subtitle on point." (let ((timestamp (save-excursion (when (subed-srt--jump-to-subtitle-time-start sub-id) (when (looking-at subed-srt--regexp-timestamp) @@ -106,7 +113,8 @@ after MSECS if there is one and its start time is >= MSECS + (subed-srt--timestamp-to-msecs timestamp)))) (defun subed-srt--subtitle-msecs-stop (&optional sub-id) - "Subtitle stop time in milliseconds or nil if it can't be found." + "Subtitle stop time in milliseconds or nil if it can't be found. +If SUB-ID is not given, use subtitle on point." (let ((timestamp (save-excursion (when (subed-srt--jump-to-subtitle-time-stop sub-id) (when (looking-at subed-srt--regexp-timestamp) @@ -115,7 +123,8 @@ after MSECS if there is one and its start time is >= MSECS + (subed-srt--timestamp-to-msecs timestamp)))) (defun subed-srt--subtitle-text (&optional sub-id) - "Return subtitle's text." + "Return subtitle's text. +If SUB-ID is not given, use subtitle on point." (or (save-excursion (let ((beg (subed-srt--jump-to-subtitle-text sub-id)) (end (subed-srt--jump-to-subtitle-end sub-id))) @@ -135,7 +144,7 @@ after MSECS if there is one and its start time is >= MSECS + (defun subed-srt--jump-to-subtitle-id (&optional sub-id) "Move to the ID of a subtitle and return point. -If SUBTITLE-ID is not given, focus the current subtitle's ID. +If SUB-ID is not given, focus the current subtitle's ID. Return point or nil if no subtitle ID could be found." (interactive) (save-match-data @@ -174,6 +183,7 @@ See also `subed-srt--subtitle-id-at-msecs'." (defun subed-srt--jump-to-subtitle-time-start (&optional sub-id) "Move point to subtitle's start time. +If SUB-ID is not given, use subtitle on point. Return point or nil if no start time could be found." (interactive) (save-match-data @@ -184,6 +194,7 @@ Return point or nil if no start time could be found." (defun subed-srt--jump-to-subtitle-time-stop (&optional sub-id) "Move point to subtitle's stop time. +If SUB-ID is not given, use subtitle on point. Return point or nil if no stop time could be found." (interactive) (save-match-data @@ -195,7 +206,8 @@ Return point or nil if no stop time could be found." (defun subed-srt--jump-to-subtitle-text (&optional sub-id) "Move point on the first character of subtitle's text. -Return point." +If SUB-ID is not given, use subtitle on point. +Return point or nil if a the subtitle's text can't be found." (interactive) (when (subed-srt--jump-to-subtitle-id sub-id) (forward-line 2) @@ -210,6 +222,7 @@ See also `subed-srt--subtitle-id-at-msecs'." (defun subed-srt--jump-to-subtitle-end (&optional sub-id) "Move point after the last character of the subtitle's text. +If SUB-ID is not given, use subtitle on point. Return point or nil if point did not change or if no subtitle end can be found." (interactive) @@ -370,12 +383,13 @@ nil if nothing was adjusted." (defun subed-srt--subtitle-insert (&optional arg) "Insert subtitle(s). -`universal-argument' is used in the following manner: + +ARG, usually provided by `universal-argument', is used in the +following manner: \\[subed-subtitle-insert] Insert 1 subtitle after the current subtitle - \\[universal-argument] - \\[subed-subtitle-insert] Insert 1 subtitle before the current subtitle + \\[universal-argument] \\[subed-subtitle-insert] Insert 1 subtitle before the current subtitle \\[universal-argument] 5 \\[subed-subtitle-insert] Insert 5 subtitles after the current subtitle \\[universal-argument] - 5 \\[subed-subtitle-insert] Insert 5 subtitles before the current subtitle - \\[universal-argument] \\[subed-subtitle-insert] Insert 1 subtitle before the current subtitle \\[universal-argument] \\[universal-argument] \\[subed-subtitle-insert] Insert 2 subtitles before the current subtitle" (interactive "P") (save-match-data @@ -476,8 +490,7 @@ nil if nothing was adjusted." ;;; Maintenance (defun subed-srt--regenerate-ids () - "Ensure subtitle IDs start at 1 and are incremented by 1 for -each subtitle." + "Ensure consecutive, unduplicated subtitle IDs." (interactive) (atomic-change-group (save-match-data @@ -497,10 +510,12 @@ each subtitle." (defvar-local subed-srt--regenerate-ids-soon-timer nil) (defun subed-srt--regenerate-ids-soon () - "Run `subed-srt--regenerate-ids' in 100ms unless this function -is called again within the next 100ms, in which case the -previously scheduled call is canceled and another call is -scheduled in 100ms." + "Delay regenerating subtitle IDs for a short amount of time. + +Run `subed-srt--regenerate-ids' in 100ms unless this function is +called again within the next 100ms, in which case the previously +scheduled call is canceled and another call is scheduled in +100ms." (interactive) (when subed-srt--regenerate-ids-soon-timer (cancel-timer subed-srt--regenerate-ids-soon-timer)) diff --git a/subed/subed.el b/subed/subed.el index b46c509..0cfb4c7 100644 --- a/subed/subed.el +++ b/subed/subed.el @@ -71,7 +71,7 @@ ;;; Debugging (defun subed-enable-debugging () - "Hide debugging messages and set `debug-on-error' to `nil'." + "Hide debugging messages and set `debug-on-error' to nil." (interactive) (unless subed-debugging-enabled-p (setq subed-debugging-enabled-p t @@ -86,8 +86,7 @@ (add-hook 'kill-buffer-hook #'subed-disable-debugging :append :local))) (defun subed-disable-debugging () - "Display debugging messages in separate window and set -`debug-on-error' to `t'." + "Display debugging messages in separate window and set `debug-on-error' to t." (interactive) (when subed-debugging-enabled-p (setq subed-debugging-enabled-p nil @@ -98,19 +97,18 @@ (remove-hook 'kill-buffer-hook #'subed-disable-debugging :local))) (defun subed-toggle-debugging () - "Display or hide debugging messages in separate window and set -`debug-on-error' to `t' or `nil'." + "Display or hide debugging messages in separate window and set `debug-on-error' to t or nil." (interactive) (if subed-debugging-enabled-p (subed-disable-debugging) (subed-enable-debugging))) -(defun subed-debug (format-string &rest args) - "Display message in debugging buffer if it exists." +(defun subed-debug (msg &rest args) + "Pass MSG and ARGS to `format' and show the result in debugging buffer if it exists." (when (get-buffer subed-debug-buffer) (with-current-buffer (get-buffer-create subed-debug-buffer) (setq-local buffer-read-only nil) - (insert (apply #'format (concat format-string "\n") args)) + (insert (apply #'format (concat msg "\n") args)) (setq-local buffer-read-only t) (let ((debug-window (get-buffer-window subed-debug-buffer))) (when debug-window @@ -175,12 +173,11 @@ Before BODY is run, point is placed on the subtitle's ID." ;;; Adjusting start/stop time individually (defun subed-increase-start-time (&optional arg) - "Add `subed-milliseconds-adjust' milliseconds to start time of -current subtitle. + "Add `subed-milliseconds-adjust' milliseconds to start time. Return new start time in milliseconds or nil if it didn't change. -If a prefix argument is given, it is used to set +If prefix argument ARG is given, it is used to set `subed-milliseconds-adjust' before moving subtitles. If the prefix argument is given but not numerical, `subed-milliseconds-adjust' is reset to its default value. @@ -196,26 +193,29 @@ Example usage: (subed-adjust-subtitle-start (subed-get-milliseconds-adjust arg))) (defun subed-decrease-start-time (&optional arg) - "Subtract `subed-milliseconds-adjust' milliseconds from start -time of current subtitle. + "Subtract `subed-milliseconds-adjust' milliseconds from start time. + Return new start time in milliseconds or nil if it didn't change. -See also `subed-increase-start-time'." + +See `subed-increase-start-time' about ARG." (interactive "P") (subed-adjust-subtitle-start (* -1 (subed-get-milliseconds-adjust arg)))) (defun subed-increase-stop-time (&optional arg) - "Add `subed-milliseconds-adjust' milliseconds to stop time of -current subtitle. + "Add `subed-milliseconds-adjust' milliseconds to stop time. + Return new stop time in milliseconds or nil if it didn't change. -See also `subed-increase-start-time'." + +See `subed-increase-start-time' about ARG." (interactive "P") (subed-adjust-subtitle-stop (subed-get-milliseconds-adjust arg))) (defun subed-decrease-stop-time (&optional arg) - "Subtract `subed-milliseconds-adjust' milliseconds from stop -time of current subtitle. + "Subtract `subed-milliseconds-adjust' milliseconds from stop time. + Return new stop time in milliseconds or nil if it didn't change. -See also `subed-increase-start-time'." + +See `subed-increase-start-time' about ARG." (interactive "P") (subed-adjust-subtitle-stop (* -1 (subed-get-milliseconds-adjust arg)))) @@ -247,14 +247,15 @@ subtitle if replaying is enabled." (subed-mpv-jump (subed-subtitle-msecs-start))))) (defun subed-move-subtitle-forward (&optional arg) - "Move subtitle `subed-milliseconds-adjust' forward in time -while preserving its duration, i.e. increase start and stop time -by the same amount. + "Move subtitle `subed-milliseconds-adjust' forward. + +Moving adjusts start and stop time by the same amount, preserving +subtitle duration. All subtitles that are fully or partially in the active region are moved. -If a prefix argument is given, it is used to set +If prefix argument ARG is given, it is used to set `subed-milliseconds-adjust' before moving subtitles. If the prefix argument is given but not numerical, `subed-milliseconds-adjust' is reset to its default value. @@ -274,11 +275,9 @@ Example usage: (subed-move-subtitles msecs beg end))) (defun subed-move-subtitle-backward (&optional arg) - "Move subtitle `subed-milliseconds-adjust' backward in time -while preserving its duration, i.e. decrease start and stop time -by the same amount. + "Move subtitle `subed-milliseconds-adjust' backward. -See `subed-move-subtitle-forward'." +See `subed-move-subtitle-forward' about ARG." (interactive "P") (let ((deactivate-mark nil) (msecs (* -1 (subed-get-milliseconds-adjust arg))) @@ -291,8 +290,12 @@ See `subed-move-subtitle-forward'." ;;; (same as moving, but follow-up subtitles are also moved) (defun subed-shift-subtitle-forward (&optional arg) - "Shifting subtitles is like moving them, but it always moves -the subtitles between point and the end of the buffer." + "Shift subtitle `subed-milliseconds-adjust' backward. + +Shifting is like moving, but it always moves the subtitles +between point and the end of the buffer. + +See `subed-move-subtitle-forward' about ARG." (interactive "P") (let ((deactivate-mark nil) (msecs (subed-get-milliseconds-adjust arg)) @@ -300,8 +303,12 @@ the subtitles between point and the end of the buffer." (subed-move-subtitles msecs beg))) (defun subed-shift-subtitle-backward (&optional arg) - "Shifting subtitles is like moving them, but it always moves -the subtitles between point and the end of the buffer." + "Shift subtitle `subed-milliseconds-adjust' backward. + +Shifting is like moving, but it always moves the subtitles +between point and the end of the buffer. + +See `subed-move-subtitle-forward' about ARG." (interactive "P") (let ((deactivate-mark nil) (msecs (* -1 (subed-get-milliseconds-adjust arg))) @@ -312,12 +319,13 @@ the subtitles between point and the end of the buffer." ;;; Replay time-adjusted subtitle (defun subed-replay-adjusted-subtitle-p () - "Whether adjusting a subtitle's start/stop time causes the -player to jump to the subtitle's start position." + "Whether the player jumps to start time if start or stop time is adjusted." (member #'subed--replay-adjusted-subtitle subed-subtitle-time-adjusted-hook)) (defun subed-enable-replay-adjusted-subtitle (&optional quiet) - "Automatically replay a subtitle when its start/stop time is adjusted." + "Automatically replay a subtitle when its start/stop time is adjusted. + +If QUIET is non-nil, do not display a message in the minibuffer." (interactive) (unless (subed-replay-adjusted-subtitle-p) (add-hook 'subed-subtitle-time-adjusted-hook #'subed--replay-adjusted-subtitle :append :local) @@ -326,7 +334,9 @@ player to jump to the subtitle's start position." (message "Enabled replaying adjusted subtitle")))) (defun subed-disable-replay-adjusted-subtitle (&optional quiet) - "Do not replay a subtitle automatically when its start/stop time is adjusted." + "Do not replay a subtitle automatically when its start/stop time is adjusted. + +If QUIET is non-nil, do not display a message in the minibuffer." (interactive) (when (subed-replay-adjusted-subtitle-p) (remove-hook 'subed-subtitle-time-adjusted-hook #'subed--replay-adjusted-subtitle :local) @@ -335,8 +345,7 @@ player to jump to the subtitle's start position." (message "Disabled replaying adjusted subtitle")))) (defun subed-toggle-replay-adjusted-subtitle () - "Enable or disable automatic replaying of subtitle when its -start/stop time is adjusted." + "Enable/disable subtitle replay when start/stop time is adjusted." (interactive) (if (subed-replay-adjusted-subtitle-p) (subed-disable-replay-adjusted-subtitle) @@ -355,7 +364,9 @@ start/stop time is adjusted." (member #'subed--sync-point-to-player subed-mpv-playback-position-hook)) (defun subed-enable-sync-point-to-player (&optional quiet) - "Automatically move point to the currently playing subtitle." + "Automatically move point to the currently playing subtitle. + +If QUIET is non-nil, do not display a message in the minibuffer." (interactive) (unless (subed-sync-point-to-player-p) (add-hook 'subed-mpv-playback-position-hook #'subed--sync-point-to-player :append :local) @@ -364,8 +375,9 @@ start/stop time is adjusted." (message "Enabled syncing point to playback position")))) (defun subed-disable-sync-point-to-player (&optional quiet) - "Do not move point automatically to the currently playing -subtitle." + "Do not move point automatically to the currently playing subtitle. + +If QUIET is non-nil, do not display a message in the minibuffer." (interactive) (when (subed-sync-point-to-player-p) (remove-hook 'subed-mpv-playback-position-hook #'subed--sync-point-to-player :local) @@ -374,15 +386,14 @@ subtitle." (message "Disabled syncing point to playback position")))) (defun subed-toggle-sync-point-to-player () - "Enable or disable moving point automatically to the currently -playing subtitle." + "Enable/disable moving point to the currently playing subtitle." (interactive) (if (subed-sync-point-to-player-p) (subed-disable-sync-point-to-player) (subed-enable-sync-point-to-player))) (defun subed--sync-point-to-player (msecs) - "Move point to currently playing subtitle." + "Move point to subtitle at MSECS." (when (and (not (use-region-p)) (subed-jump-to-subtitle-text-at-msecs msecs)) (subed-debug "Synchronized point to playback position: %s -> #%s" @@ -398,8 +409,9 @@ playing subtitle." (defvar-local subed--point-sync-delay-after-motion-timer nil) (defun subed-disable-sync-point-to-player-temporarily () - "If point is synced to playback position, temporarily disable -that for `subed-point-sync-delay-after-motion' seconds." + "Temporarily disable syncing point to player. + +After `subed-point-sync-delay-after-motion' seconds point is re-synced." (if subed--point-sync-delay-after-motion-timer (cancel-timer subed--point-sync-delay-after-motion-timer) (setq subed--point-was-synced (subed-sync-point-to-player-p))) @@ -416,12 +428,13 @@ that for `subed-point-sync-delay-after-motion' seconds." ;;; Sync player-to-point (defun subed-sync-player-to-point-p () - "Whether playback position is automatically adjusted to -subtitle at point." + "Whether playback position jumps to subtitle at point." (member #'subed--sync-player-to-point subed-subtitle-motion-hook)) (defun subed-enable-sync-player-to-point (&optional quiet) - "Automatically seek player to subtitle at point." + "Automatically seek player to subtitle at point. + +If QUIET is non-nil, do not display a message in the minibuffer." (interactive) (unless (subed-sync-player-to-point-p) (subed--sync-player-to-point) @@ -431,7 +444,9 @@ subtitle at point." (message "Enabled syncing playback position to point")))) (defun subed-disable-sync-player-to-point (&optional quiet) - "Do not automatically seek player to subtitle at point." + "Do not automatically seek player to subtitle at point. + +If QUIET is non-nil, do not display a message in the minibuffer." (interactive) (when (subed-sync-player-to-point-p) (remove-hook 'subed-subtitle-motion-hook #'subed--sync-player-to-point :local) @@ -462,13 +477,13 @@ subtitle at point." ;;; Loop over single subtitle (defun subed-subtitle-loop-p () - "Whether player is rewinded to start of current subtitle every -time it reaches the subtitle's stop time." + "Whether the player is looping over the current subtitle." (or subed--subtitle-loop-start subed--subtitle-loop-stop)) (defun subed-toggle-subtitle-loop (&optional quiet) - "Enable or disable looping in player over currently focused -subtitle." + "Enable or disable looping in player over the current subtitle. + +If QUIET is non-nil, do not display a message in the minibuffer." (interactive) (if (subed-subtitle-loop-p) (progn @@ -499,8 +514,7 @@ subtitle." (subed-srt--msecs-to-timestamp subed--subtitle-loop-stop))) (defun subed--ensure-subtitle-loop (cur-msecs) - "Seek back to `subed--subtitle-loop-start' if player is after -`subed--subtitle-loop-stop'." + "Jump to current subtitle start time if CUR-MSECS is after stop time." (when (and subed--subtitle-loop-start subed--subtitle-loop-stop subed-mpv-is-playing) (when (or (< cur-msecs subed--subtitle-loop-start) @@ -515,15 +529,19 @@ subtitle." ;;; Pause player while the user is editing (defun subed-pause-while-typing-p () - "Whether player is automatically paused or slowed down while -the user is editing the buffer. + "Whether player is automatically paused or slowed down during editing. + See `subed-playback-speed-while-typing' and `subed-playback-speed-while-not-typing'." (member #'subed--pause-while-typing after-change-functions)) (defun subed-enable-pause-while-typing (&optional quiet) - "Automatically pause player while the user is editing the -buffer for `subed-unpause-after-typing-delay' seconds." + "Pause player while the user is editing a subtitle. + +After `subed-unpause-after-typing-delay' seconds, playback is +resumed automatically unless the player was paused already. + +If QUIET is non-nil, do not display a message in the minibuffer." (unless (subed-pause-while-typing-p) (add-hook 'after-change-functions #'subed--pause-while-typing :append :local) (when (not quiet) @@ -534,16 +552,16 @@ buffer for `subed-unpause-after-typing-delay' seconds." subed-playback-speed-while-typing))))) (defun subed-disable-pause-while-typing (&optional quiet) - "Do not automatically pause player while the user is editing -the buffer." + "Do not automatically pause player while the user is editing the buffer. + +If QUIET is non-nil, do not display a message in the minibuffer." (when (subed-pause-while-typing-p) (remove-hook 'after-change-functions #'subed--pause-while-typing :local) (when (not quiet) (message "Playback speed will not change while subtitle texts are edited")))) (defun subed-toggle-pause-while-typing () - "Enable or disable auto-pausing while the user is editing the -buffer." + "Enable or disable auto-pausing while the user is editing the buffer." (interactive) (if (subed-pause-while-typing-p) (subed-disable-pause-while-typing) @@ -551,10 +569,12 @@ buffer." (defvar-local subed--unpause-after-typing-timer nil) (defun subed--pause-while-typing (&rest args) - "Pause or slow down playback for `subed-unpause-after-typing-delay' seconds." + "Pause or slow down playback for `subed-unpause-after-typing-delay' seconds. + +This function is meant to be an item in `after-change-functions' +and therefore gets ARGS, which is ignored." (when subed--unpause-after-typing-timer (cancel-timer subed--unpause-after-typing-timer)) - (when (or subed-mpv-is-playing subed--player-is-auto-paused) (if (<= subed-playback-speed-while-typing 0) ;; Pause playback @@ -643,7 +663,7 @@ Return nil if function `buffer-file-name' returns nil." (defun subed-mode () "Major mode for editing subtitles. -This function enables or disables subed-mode. See also +This function enables or disables `subed-mode'. See also `subed-mode-enable' and `subed-mode-disable'. Key bindings: