branch: externals/logos
commit 6fbba45fa0757341d4f44d90b9962255ad79c5fd
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Rename logos-focus-mode-hook for correctness
The 'logos-focus-mode-extra-functions' has the unfortunate connotation
of being an irregular hook, i.e. one that is called with arguments.
Whereas this one is a regular hook that passes no arguments to the
functions it calls.
Quoting from the Emacs Lisp Reference Manual:
If the hook variable’s name does not end with ‘-hook’, that indicates
it is probably an “abnormal hook”. These differ from normal hooks in
two ways: they can be called with one or more arguments, and their
return values can be used in some way. The hook’s documentation says
how the functions are called and how their return values are used. Any
functions added to an abnormal hook must follow the hook’s calling
convention. By convention, abnormal hook names end in ‘-functions’.
To read the manual, evaluate:
(info "(elisp) Hooks")
---
README.org | 37 ++++++++++++++++++++-----------------
logos.el | 19 ++++++++++++-------
2 files changed, 32 insertions(+), 24 deletions(-)
diff --git a/README.org b/README.org
index 417eed974b..7f4c89d578 100644
--- a/README.org
+++ b/README.org
@@ -244,8 +244,8 @@ changes out-of-the-box
([[#h:2bb57369-352a-43bf-afe3-0bed2fcc7359][Extra tweaks]
logos-scroll-lock nil
logos-olivetti nil)
-;; Also check this manual for `logos-focus-mode-extra-functions'. It is
-;; a hook that lets you extend `logos-focus-mode'.
+;; Also check this manual for `logos-focus-mode-hook'. It lets you
+;; extend `logos-focus-mode'.
(let ((map global-map))
(define-key map [remap narrow-to-region] #'logos-narrow-dwim)
@@ -472,19 +472,23 @@ end result can look like this:
(org-mode . ,(format "\\(^\\*\\{1,3\\} +\\|^-\\{5\\}$\\|%s\\)"
logos--page-delimiter))))
#+end_src
-** Leverage logos-focus-mode-extra-functions
+** Leverage logos-focus-mode-hook
:PROPERTIES:
:CUSTOM_ID: h:a2540f2f-1159-4e5c-a486-e1f2cb63fee8
:END:
#+cindex: User-level extensions to logos-focus-mode
-#+vindex: logos-focus-mode-extra-functions
-The ~logos-focus-mode-extra-functions~ is a normal hook that runs when
-~logos-focus-mode~ is enabled. Each function is run without an argument
-and looks like those in =logos.el=. An example that sets a variable is
-~logos--buffer-read-only~; one that sets a mode is ~logos--scroll-lock~;
-another that sets the mode of an external package is ~logos--olivetti~;
-while ~logos--hide-fringe~ provides yet another useful sample.
+[ ~logos-focus-mode-hook~ replaces ~logos-focus-mode-extra-functions~
+ as part of {{{development-version}}}. ]
+
+#+vindex: logos-focus-mode-hook
+The ~logos-focus-mode-hook~ is a normal hook that runs when
+~logos-focus-mode~ is enabled. Each function is called without an
+argument and looks like those in =logos.el=. An example that sets a
+variable is ~logos--buffer-read-only~; one that sets a mode is
+~logos--scroll-lock~; another that sets the mode of an external
+package is ~logos--olivetti~; while ~logos--hide-fringe~ provides yet
+another useful sample.
If a function cannot be like the aforementioned though still needs to
set its state both when ~logos-focus-mode~ is enabled and disabled, then
@@ -495,9 +499,8 @@ use the ~logos-focus-mode-hook~ instead.
:CUSTOM_ID: h:ef719925-8d0b-479a-a87e-32b727578bfc
:END:
-Here is a snippet that relies on ~logos-focus-mode-extra-functions~ to
-extend the functionality of ~logos-focus-mode~ at the user level
-([[#h:a2540f2f-1159-4e5c-a486-e1f2cb63fee8][Leverage
logos-focus-mode-extra-functions]]).
+Here is a snippet that relies on ~logos-focus-mode-hook~ to extend the
+functionality of ~logos-focus-mode~ at the user level
([[#h:a2540f2f-1159-4e5c-a486-e1f2cb63fee8][Leverage logos-focus-mode-hook]]).
#+begin_src emacs-lisp
(defvar my-logos-org-indent nil
@@ -511,7 +514,7 @@ extend the functionality of ~logos-focus-mode~ at the user
level
;; `logos--mode' function takes care of the technicalities.
(logos--mode 'org-indent-mode -1)))
-(add-hook 'logos-focus-mode-extra-functions #'my-logos-org-indent)
+(add-hook 'logos-focus-mode-hook #'my-logos-org-indent)
#+end_src
The ~my-logos-org-indent~ variable lets the user opt in and out of this
@@ -526,7 +529,7 @@ not needed, the following will suffice:
;; `logos--mode' function takes care of the technicalities.
(logos--mode 'org-indent-mode -1))
-(add-hook 'logos-focus-mode-extra-functions #'my-logos-org-indent)
+(add-hook 'logos-focus-mode-hook #'my-logos-org-indent)
#+end_src
*** Disable menu-bar and tool-bar
@@ -543,13 +546,13 @@ to disable the ~menu-bar-mode~ and ~tool-bar-mode~ when
activating the
(defun my-logos-hide-menu-bar ()
(logos--mode 'menu-bar-mode -1))
-(add-hook 'logos-focus-mode-extra-functions #'my-logos-hide-menu-bar)
+(add-hook 'logos-focus-mode-hook #'my-logos-hide-menu-bar)
;; Assuming the `tool-bar-mode' is enabled by default...
(defun my-logos-hide-tool-bar ()
(logos--mode 'tool-bar-mode -1))
-(add-hook 'logos-focus-mode-extra-functions #'my-logos-hide-tool-bar)
+(add-hook 'logos-focus-mode-hook #'my-logos-hide-tool-bar)
#+end_src
If those modes are already disabled, the following have no effect.
diff --git a/logos.el b/logos.el
index 7e9535674a..d9ab893980 100644
--- a/logos.el
+++ b/logos.el
@@ -199,14 +199,19 @@ This is only relevant when `logos-focus-mode' is enabled."
:package-version '(logos . "0.4.0")
:local t)
-(defcustom logos-focus-mode-extra-functions nil
+(define-obsolete-variable-alias
+ 'logos-focus-mode-extra-functions
+ 'logos-focus-mode-hook
+ "1.1.0")
+
+(defcustom logos-focus-mode-hook nil
"List of functions to execute when `logos-focus-mode' is enabled.
-Each function is run without an argument. An example that sets a
-variable is `logos--buffer-read-only'; one that sets a mode is
-`logos--scroll-lock'; another that sets the mode of an external
-package is `logos--olivetti'; while `logos--hide-fringe' provides
-yet another useful sample.
+Each function is called without an argument. An example that
+sets a variable is `logos--buffer-read-only'; one that sets a
+mode is `logos--scroll-lock'; another that sets the mode of an
+external package is `logos--olivetti'; while `logos--hide-fringe'
+provides yet another useful sample.
Consult the Logos manual for concrete do-it-yourself examples.
@@ -444,7 +449,7 @@ options: `logos-scroll-lock', `logos-variable-pitch',
(setq logos--restore nil)
(when logos-focus-mode
(logos--setup)
- (run-hooks 'logos-focus-mode-extra-functions)))
+ (run-hooks 'logos-focus-mode-hook)))
(defun logos--setup ()
"Set up aesthetics for presentation."
