From 5723174cc52d68a94ba9dc67300b4076765c111d Mon Sep 17 00:00:00 2001 From: Mats Lidell Date: Sat, 6 Aug 2022 17:26:47 +0200 Subject: [PATCH] hycontrol.el: Shorten docs strings to be within 80 char limit. --- ChangeLog | 4 + hycontrol.el | 274 +++++++++++++++++++++++++++++++-------------------- 2 files changed, 171 insertions(+), 107 deletions(-) diff --git a/ChangeLog b/ChangeLog index 44116354..cc8889fd 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2022-08-06 Mats Lidell + +* hycontrol.el: Shorten docs strings to be within 80 char limit. + 2022-07-26 Mats Lidell * kotl/kproperty.el: diff --git a/hycontrol.el b/hycontrol.el index d817c8f1..196ffab9 100644 --- a/hycontrol.el +++ b/hycontrol.el @@ -3,9 +3,9 @@ ;; Author: Bob Weiner ;; ;; Orig-Date: 1-Jun-16 at 15:35:36 -;; Last-Mod: 16-May-22 at 00:12:56 by Bob Weiner +;; Last-Mod: 6-Aug-22 at 17:25:25 by Mats Lidell ;; -;; Copyright (C) 2016-2021 Free Software Foundation, Inc. +;; Copyright (C) 2016-2022 Free Software Foundation, Inc. ;; See the "HY-COPY" file for license information. ;; ;; This file is part of GNU Hyperbole. @@ -134,7 +134,7 @@ ;;; ************************************************************************ (defvar hycontrol-debug nil - "When set non-nil by a user, some HyControl functions log debugging messages to the *Messages* buffer.") + "Whether some HyControl functions log debugging messages to *Messages*.") (defvar hycontrol-display-buffer-predicate-list ;; Display only buffers attached to files. @@ -149,30 +149,31 @@ evaluated with the buffer argument as the current buffer, e.g. (eq major-mode 'c-mode).") (defcustom hycontrol-help-flag t - "*When t (the default), display key binding help in the minibuffer when in a HyControl mode." + "*Non-nil means show key binding help in the minibuffer when in a HyControl mode." :type 'boolean :group 'hyperbole-screen) (defcustom hycontrol-invert-mode-line-flag t - "*When t (default) and in a HyControl mode, invert mode-line to emphasize the special key bindings in effect." + "*Non-nil means invert mode-line to emphasize the special key bindings in effect." :type 'boolean :group 'hyperbole-screen) (defcustom hycontrol-keep-window-flag nil - "*When non-nil (default is nil), leave original window when tear off window to another frame." + "*Non-nil means leave original window when tear off window to another frame." :type 'boolean :group 'hyperbole-screen) (defcustom hycontrol-maximum-units 1000 "*Maximum units setting allowed for hycontrol commands. -The unit counter resets to the last digit entered whenever this value is exceeded." +The unit counter resets to the last digit entered whenever this +value is exceeded." :type '(integer :match (lambda (_widget value) (and (integerp value) (> value 0) (<= value (max 1000 (display-pixel-width)))))) :group 'hyperbole-screen) (defcustom hycontrol-frame-offset '(13 . 23) - "*Increase in pixel offset for new hycontrol frames relative to the selected frame. + "*Increase in offset for new hycontrol frames relative to the selected frame. Its value is an (x-offset . y-offset) pair in pixels." :type '(cons integer integer) :group 'hyperbole-screen) @@ -181,7 +182,9 @@ Its value is an (x-offset . y-offset) pair in pixels." '(((1920 . 1080) . (0 10 0 68)) ; 24" iMac HD display ((2560 . 1440) . (0 15 0 93)) ; 27" iMac HD display (t . (0 0 0 0))) - "*Alist of (screen-predicate . (top-offset right-offset bottom-offset left-offset) pairs. + "*Alist of screen predicate offset pairs. +The format is (screen-predicate . (top-offset right-offset +bottom-offset left-offset). Offsets are integers given in pixels. The offsets associated with the first matching screen-predicate are used in HyControl screen edge frame placement commands; this is set when HyControl is first loaded/used. @@ -219,12 +222,12 @@ The final predicate should always be t, for default values, typically of zero.") (defvar hycontrol-frame-widths '(1.0 0.75 0.666 0.5 0.333 0.25) - "List of frame width percentages that HyControl cycles through when adjusting a frame's width. + "List of width percentages to cycle through when adjusting a frame's width. 0.75 and 75 are treated as the same percentage.") (defvar hycontrol-frame-heights '(1.0 0.75 0.666 0.5 0.333 0.25) - "List of frame height percentages that HyControl cycles through when adjusting a frame's height. + "List of height percentages to cycle through when adjusting a frame's height. 0.75 and 75 are treated as the same percentage.") (defvar hycontrol-arg nil @@ -480,11 +483,13 @@ associated key: quit {q}, abort {C-g}, or toggle {t}.") (defvar hycontrol--quit-function nil - "Stores function auto-generated by a call to `set-transient-map' to remove the transient-map later.") + "Stores function to remove the transient-map later. +The function is auto-generated by a call to `set-transient-map'") (defvar hycontrol--screen-edge-position 0 - "Cycles between 0-7 representing corner and center edge positions in clockwise order from the upper left corner.") + "Cycles between 0-7 representing corner and center edge positions. +The cycle is in clockwise order from the upper left corner.") (defvar hycontrol--frame-widths-pointer nil) (defvar hycontrol--frame-heights-pointer nil) @@ -492,7 +497,8 @@ associated key: quit {q}, abort {C-g}, or toggle {t}.") (defvar hycontrol--buffer-list-pointer nil) (defvar hycontrol--initial-which-key-inhibit nil - "Stores value of `which-key-inhibit' flag from \"which-key\" package upon entry to HyControl, if any.") + "Store value of `which-key-inhibit' flag from \"which-key\" package, if any. +Used on entry to HyControl.") ;;; ************************************************************************ ;;; Private functions @@ -551,7 +557,7 @@ If the argument is 0, set it to -1." hycontrol-arg (if (zerop hycontrol-arg) -1 (- hycontrol-arg)))) (defun hycontrol-minus-key () - "Conditional command to execute when the minus key is pressed in a HyControl mode." + "Conditional command to execute when the minus key is pressed." (interactive) (cond ((and (symbolp last-command) (string-match-p "\\`\\(hui:menu-enter\\|hycontrol.*-\\(frames\\|windows\\|prefix\\|universal\\)-\\(mode\\|arg\\)\\)" (symbol-name last-command))) @@ -562,7 +568,7 @@ If the argument is 0, set it to -1." (hycontrol-window-minimize-lines)))) (defun hycontrol-multiply-universal-arg () - "Return the new prefix argument based on existing `hycontrol-arg' and one press of the universal arg, C-u." + "Return prefix arg based on `hycontrol-arg' and one press of the universal arg." (interactive) (setq this-command 'hycontrol-multiply-universal-arg hycontrol-arg (* hycontrol-arg 4)) @@ -675,36 +681,48 @@ relative to Left and Top which are both zero." (frame-edges frame 'outer-edges)) (defsubst hycontrol-frame-x-origin (&optional frame) - "Return the X origin coordinate (upper left point) of optional FRAME or the selected frame. This includes all graphical window manager decorations. -Under a graphical window system, this is in pixels; otherwise, it is in characters." + "Return the X origin coordinate of optional FRAME or the selected frame. +This includes all graphical window manager decorations. The X +origin coordinate is the upper left point. Under a graphical +window system, this is in pixels; otherwise, it is in characters." (nth 0 (hycontrol-frame-edges frame))) (defsubst hycontrol-frame-y-origin (&optional frame) - "Return the Y origin coordinate (upper left point) of optional FRAME or the selected frame. This includes all graphical window manager decorations. -Under a graphical window system, this is in pixels; otherwise, it is in characters." + "Return the Y origin coordinate of optional FRAME or the selected frame. +This includes all graphical window manager decorations. The Y +origin coordinate is the upper left point. Under a graphical +window system, this is in pixels; otherwise, it is in characters." (nth 1 (hycontrol-frame-edges frame))) (defun hycontrol-frame-height (&optional frame) - "Return the height of optional FRAME or the selected frame. This includes all graphical window manager decorations. -Under a graphical window system, this is in pixels; otherwise, it is in characters." + "Return the height of optional FRAME or the selected frame. +This includes all graphical window manager decorations. Under a +graphical window system, this is in pixels; otherwise, it is in +characters." (frame-pixel-height frame)) (defun hycontrol-frame-width (&optional frame) - "Return the width of optional FRAME or the selected frame. This includes all graphical window manager decorations. -Under a graphical window system, this is in pixels; otherwise, it is in characters." + "Return the width of optional FRAME or the selected frame. +This includes all graphical window manager decorations. Under a +graphical window system, this is in pixels; otherwise, it is in +characters." (frame-pixel-width frame)) ;; Frame Resizing Support (defconst hycontrol-screen-offset-sensitivity 12 - "Number of pixels a frame dimension can be off from its screen-offset and still be considered at the screen edge.") + "Screen edge sensitivity in pixels. +Number of pixels a frame dimension can be off from its +screen-offset and still be considered at the screen edge.") (defun hycontrol-frame-at-left-p () - "Return non-nil if selected frame's left edge is at the left edge of the screen sans `hycontrol-screen-left-offset'." + "Non-nil if selected frame's left edge is at the left edge of the screen. +Screen left edge is adjusted based on `hycontrol-screen-left-offset'." (<= (- (nth 0 (hycontrol-frame-edges)) hycontrol-screen-left-offset) hycontrol-screen-offset-sensitivity)) (defun hycontrol-frame-at-top-p () - "Return non-nil if selected frame's bottom is at the top of the screen sans `hycontrol-screen-top-offset'." + "Non-nil if selected frame's bottom is at the top of the screen. +Screen top is adjusted based on `hycontrol-screen-top-offset'." (<= (- (nth 1 (hycontrol-frame-edges)) hycontrol-screen-top-offset ;; Under macOS, frames are automatically offset vertically by ;; the height of the global menubar, so account for that. @@ -712,12 +730,14 @@ Under a graphical window system, this is in pixels; otherwise, it is in characte hycontrol-screen-offset-sensitivity)) (defun hycontrol-frame-at-right-p () - "Return non-nil if selected frame's right edge is at the right edge of the screen sans `hycontrol-screen-right-offset'." + "Non-nil if selected frame's right edge is at the right edge of the screen. +Screen right edge is adjusted based on `hycontrol-screen-right-offset'." (<= (- (display-pixel-width) (nth 2 (hycontrol-frame-edges)) hycontrol-screen-right-offset) hycontrol-screen-offset-sensitivity)) (defun hycontrol-frame-at-bottom-p () - "Return non-nil if selected frame's bottom is at the bottom of the screen sans `hycontrol-screen-bottom-offset'." + "Non-nil if selected frame's bottom is at the bottom of the screen. +Screen bottom edge is adjusted based on `hycontrol-screen-bottom-offset'." (<= (- (display-pixel-height) (nth 3 (hycontrol-frame-edges)) hycontrol-screen-bottom-offset ;; Under macOS, frames are automatically offset vertically by ;; the height of the global menubar, so account for that. @@ -727,7 +747,8 @@ Under a graphical window system, this is in pixels; otherwise, it is in characte ;; Frame Zoom Support (defun hycontrol-frame-zoom (zoom-func arg max-msgs) "Zoom default frame face using ZOOM-FUNC and amount ARG (must be 1-9). -MAX-MSGS is a number used only if ZOOM-FUNC is undefined and an error message is logged." +MAX-MSGS is a number used only if ZOOM-FUNC is undefined and an +error message is logged." (if (fboundp zoom-func) (let ((frame-zoom-font-difference arg)) (funcall zoom-func)) @@ -735,8 +756,9 @@ MAX-MSGS is a number used only if ZOOM-FUNC is undefined and an error message is (defun hycontrol-make-frame () - "Create and select a new frame with the same size and selected buffer as the selected frame. -It is offset from the selected frame by `hycontrol-frame-offset' (x . y) pixels." + "Create a new frame with the same size and selected buffer as the selected frame. +The new frame is selected. It is offset from the selected frame +by `hycontrol-frame-offset' (x . y) pixels." (interactive) (select-frame (make-frame (list (cons 'width (frame-width)) (cons 'height (frame-height)) (cons 'left (+ (car hycontrol-frame-offset) (car (frame-position)))) @@ -752,7 +774,7 @@ It is offset from the selected frame by `hycontrol-frame-offset' (x . y) pixels. ('right (set-frame-position nil (+ x pixels) y))))) (defun hycontrol-numeric-keypad (e _arg) - "Move the selected frame to a screen location based on the location of the last pressed numeric keypad key." + "Move frame to screen location based on the last pressed numeric keypad key." (let ((num (if (integerp e) e ;; kp- symbol @@ -831,15 +853,19 @@ multiple of the default frame font width." (error "(HyDebug): Invalid expression in `hycontrol-display-buffer-predicate-list' - %s" err))) (defvar hycontrol--blank-buffer (get-buffer-create "BLANK") - "Blank buffer to display in extra window grid windows after selected buffer list is exhausted.") + "Blank buffer to display in extra window grid windows. +Used after selected buffer list is exhausted.") (defun hycontrol-window-display-buffer (window) - "Given a WINDOW, choose the next appropriate buffer to display from `hycontrol--buffer-list'. + "Given a WINDOW, choose the next appropriate buffer to display. +Uses `hycontrol--buffer-list'. -When `hycontrol--invert-display-buffer-predicates' is non-nil and not 'ignore, -the list of buffers used is further filtered using the functions and sexpressions -in `hycontrol-display-buffer-predicate-list', which by default filters -a frame's buffer-list to just those buffers with attached files. +When `hycontrol--invert-display-buffer-predicates' is non-nil and +not 'ignore, the list of buffers used is further filtered using +the functions and sexpressions in +`hycontrol-display-buffer-predicate-list', which by default +filters a frame's buffer-list to just those buffers with attached +files. Filtering is disabled if a specific list of buffers is sent to the `hycontrol-make-windows-grid' function that calls this." @@ -862,9 +888,10 @@ Filtering is disabled if a specific list of buffers is sent to the (defun hycontrol-window-display-buffer-with-repeats (window) "This is no longer used since Hyperbole V8. Left here for reference. -Given a WINDOW, choose the next appropriate buffer to display therein using `hycontrol-display-buffer-predicate-list'. -Also uses the value of`hycontrol--buffer-list' as the list of -buffers to distribute among the windows." +Given a WINDOW, choose the next appropriate buffer to display +therein using `hycontrol-display-buffer-predicate-list'. Also +uses the value of`hycontrol--buffer-list' as the list of buffers +to distribute among the windows." (let ((buf (car hycontrol--buffer-list-pointer))) (setq hycontrol--buffer-list-pointer (cdr hycontrol--buffer-list-pointer)) (unless buf @@ -898,7 +925,7 @@ buffers to distribute among the windows." (apply #'message msg-args))) (defun hycontrol-user-error (max-msgs &rest err) - "Log MAX-MSGS, adding ERR to the *Messages* buffer log; display ERR for 2 seconds." + "Log MAX-MSGS, adding ERR to *Messages* buffer; display ERR for 2 seconds." (let ((message-log-max max-msgs)) (beep) (apply #'message err) @@ -950,7 +977,8 @@ is set to 1. If it is > `hycontrol-maximum-units', it is set to (keyboard-quit)) (defun hycontrol-quit () - "Globally quit HyControl Frames mode, typically on a press of {q}, always on a press of {Q}. + "Globally quit HyControl Frames mode. +Typically on a press of {q}, always on a press of {Q}. If in a help buffer where {q} is bound to `quit-window', run that instead of quitting HyControl." (interactive) @@ -1017,9 +1045,10 @@ instead of quitting HyControl." (delete-other-frames))) (defun hycontrol-frame-swap-buffers () - "Swap the buffers displayed by each of two visible, most recently used frames and return t. -The selected window in each frame is used. If there are not at least -two visible frames, do nothing and return nil." + "Swap the buffers displayed by each of two visible, most recently used frames. +Return t on success. The selected window in each frame is used. +If there are not at least two visible frames, do nothing and +return nil." (interactive) (let ((frames (filtered-frame-list #'frame-visible-p)) frame2 @@ -1043,7 +1072,7 @@ two visible frames, do nothing and return nil." "(Virtual 7 8 9 Enter a digit to Numeric 4 5 6 move the frame Keypad) 1 2 3 to that quadrant" - "HyControl prompt string for virtual numeric keypad (emulate keypad when not available)") + "Prompt string for virtual numeric keypad (emulate keypad when not available).") (defun hycontrol-virtual-numeric-keypad (arg) (catch 'quit @@ -1055,7 +1084,8 @@ two visible frames, do nothing and return nil." (hycontrol-numeric-keypad (- e ?0) arg)))) (defun hycontrol-frame-to-screen-edges (&optional arg) - "Cycle the selected frame's position clockwise through the middle of edges and corners of the screen; once per call. + "Cycle the selected frame's position clockwise; once per call. +Cycle through the middle of edges and corners of the screen. With an optional ARG of 0, just reset the cycle position to 0." (interactive) (if (and arg (zerop arg)) @@ -1071,7 +1101,8 @@ With an optional ARG of 0, just reset the cycle position to 0." (setq hycontrol--screen-edge-position 0)))) (defun hycontrol-frame-to-bottom () - "Move the selected frame to the bottom of the screen, allowing for hycontrol-screen-*-offsets." + "Move the selected frame to the bottom of the screen. +Allow for hycontrol-screen-*-offsets." (interactive) (hycontrol-set-frame-position nil (car (frame-position)) @@ -1079,12 +1110,14 @@ With an optional ARG of 0, just reset the cycle position to 0." hycontrol-screen-bottom-offset))) (defun hycontrol-frame-to-left () - "Move the selected frame to the left of the screen, allowing for hycontrol-screen-*-offsets." + "Move the selected frame to the left of the screen. +Allow for hycontrol-screen-*-offsets." (interactive) (hycontrol-set-frame-position nil hycontrol-screen-left-offset (cdr (frame-position)))) (defun hycontrol-frame-to-right () - "Move the selected frame to the right of the screen, allowing for hycontrol-screen-*-offsets." + "Move the selected frame to the right of the screen. +Allow for hycontrol-screen-*-offsets." (interactive) (hycontrol-set-frame-position nil (- (display-pixel-width) (hycontrol-frame-width) @@ -1092,8 +1125,10 @@ With an optional ARG of 0, just reset the cycle position to 0." (cdr (frame-position)))) (defun hycontrol-frame-fit-to-screen (&optional frame x-origin y-origin) - "Ensure the selected frame fits within the screen, allowing for hycontrol-screen-*-offsets. -Accepts optional arguments FRAME, X-ORIGIN, and Y-ORIGIN (in pixels) to use when resizing FRAME (defaults to selected frame)." + "Ensure the selected frame fits within the screen. +Allow for hycontrol-screen-*-offsets. Accepts optional arguments +FRAME, X-ORIGIN, and Y-ORIGIN (in pixels) to use when resizing +FRAME (defaults to selected frame)." (let ((max-width (- (display-pixel-width) hycontrol-screen-left-offset hycontrol-screen-right-offset 2)) (max-height (- (display-pixel-height) hycontrol-screen-top-offset hycontrol-screen-bottom-offset 2)) (frame-resize-pixelwise t)) @@ -1121,12 +1156,14 @@ Accepts optional arguments FRAME, X-ORIGIN, and Y-ORIGIN (in pixels) to use when (defun hycontrol-frame-to-top () - "Move the selected frame to the top of the screen, allowing for hycontrol-screen-*-offsets." + "Move the selected frame to the top of the screen. +Allow for hycontrol-screen-*-offsets." (interactive) (hycontrol-set-frame-position nil (car (frame-position)) hycontrol-screen-top-offset)) (defun hycontrol-frame-to-bottom-center () - "Move the selected frame to the center of the bottom of the screen, allowing for hycontrol-screen-*-offsets." + "Move the selected frame to the center of the bottom of the screen. +Allow for hycontrol-screen-*-offsets." (interactive) (hycontrol-set-frame-position nil (round (/ (- (display-pixel-width) (hycontrol-frame-width)) 2)) @@ -1143,13 +1180,15 @@ Accepts optional arguments FRAME, X-ORIGIN, and Y-ORIGIN (in pixels) to use when (defun hycontrol-frame-to-left-center () - "Move the selected frame to the center of the left of the screen, allowing for hycontrol-screen-*-offsets." + "Move the selected frame to the center of the left of the screen. +Allow for hycontrol-screen-*-offsets." (interactive) (hycontrol-set-frame-position nil hycontrol-screen-left-offset (round (/ (- (display-pixel-height) (hycontrol-frame-height)) 2)))) (defun hycontrol-frame-to-right-center () - "Move the selected frame to the center of the right of the screen, allowing for hycontrol-screen-*-offsets." + "Move the selected frame to the center of the right of the screen. +Allow for hycontrol-screen-*-offsets." (interactive) (hycontrol-set-frame-position nil (- (display-pixel-width) (hycontrol-frame-width) @@ -1157,12 +1196,14 @@ Accepts optional arguments FRAME, X-ORIGIN, and Y-ORIGIN (in pixels) to use when (round (/ (- (display-pixel-height) (hycontrol-frame-height)) 2)))) (defun hycontrol-frame-to-top-center () - "Move the selected frame to the center of the top of the screen, allowing for hycontrol-screen-*-offsets." + "Move the selected frame to the center of the top of the screen. +Allow for hycontrol-screen-*-offsets." (interactive) (hycontrol-set-frame-position nil (round (/ (- (display-pixel-width) (hycontrol-frame-width)) 2)) hycontrol-screen-top-offset)) (defun hycontrol-frame-to-bottom-left () - "Move the selected frame to the bottom left of the screen, allowing for hycontrol-screen-*-offsets." + "Move the selected frame to the bottom left of the screen. +Allow for hycontrol-screen-*-offsets." (interactive) (hycontrol-set-frame-position nil hycontrol-screen-left-offset @@ -1170,7 +1211,8 @@ Accepts optional arguments FRAME, X-ORIGIN, and Y-ORIGIN (in pixels) to use when hycontrol-screen-bottom-offset))) (defun hycontrol-frame-to-bottom-right () - "Move the selected frame to the bottom right of the screen, allowing for hycontrol-screen-*-offsets." + "Move the selected frame to the bottom right of the screen. +Allow for hycontrol-screen-*-offsets." (interactive) (hycontrol-set-frame-position nil @@ -1180,12 +1222,14 @@ Accepts optional arguments FRAME, X-ORIGIN, and Y-ORIGIN (in pixels) to use when ;; Frame Resizing (defun hycontrol-frame-to-top-left () - "Move the selected frame to the top left of the screen, allowing for hycontrol-screen-*-offsets." + "Move the selected frame to the top left of the screen. +Allow for hycontrol-screen-*-offsets." (interactive) (hycontrol-set-frame-position nil hycontrol-screen-left-offset hycontrol-screen-top-offset)) (defun hycontrol-frame-to-top-right () - "Move the selected frame to the top right of the screen, allowing for hycontrol-screen-*-offsets." + "Move the selected frame to the top right of the screen. +Allow for hycontrol-screen-*-offsets." (interactive) (hycontrol-set-frame-position nil (- (display-pixel-width) (hycontrol-frame-width) @@ -1210,7 +1254,8 @@ non-integer arguments are ignored and the default value is used." (t (hycontrol-frame-resize-percentage 1)))) (defun hycontrol-frame-resize-arg (arg) - "Inverse result of `hycontrol-frame-resize-percentage' to provide feedback on any argument value adjustment." + "Inverse result of `hycontrol-frame-resize-percentage'. +This is to provide feedback on any argument value adjustment." (pcase arg (0 0) (1 1) @@ -1220,9 +1265,10 @@ non-integer arguments are ignored and the default value is used." (_ 1))) (defun hycontrol-frame-resize-to-bottom (&optional arg) - "Expand the selected frame to the bottom of the screen, allowing for hycontrol-screen-*-offsets. -If already at the bottom, adjust its height to ARG percent of the screen (50% by default -if ARG is 1 or nil) but keep it at the bottom of the screen." + "Expand the selected frame to the bottom of the screen. +Allow for hycontrol-screen-*-offsets. If already at the bottom, +adjust its height to ARG percent of the screen (50% by default if +ARG is 1 or nil) but keep it at the bottom of the screen." (interactive "p") (setq arg (hycontrol-frame-resize-percentage arg)) (let ((frame-resize-pixelwise t)) @@ -1238,9 +1284,10 @@ if ARG is 1 or nil) but keep it at the bottom of the screen." (hycontrol-frame-resize-arg arg)) (defun hycontrol-frame-resize-to-left (&optional arg) - "Expand the selected frame to the left of the screen, allowing for hycontrol-screen-*-offsets. -If already at the left, adjust its width to ARG percent of the screen (50% by default -if ARG is 1 or nil) but keep it at the left of the screen." + "Expand the selected frame to the left of the screen. +Allow for hycontrol-screen-*-offsets. If already at the left, +adjust its width to ARG percent of the screen (50% by default if +ARG is 1 or nil) but keep it at the left of the screen." (interactive "p") (setq arg (hycontrol-frame-resize-percentage arg)) (let ((frame-resize-pixelwise t)) @@ -1256,9 +1303,11 @@ if ARG is 1 or nil) but keep it at the left of the screen." (hycontrol-frame-resize-arg arg)) (defun hycontrol-frame-resize-to-right (&optional arg) - "Expand the selected frame to the right of the screen, allowing for hycontrol-screen-*-offsets. -If already at the right, adjust its width to ARG percent of the screen (50% by default -if ARG is 1 or nil) but keep it at the right of the screen." + "Expand the selected frame to the right of the screen. +Allowing for hycontrol-screen-*-offsets. If already at the +right, adjust its width to ARG percent of the screen (50% by +default if ARG is 1 or nil) but keep it at the right of the +screen." (interactive "p") (setq arg (hycontrol-frame-resize-percentage arg)) (let ((frame-resize-pixelwise t)) @@ -1274,9 +1323,10 @@ if ARG is 1 or nil) but keep it at the right of the screen." (hycontrol-frame-resize-arg arg)) (defun hycontrol-frame-resize-to-top (&optional arg) - "Expand the selected frame to the top of the screen, allowing for hycontrol-screen-*-offsets. -If already at the top, adjust its height to ARG percent of the screen (50% by default -if ARG is 1 or nil) but keep it at the top of the screen." + "Expand the selected frame to the top of the screen. +Allow for hycontrol-screen-*-offsets. If already at the top, +adjust its height to ARG percent of the screen (50% by default if +ARG is 1 or nil) but keep it at the top of the screen." (interactive "p") (setq arg (hycontrol-frame-resize-percentage arg)) (let ((frame-resize-pixelwise t)) @@ -1291,7 +1341,8 @@ if ARG is 1 or nil) but keep it at the top of the screen." (defun hycontrol-frame-minimize-lines () - "Shrink the frame to its approximate smallest number of lines to display all existing windows." + "Shrink frame to its smallest number of lines to display all existing windows. +The smallest noumber is an approximation." (interactive) (let ((l 0)) (save-window-excursion @@ -1393,7 +1444,7 @@ Widths are given in screen percentages by the list ;;;###autoload (defun hycontrol-frame-adjust-widths-full-height () - "Cycle through different common widths adjustments of a frame after fixing its height full-screen. + "Cycle through frame width adjustments after fixing its height full-screen. Widths are given in screen percentages by the list `hycontrol-frame-widths' and typically go from widest to narrowest." (interactive) @@ -1426,7 +1477,7 @@ Heights are given in screen percentages by the list ;;;###autoload (defun hycontrol-frame-adjust-heights-full-width () - "Cycle through different common height adjustments of a frame after fixing its width full-screen. + "Cycle through height adjustments of a frame after fixing its width full-screen. Heights are given in screen percentages by the list `hycontrol-frame-heights' and typically go from tallest to shortest." (interactive) @@ -1462,7 +1513,8 @@ Heights are given in screen percentages by the list ;;; Window Commands (defun hycontrol-invert-mode-line () - "If `hycontrol-invert-mode-line-flag' is non-nil, invert the background and foreground faces of the selected window mode-line." + "Invert the background and foreground faces of the selected window mode-line. +Enabled if `hycontrol-invert-mode-line-flag' is non-nil." (when hycontrol-invert-mode-line-flag (let* ((bg (face-background 'mode-line)) (fg (face-foreground 'mode-line))) @@ -1488,8 +1540,10 @@ Heights are given in screen percentages by the list items)) (defun hycontrol-windows-grid-buffer-list () - "Return either any marked items in Dired, Buffer Menu or IBuffer mode or the existing frame's buffer list. -If selecting buffers by major-mode, then ignore any marked items." + "Return buffer list for grid. +Buffers are either any marked items in Dired, Buffer Menu or +IBuffer mode or the existing frame's buffer list. If selecting +buffers by major-mode, then ignore any marked items." (if (and (boundp 'mode) (symbolp mode)) (buffer-list (selected-frame)) ;; Get the list of marked items if in an item list buffer and @@ -1562,9 +1616,10 @@ argument." (hhist:add hist-elt)))))) ;; Save prior frame configuration for easy return (defun hycontrol-windows-grid-minimum-size (num-buffers) - "Return the minimum integer window grid size to display NUM-BUFFERS. Minimize number of rows rather than columns. -Size is a 2 digit whole number with the first digit number of rows and -the second, number of columns of windows." + "Return the minimum integer window grid size to display NUM-BUFFERS. +Minimize number of rows rather than columns. Size is a 2 digit +whole number with the first digit number of rows and the second, +number of columns of windows." (let* ((num-cols (ceiling (sqrt num-buffers))) (num-rows (1- num-cols)) (grid-size (+ (* num-rows 10) num-cols))) @@ -1590,7 +1645,7 @@ the second, number of columns of windows." ;;;###autoload (defun hycontrol-windows-grid-by-file-pattern (pattern &optional full) - "Display an automatically sized window grid showing files found from glob PATTERN. + "Display an automatically sized window grid with files found from glob PATTERN. Use absolute file paths if called interactively or optional FULL is non-nil." (interactive (list (read-string "Pattern of files to display in windows grid: ") @@ -1601,9 +1656,10 @@ Use absolute file paths if called interactively or optional FULL is non-nil." ;;;###autoload (defun hycontrol-windows-grid-by-major-mode (arg mode) - "Display a grid of windows in the selected frame, sized according to prefix ARG, with buffers of major MODE. -Left digit of ARG is the number of grid rows and the right digit is -the number of grid columns. + "Display a grid of windows in the selected frame with buffers of major MODE. +The grid is sized according to prefix ARG. Left digit of ARG is +the number of grid rows and the right digit is the number of grid +columns. See documentation of `hycontrol-windows-grid' for further details." (interactive @@ -1618,9 +1674,9 @@ See documentation of `hycontrol-windows-grid' for further details." ;;;###autoload (defun hycontrol-windows-grid-repeatedly (&optional arg) - "Repeatedly display different window grid layouts according to prefix ARG prompted for each time. -Left digit of ARG is the number of grid rows and the right digit is -the number of grid columns. + "Repeatedly display different window grid layouts according to prefix ARG. +ARG is prompted for each time. Left digit of ARG is the number +of grid rows and the right digit is the number of grid columns. See documentation of `hycontrol-windows-grid' for further details." (interactive "p") @@ -1736,14 +1792,14 @@ See documentation of `hycontrol-windows-grid' for further details." (delete-other-windows))) (defun hycontrol-window-maximize-lines () - "Grow window to its maximum possible number of lines without removing any windows." + "Grow window to its maximum possible number of lines without removing windows." (interactive) (maximize-window)) (defun hycontrol-window-minimize-lines () - "Shrink window to its smallest possible number of lines to display entire buffer, if possible. -Otherwise or if the window is already displaying all of its lines, shrink it to about one line, -if possible." + "Shrink window to its smallest number of lines to show whole buffer, if possible. +Otherwise or if the window is already displaying all of its +lines, shrink it to about one line, if possible." (interactive) (let ((neg-shrink-amount (- (1+ (count-lines (point-min) (point-max))))) (window-min-height 1)) @@ -1755,9 +1811,10 @@ if possible." (shrink-window (1- (window-height)))))) (defun hycontrol-window-swap-buffers () - "Swap the buffers displayed by each of two windows within the selected frame and return t. -Swap which window is selected so that the current buffer remains the same. -Do nothing and return nil if there are not precisely two windows." + "Swap the buffers displayed in two windows in the selected frame and return t. +Swap which window is selected so that the current buffer remains +the same. Do nothing and return nil if there are not precisely +two windows." (interactive) (let ((windows (window-list nil 'no-mini)) buf1 buf2) @@ -1773,9 +1830,10 @@ Do nothing and return nil if there are not precisely two windows." ;;;###autoload (defun hycontrol-window-to-new-frame () "Create a new frame sized to match the selected window with the same buffer. -If there is only one window in the source frame or if `hycontrol-keep-window-flag' -is non-nil, leave the original window and just clone it into the new frame; -otherwise, delete the original window." +If there is only one window in the source frame or if +`hycontrol-keep-window-flag' is non-nil, leave the original +window and just clone it into the new frame; otherwise, delete +the original window." (interactive) (let ((w (selected-window)) (frame-resize-pixelwise t) @@ -1818,7 +1876,7 @@ otherwise, delete the original window." ;;; Screen Offsets - Set once when this file is loaded; `hycontrol-set-screen-offsets' resets them. (defun hycontrol-display-screen-offsets () - "Display a user minibuffer message listing HyControl's screen edge offsets in pixels." + "Display a minibuffer message listing HyControl's screen edge offsets in pixels." (interactive) (message "Screen pixel offsets are: Left: %d; Top: %d; Right: %d; Bot: %d" hycontrol-screen-left-offset @@ -1827,8 +1885,9 @@ otherwise, delete the original window." hycontrol-screen-bottom-offset)) (defun hycontrol-get-screen-offsets () - "Return the first matching list of screen edge .50%%%offsets from `hycontrol-screen-offset-alist'. -See its documentation for more information." + "Return the first matching list of screen edge .50%%%offsets. +The offsets are from `hycontrol-screen-offset-alist'. See its +documentation for more information." (interactive) (prog1 (catch 'result (let (predicate offsets width height) @@ -1859,8 +1918,9 @@ See its documentation for more information." (if (called-interactively-p 'interactive) (hycontrol-display-screen-offsets)))) (defun hycontrol-set-screen-offsets () - "Set screen edge offsets to the first matching list of offsets from `hycontrol-screen-offset-alist'. -See its documentation for more information." + "Set screen edge offsets to the first matching list of offsets. +Offsets are from `hycontrol-screen-offset-alist'. See its +documentation for more information." (interactive) (let ((offsets (hycontrol-get-screen-offsets))) (setq hycontrol-screen-left-offset (nth 0 offsets)