branch: externals/lin
commit 0e2dd40062b33ef5cc64df9d1e153560d2885565
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Improve the minor-mode setup; add lin-global-mode
---
README.org | 80 +++++++++++++++++++++++++-------------------
lin.el | 110 ++++++++++++++++++++++++++++---------------------------------
2 files changed, 96 insertions(+), 94 deletions(-)
diff --git a/README.org b/README.org
index d2de39703b..d992d71be9 100644
--- a/README.org
+++ b/README.org
@@ -80,15 +80,12 @@ more of a reminder of the point's location on the vertical
axis.
#+findex: lin-mode
#+vindex: lin-mode-hooks
-#+findex: lin-setup
-~lin-mode~ enables ~hl-line-mode~ by adding it to every hook specified
-in the user option ~lin-mode-hooks~. Users are advised to configure
-that variable with ~customize-set-variable~, or the Custom UI, or
-equivalent as it has a function which automatically sets up Lin. Those
-who prefer to set values with ~setq~ must handle the process manually,
-by using the ~lin-setup~ function.
-
#+vindex: lin-face
+~lin-mode~ enables ~hl-line-mode~ in the current buffer and remaps the
+appropriate face to the ~lin-face~. The ~lin-global-mode~ follows the
+same principle, though it applies to all hooks specified in the user
+option ~lin-mode-hooks~.
+
#+vindex: lin-blue
#+vindex: lin-red
#+vindex: lin-green
@@ -104,7 +101,7 @@ by using the ~lin-setup~ function.
#+vindex: lin-magenta-override-fg
#+vindex: lin-cyan-override-fg
#+vindex: lin-mac-override-fg
-Users can selected their preferred style by customizing the user option
+Users can select their preferred style by customizing the user option
~lin-face~. Options include the faces ~lin-red~, ~lin-green~,
~lin-yellow~, ~lin-blue~ (default), ~lin-magenta~, ~lin-cyan~,
~lin-mac~, ~lin-red-override-fg~, ~lin-green-override-fg~,
@@ -119,13 +116,24 @@ the others only specify a background attribute.
:PROPERTIES:
:CUSTOM_ID: h:7b68abd3-a854-4b72-b704-05ca013dfa7f
:END:
-#+cindex: Install Lin
+#+cindex: Installation instructions
+
+** COMMENT GNU ELPA package
+:PROPERTIES:
+:CUSTOM_ID: h:9379f7d7-9f78-40b8-8d30-cceb462cd41f
+:END:
-LIN is not in any package archive for the time being, though I plan to
-submit it to GNU ELPA (as such, any non-trivial patches require
-copyright assignment to the Free Software Foundation). Users can rely
-on =straight.el=, =quelpa=, or equivalent to fetch the source. Below are
-the essentials for those who prefer the manual method.
+The package is available as =lin=. Simply do:
+
+: M-x package-refresh-contents
+: M-x package-install
+
+And search for it.
+
+** Manual installation
+:PROPERTIES:
+:CUSTOM_ID: h:494b6abd-e3d4-4622-b428-272eae0c7779
+:END:
Assuming your Emacs files are found in =~/.emacs.d/=, execute the
following commands in a shell prompt:
@@ -139,7 +147,7 @@ mkdir manual-packages
# Go to the new directory
cd manual-packages
-# Clone this repo and name it "lin"
+# Clone this repo, naming it "lin"
git clone https://gitlab.com/protesilaos/lin.git lin
#+end_src
@@ -163,24 +171,28 @@ Everything is in place to set up the package.
(setq lin-face 'lin-blue) ; check doc string for alternative styles
-(lin-setup) ; Either run this or change `lin-mode-hooks'
-
-(customize-set-variable
- 'lin-mode-hooks ; do not use `setq' with this; `customize-set-variable' runs
`lin-setup' automatically
- '(dired-mode-hook
- elfeed-search-mode-hook
- git-rebase-mode-hook
- ibuffer-mode-hook
- ilist-mode-hook
- ledger-report-mode-hook
- log-view-mode-hook
- magit-log-mode-hook
- mu4e-headers-mode
- notmuch-search-mode-hook
- notmuch-tree-mode-hook
- occur-mode-hook
- org-agenda-mode-hook
- tabulated-list-mode-hook))
+;; You can use this to live update the face:
+;;
+;; (customize-set-variable 'lin-face 'lin-green)
+
+(setq lin-mode-hooks
+ '(bongo-mode-hook
+ dired-mode-hook
+ elfeed-search-mode-hook
+ git-rebase-mode-hook
+ ibuffer-mode-hook
+ ilist-mode-hook
+ ledger-report-mode-hook
+ log-view-mode-hook
+ magit-log-mode-hook
+ mu4e-headers-mode
+ notmuch-search-mode-hook
+ notmuch-tree-mode-hook
+ occur-mode-hook
+ org-agenda-mode-hook
+ tabulated-list-mode-hook))
+
+(lin-global-mode 1)
#+end_src
* Acknowledgements
diff --git a/lin.el b/lin.el
index 94e1ad3f45..9d21048ceb 100644
--- a/lin.el
+++ b/lin.el
@@ -41,15 +41,13 @@
;; highlight is more of a reminder of the point's location on the
;; vertical axis.
;;
-;; `lin-mode' enables `hl-line-mode' by adding it to every hook
-;; specified in the user option `lin-mode-hooks'. Users are advised to
-;; configure that variable with `customize-set-variable', or the Custom
-;; UI, or equivalent as it has a function which automatically sets up
-;; Lin. Those who prefer to set values with `setq' must handle the
-;; process manually, by using the `lin-setup' function.
+;; `lin-mode' enables `hl-line-mode' in the current buffer and remaps
+;; the appropriate face to the `lin-face'. The `lin-global-mode'
+;; follows the same principle, though it applies to all hooks specified
+;; in the user option `lin-mode-hooks'.
;;
-;; Users can selected their preferred style by customizing the user
-;; option `lin-face'. Options include the faces `lin-red', `lin-green',
+;; Users can select their preferred style by customizing the user option
+;; `lin-face'. Options include the faces `lin-red', `lin-green',
;; `lin-yellow', `lin-blue' (default), `lin-magenta', `lin-cyan',
;; `lin-mac', `lin-red-override-fg', `lin-green-override-fg',
;; `lin-yellow-override-fg', `lin-blue-override-fg',
@@ -59,31 +57,6 @@
;; set a foreground value which replaces that of the underlying text.
;; Whereas the others only specify a background attribute.
;;
-;; Sample configuration:
-;;
-;; (require 'lin)
-;;
-;; (setq lin-face 'lin-blue)
-;;
-;; (lin-setup)
-;;
-;; (customize-set-variable
-;; 'lin-mode-hooks
-;; '(dired-mode-hook
-;; elfeed-search-mode-hook
-;; git-rebase-mode-hook
-;; ibuffer-mode-hook
-;; ilist-mode-hook
-;; ledger-report-mode-hook
-;; log-view-mode-hook
-;; magit-log-mode-hook
-;; mu4e-headers-mode
-;; notmuch-search-mode-hook
-;; notmuch-tree-mode-hook
-;; occur-mode-hook
-;; org-agenda-mode-hook
-;; tabulated-list-mode-hook))
-;;
;; Consult the manual for further details. Or visit the documentation's
;; web page: <https://protesilaos.com/emacs/lin>.
@@ -114,19 +87,13 @@
occur-mode-hook
org-agenda-mode-hook
tabulated-list-mode-hook)
- "List of hooks that should enable `lin-mode'.
+ "List of hooks that should enable Lin.
-When Lin is set up, it activates `hl-line-mode' and remaps its
-face to `lin-face'. This makes it possible to distinguish
-between the two use-cases of permanent line highlighting: (i)
-gentle reminder of where the point is while editing, (ii) current
-selection.
-
-Set this user option with `customize-set-variable', the Custom
-UI, or equivalent. It has a custom setter function which
-automatically sets things up when configured that way. Users who
-prefer to use `setq' must run `lin-setup' manually. Consult its
-doc string."
+When Lin is set up with either `lin-mode' or `lin-global-mode',
+it activates `hl-line-mode' and remaps its face to `lin-face'.
+This makes it possible to distinguish between the two use-cases
+of permanent line highlighting: (i) gentle reminder of where the
+point is while editing, (ii) current selection."
:type '(repeat variable)
:initialize #'custom-initialize-default
:set (lambda (symbol value)
@@ -148,10 +115,9 @@ Users can select one among `lin-red', `lin-green',
`lin-yellow',
background attribute.
Set this user option with `customize-set-variable', the Custom
-UI, or equivalent. It has a custom setter function which
-automatically sets things up when configured that way. Users who
-prefer to use `setq' must run `lin-restart-mode-in-buffers'
-manually. Consult its doc string."
+UI, or equivalent. It has a custom setter function which live
+updates the face. Users who prefer to use `setq' must run
+`lin-enable-mode-in-buffers' manually. Consult its doc string."
:type '(radio (face :tag "Red style" lin-red)
(face :tag "Green style" lin-green)
(face :tag "Yellow style" lin-yellow)
@@ -170,7 +136,7 @@ manually. Consult its doc string."
:initialize #'custom-initialize-default
:set (lambda (symbol value)
(set-default symbol value)
- (lin-restart-mode-in-buffers))
+ (lin-enable-mode-in-buffers))
:group 'lin)
;;;; Faces
@@ -327,14 +293,10 @@ manually. Consult its doc string."
(t
'hl-line)))
-(defvar lin-lighter " -L-"
- "Mode line lighter for `lin-mode'.")
-
(define-minor-mode lin-mode
"Enable `hl-line-mode' and remap its face to `lin-face'."
:global nil
:init-value nil
- :lighter lin-lighter
(if lin-mode
(progn
(setq lin--cookie
@@ -343,6 +305,18 @@ manually. Consult its doc string."
(face-remap-remove-relative lin--cookie)
(hl-line-mode -1)))
+;;;###autoload
+(define-minor-mode lin-global-mode
+ "Like `lin-mode' but sets things up for all `lin-mode-hooks'."
+ :global t
+ :init-value nil
+ (if lin-global-mode
+ (progn
+ (lin-setup)
+ (lin-enable-mode-in-buffers))
+ (lin-setup :reverse)
+ (lin-disable-mode-in-buffers)))
+
(defun lin-setup (&optional reverse)
"Set up Lin for select mode hooks.
@@ -356,16 +330,32 @@ With optional non-nil REVERSE argument, remove those
hooks."
(dolist (hook lin-mode-hooks)
(add-hook hook #'lin-mode))))
-(defun lin--mode-restart (buffer)
- "Restart `lin-mode' if already enabled in BUFFER."
+(defun lin--mode-enable (buffer)
+ "Enable `lin-mode' in BUFFER if appropriate."
(with-current-buffer buffer
- (when lin-mode
+ (when (or lin-mode
+ (memq (intern (format "%s-hook" major-mode)) lin-mode-hooks))
(lin-mode 1))))
-(defun lin-restart-mode-in-buffers ()
+(defun lin--mode-disable (buffer)
+ "Disable `lin-mode' if already enabled in BUFFER."
+ (with-current-buffer buffer
+ (when lin-mode
+ (lin-mode -1))))
+
+(defun lin-enable-mode-in-buffers ()
+ "Restart `lin-mode' if already enabled in any buffer.
+Do so by checking the `buffer-list'."
+ (mapc #'lin--mode-enable (buffer-list)))
+
+(define-obsolete-function-alias
+ 'lin-restart-mode-in-buffers
+ 'lin-enable-mode-in-buffers "0.3.0")
+
+(defun lin-disable-mode-in-buffers ()
"Restart `lin-mode' if already enabled in any buffer.
-This checks the `buffer-list'."
- (mapc #'lin--mode-restart (buffer-list)))
+Do so by checking the `buffer-list'."
+ (mapc #'lin--mode-disable (buffer-list)))
(provide 'lin)
