[nongnu] elpa/devil dd29681fe0 3/4: Add option to set devil-mode in all buffers

[ELPA Syncer]

branch: elpa/devil
commit dd29681fe07f37c4acbff32a5767bddcbf3b5b80
Author: Morgan Willcock <morgan@ice9.digital>
Commit: Morgan Willcock <morgan@ice9.digital>

    Add option to set devil-mode in all buffers
    
    This changes introduces a customisable variable named
    `devil-global-sets-buffer-default` which indicates that enabling the
    global minor-mode will also modify the default value of devil-mode.
    By doing so, Devil will now be active in all buffers by default, even
    for buffers which have not run hooks which could a apply a minor mode.
    
    This fixes the problem of being defaulted into or switching into
    buffers where Devil is not active, and finding that Devil key
    sequences are not working.
    
    The documentation which has been added emphasises that the use-case for
    the new variable is limited and it is much safer to deal with
    problematic buffers directly if the user actually notices a problem.
---
 CHANGES.org |  3 +++
 MANUAL.org  | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 devil.el    | 24 +++++++++++++++++++++++-
 3 files changed, 78 insertions(+), 1 deletion(-)

diff --git a/CHANGES.org b/CHANGES.org
index 49439c498a..f364ef9c82 100644
--- a/CHANGES.org
+++ b/CHANGES.org
@@ -16,6 +16,9 @@
 - Repeatable key sequence group for =, x ^= and =, x {= and =, x }=.
 - Repeatable key sequences =, a= and =, e= added to group for =, p=.
 - Repeatable key sequences =, m a= and =, m e= added to group for =, m b=.
+- Customisable variable =devil-global-sets-buffer-default= that, when
+  set to =t=, makes enabling =global-devil-mode= also enable Devil in
+  all new buffers.
 
 *** Changed
 
diff --git a/MANUAL.org b/MANUAL.org
index 023f7d7a87..d3be420f08 100644
--- a/MANUAL.org
+++ b/MANUAL.org
@@ -510,6 +510,48 @@ a text buffer like this, although we can type =, x , f= to 
launch the
 minibuffer.  Further the special keymaps described in the previous
 section work only when Devil is enabled globally.
 
+** Mode as a buffer default
+:PROPERTIES:
+:CUSTOM_ID: buffer-default
+:END:
+While enabling =global-devil-mode= is typically enough for using Devil
+in every buffer the user encounters, buffer creation which bypasses
+the traditional setup hooks will not have the mode enabled by default.
+The most likely place to encounter this problem is with the default
+Emacs startup screen, which is created after the user's init file has
+been processed but does not run any hooks which will enable Devil.
+
+To solve this particular problem it is recommended to either customise
+the startup screen to one which does run the required hooks, or to
+advise the =display-startup-screen= function to enable Devil in the
+buffer once created.  Here is an example of enabling
+=global-devil-mode= and ensuring it is activated in the default Emacs
+startup screen.
+
+#+begin_src elisp
+  (require 'devil)
+  (global-devil-mode)
+  (advice-add 'display-startup-screen
+              :after (lambda (&optional _) (devil-mode 1)))
+#+end_src
+
+This solves the problem most likely to be encountered.  But what if
+you do genuinely need Devil active in *every* buffer?  When
+=devil-global-sets-buffer-default= is set to =t= and
+=global-minor-mode= is called, Devil will be enabled in all new
+buffers by default.  Enabling this functionality may seem appealing,
+but consider that not all buffers are intended to be interacted with,
+and the decision to opt-out of hooks which could apply a minor-mode is
+likely to have been intentional.  Even though it is not recommended,
+the following example demonstrates how to have Devil active in all
+buffers by default.
+
+#+begin_src elisp
+  (require 'devil)
+  (setq devil-global-sets-buffer-default t)
+  (global-devil-mode)
+#+end_src
+
 ** Custom Appearance
 :PROPERTIES:
 :CUSTOM_ID: custom-appearance
@@ -967,6 +1009,16 @@ and preferences.
     [[*Comparison with God Mode]] for more details on the differences
     between the two modes.
 
+05. I've called the function =global-devil-mode= in my config file,
+    but when Emacs opens Devil does not seem to active.  Why isn't it
+    working?
+
+    The most likely issue is that the first buffer shown is the
+    default Emacs startup screen, which is created without running any
+    hooks which would give Devil the opportunity to be applied.  See
+    the section [[*Mode as a buffer default]] for further details and
+    possible solutions.
+
 * Conclusion
 :PROPERTIES:
 :CUSTOM_ID: conclusion
diff --git a/devil.el b/devil.el
index 58c73c530f..f8d8fc9e95 100644
--- a/devil.el
+++ b/devil.el
@@ -227,6 +227,26 @@ Format control sequences supported by `devil-format' may 
be used
 in the format control string."
   :type 'string)
 
+(defcustom devil-global-sets-buffer-default nil
+  "Non-nil iff `global-devil-mode' modifies new buffer defaults.
+
+When non-nil and `global-devil-mode' is enabled, `devil-mode'
+will be enabled in all new buffers without relying on the
+standard global minor-mode hooks.
+
+While this solves issues with `devil-mode' not being active in
+buffers which have not called the hooks where a minor-mode could
+be applied, the decision to bypass these hooks is likely to have
+been intentional.  It is not recommended to enable this option
+unless you are absolutely sure of the consequences.
+
+To work around the most common issue, where `global-devil-mode'
+is enabled during start-up but `devil-mode' is not enabled in the
+default Emacs startup screen, a safer solution is to advise the
+function which creates the startup screen to enable the mode
+locally."
+  :type 'boolean)
+
 
 ;;; Minor Mode Definition ============================================
 
@@ -239,7 +259,9 @@ in the format control string."
 ;;;###autoload
 (define-globalized-minor-mode
   global-devil-mode devil-mode devil--on
-  (if global-devil-mode (devil--add-extra-keys) (devil--remove-extra-keys)))
+  (if global-devil-mode (devil--add-extra-keys) (devil--remove-extra-keys))
+  (when devil-global-sets-buffer-default
+    (setq-default devil-mode global-devil-mode)))
 
 (defun devil--on ()
   "Turn Devil mode on."