Synopsis: Change allout user configuration so auto-activation is controlled

solely by customization `allout-auto-activation'.

(allout-auto-activation-helper) (allout-setup): New autoloads implement new
custom set procedure for allout-auto-activation.  Also, explicitly invoke
(allout-setup) after allout-auto-activation is custom-defined, to effect
the settings in emacs sessions besides the few where allout-auto-activation
customization is donea.
(allout-auto-activation): Use allout-auto-activation-helper to :set.
Revise the docstring.
(allout-init): Reduce functionality to just customizing
allout-auto-activation, and mark obsolete.
(allout-mode): Respect string values for allout-auto-activation.  Run
allout-after-copy-or-kill-hook without any args.
(allout-mode) (allout-layout) (allout-default-layout) (outlineify-sticky):
Adjust docstring for new scheme.
(allout-after-copy-or-kill-hook): No arguments - hook implementers should
concentrate on the kill ring.

1 files changed, 77 insertions, 125 deletions

diff --git a/lisp/allout.el b/lisp/allout.el
index 49c2dba322a..5d87415a57f 100644
--- a/lisp/allout.el
+++ b/lisp/allout.el
@@ -62,18 +62,15 @@
 ;; The latest development version and helpful notes are available at
 ;; http://myriadicity.net/Sundry/EmacsAllout .
 ;;
-;; The outline menubar additions provide quick reference to many of
-;; the features, and see the docstring of the variable `allout-init'
-;; for instructions on priming your Emacs session for automatic
-;; activation of allout-mode.
-;;
-;; See the docstring of the variables `allout-layout' and
+;; The outline menubar additions provide quick reference to many of the
+;; features.  See the docstring of the variables `allout-layout' and
 ;; `allout-auto-activation' for details on automatic activation of
-;; `allout-mode' as a minor mode.  (It has changed since allout
-;; 3.x, for those of you that depend on the old method.)
+;; `allout-mode' as a minor mode.  (`allout-init' is deprecated in favor of
+;; a purely customization-based method.)
 ;;
 ;; Note -- the lines beginning with `;;;_' are outline topic headers.
-;;        Just `ESC-x eval-buffer' to give it a whirl.
+;;        Customize `allout-auto-activation' to enable, then revisit this
+;;        buffer to give it a whirl.
 
 ;; ken manheimer (ken dot manheimer at gmail dot com)
 
@@ -271,35 +268,56 @@ See the existing keys for examples."
   :set 'allout-compose-and-institute-keymap
   )
 
+;;;_  > allout-auto-activation-helper (var value)
+;;;###autoload
+(defun allout-auto-activation-helper (var value)
+  "Institute `allout-auto-activation'.
+
+Intended to be used as the `allout-auto-activation' :set function."
+  (set-default var value)
+  (allout-setup))
+;;;_  > allout-setup ()
+;;;###autoload
+(defun allout-setup ()
+  "Do fundamental emacs session for allout auto-activation.
+
+Establishes allout processing as part of visiting a file if
+`allout-auto-activation' is non-nil, or removes it otherwise.
+
+The proper way to use this is through customizing the setting of
+`allout-auto-activation'."
+  (if (not allout-auto-activation)
+      (remove-hook 'find-file-hook 'allout-find-file-hook)
+      (add-hook 'find-file-hook 'allout-find-file-hook)))
 ;;;_  = allout-auto-activation
+;;;###autoload
 (defcustom allout-auto-activation nil
-  "Regulates auto-activation modality of allout outlines -- see `allout-init'.
+  "Configure allout outline mode auto-activation.
 
-Setq-default by `allout-init' to regulate whether or not allout
-outline mode is automatically activated when the buffer-specific
-variable `allout-layout' is non-nil, and whether or not the layout
-dictated by `allout-layout' should be imposed on mode activation.
+Control whether and how allout outline mode is automatically
+activated when files are visited with non-nil buffer-specific
+file variable `allout-layout'.
 
-With value t, auto-mode-activation and auto-layout are enabled.
-\(This also depends on `allout-find-file-hook' being installed in
-`find-file-hook', which is also done by `allout-init'.)
+When allout-auto-activation is \"On\" \(t), allout mode is
+activated in buffers with non-nil `allout-layout', and the
+specified layout is applied.
 
-With value `ask', auto-mode-activation is enabled, and endorsement for
+With value \"ask\", auto-mode-activation is enabled, and endorsement for
 performing auto-layout is asked of the user each time.
 
-With value `activate', only auto-mode-activation is enabled,
-auto-layout is not.
+With value \"activate\", only auto-mode-activation is enabled.
+Auto-layout is not.
 
 With value nil, neither auto-mode-activation nor auto-layout are
-enabled.
-
-See the docstring for `allout-init' for the proper interface to
-this variable."
+enabled, and allout auto-activation processing is removed from
+file visiting activities."
+  :set 'allout-auto-activation-helper
   :type '(choice (const :tag "On" t)
                 (const :tag "Ask about layout" "ask")
                 (const :tag "Mode only" "activate")
                 (const :tag "Off" nil))
   :group 'allout)
+(allout-setup)
 ;;;_  = allout-default-layout
 (defcustom allout-default-layout '(-2 : 0)
   "Default allout outline layout specification.
@@ -311,7 +329,7 @@ layout specifications.
 A list value specifies a default layout for the current buffer,
 to be applied upon activation of `allout-mode'.  Any non-nil
 value will automatically trigger `allout-mode', provided
-`allout-init' has been called to enable this behavior.
+`allout-auto-activation' has been customized to enable it.
 
 The types of elements in the layout specification are:
 
@@ -890,10 +908,10 @@ For details, see `allout-toggle-current-subtree-encryption's docstring."
 (defvar allout-layout nil            ; LEAVE GLOBAL VALUE NIL -- see docstring.
   "Buffer-specific setting for allout layout.
 
-In buffers where this is non-nil (and if `allout-init' has been run, to
-enable this behavior), `allout-mode' will be automatically activated.  The
-layout dictated by the value will be used to set the initial exposure when
-`allout-mode' is activated.
+In buffers where this is non-nil \(and if `allout-auto-activation'
+has been customized to enable this behavior), `allout-mode' will be
+automatically activated.  The layout dictated by the value will be used to
+set the initial exposure when `allout-mode' is activated.
 
 \*You should not setq-default this variable non-nil unless you want every
 visited file to be treated as an allout file.*
@@ -906,9 +924,9 @@ example, the following lines at the bottom of an Emacs Lisp file:
 ;;;End:
 
 dictate activation of `allout-mode' mode when the file is visited
-\(presuming allout-init was already run), followed by the
-equivalent of `(allout-expose-topic 0 : -1 -1 0)'.  (This is
-the layout used for the allout.el source file.)
+\(presuming proper `allout-auto-activation' customization),
+followed by the equivalent of `(allout-expose-topic 0 : -1 -1 0)'.
+\(This is the layout used for the allout.el source file.)
 
 `allout-default-layout' describes the specification format.
 `allout-layout' can additionally have the value `t', in which
@@ -1441,9 +1459,7 @@ This hook might be invoked multiple times by a single command.")
 (defvar allout-after-copy-or-kill-hook nil
   "*Hook that's run after copying outline text.
 
-Functions on the hook should take two arguments:
-
-  START, END -- integers indicating the span containing the copied text.")
+Functions on the hook should not take any arguments.")
 ;;;_   = allout-outside-normal-auto-fill-function
 (defvar allout-outside-normal-auto-fill-function nil
   "Value of normal-auto-fill-function outside of allout mode.
@@ -1621,84 +1637,19 @@ non-nil in a lasting way.")
   "If t, `allout-mode's last deactivation was deliberate.
 So `allout-post-command-business' should not reactivate it...")
 (make-variable-buffer-local 'allout-explicitly-deactivated)
-;;;_  > allout-init (&optional mode)
-(defun allout-init (&optional mode)
-  "Prime `allout-mode' to enable/disable auto-activation, wrt `allout-layout'.
-
-MODE is one of the following symbols:
-
- - nil (or no argument) deactivate auto-activation/layout;
- - `activate', enable auto-activation only;
- - `ask', enable auto-activation, and enable auto-layout but with
-   confirmation for layout operation solicited from user each time;
- - `report', just report and return the current auto-activation state;
- - anything else (eg, t) for auto-activation and auto-layout, without
-   any confirmation check.
-
-Use this function to setup your Emacs session for automatic activation
-of allout outline mode, contingent to the buffer-specific setting of
-the `allout-layout' variable.  (See `allout-layout' and
-`allout-expose-topic' docstrings for more details on auto layout).
-
-`allout-init' works by setting up (or removing) the `allout-mode'
-find-file-hook, and giving `allout-auto-activation' a suitable
-setting.
-
-To prime your Emacs session for full auto-outline operation, include
-the following two lines in your Emacs init file:
-
-\(require 'allout)
-\(allout-init t)"
-
-  (interactive)
-  (if (allout-called-interactively-p)
-      (progn
-        (setq mode
-              (completing-read
-               (concat "Select outline auto setup mode "
-                       "(empty for report, ? for options) ")
-               '(("nil")("full")("activate")("deactivate")
-                 ("ask") ("report") (""))
-               nil
-               t))
-        (if (string= mode "")
-            (setq mode 'report)
-          (setq mode (intern-soft mode)))))
-  (let
-      ;; convenience aliases, for consistent ref to respective vars:
-      ((hook 'allout-find-file-hook)
-       (find-file-hook-var-name (if (boundp 'find-file-hook)
-                                    'find-file-hook
-                                  'find-file-hooks))
-       (curr-mode 'allout-auto-activation))
-
-    (cond ((not mode)
-           (set find-file-hook-var-name
-                (delq hook (symbol-value find-file-hook-var-name)))
-           (if (allout-called-interactively-p)
-               (message "Allout outline mode auto-activation inhibited.")))
-          ((eq mode 'report)
-           (if (not (memq hook (symbol-value find-file-hook-var-name)))
-               (allout-init nil)
-             ;; Just punt and use the reports from each of the modes:
-             (allout-init (symbol-value curr-mode))))
-          (t (add-hook find-file-hook-var-name hook)
-             (set curr-mode             ; `set', not `setq'!
-                  (cond ((eq mode 'activate)
-                         (message
-                          "Outline mode auto-activation enabled.")
-                         'activate)
-                        ((eq mode 'report)
-                         ;; Return the current mode setting:
-                         (allout-init mode))
-                        ((eq mode 'ask)
-                         (message
-                          (concat "Outline mode auto-activation and "
-                                  "-layout (upon confirmation) enabled."))
-                         'ask)
-                        ((message
-                          "Outline mode auto-activation and -layout enabled.")
-                         'full)))))))
+;;;_  > allout-init (mode)
+(defun allout-init (mode)
+  "DEPRECATED - configure allout activation by customizing
+`allout-auto-activation'.  This function remains around, limited
+from what it did before, for backwards compatability.
+
+MODE is the activation mode - see `allout-auto-activation' for
+valid values."
+
+  (custom-set-variables (list 'allout-auto-activation (format "%s" mode)))
+  (format "%s" mode))
+(make-obsolete 'allout-init
+               "customize 'allout-auto-activation' instead." "23.3")
 ;;;_  > allout-setup-menubar ()
 (defun allout-setup-menubar ()
   "Populate the current buffer's menubar with `allout-mode' stuff."
@@ -1764,9 +1715,8 @@ and many other features.
 Below is a description of the key bindings, and then description
 of special `allout-mode' features and terminology.  See also the
 outline menubar additions for quick reference to many of the
-features, and see the docstring of the function `allout-init' for
-instructions on priming your emacs session for automatic
-activation of `allout-mode'.
+features.  Customize `allout-auto-activation' to prepare your
+emacs session for automatic activation of `allout-mode'.
 
 The bindings are those listed in `allout-prefixed-keybindings'
 and `allout-unprefixed-keybindings'.  We recommend customizing
@@ -1850,7 +1800,8 @@ M-x outlineify-sticky       Activate outline mode for current buffer,
                             Like above 'copy-exposed', but convert topic
                             prefixes to section.subsection... numeric
                             format.
-\\[eval-expression] (allout-init t) Setup Emacs session for outline mode
+\\[customize-variable] allout-auto-activation
+                            Prepare Emacs session for allout outline mode
                             auto-activation.
 
                   Topic Encryption
@@ -2092,8 +2043,8 @@ OPEN:	A TOPIC that is not CLOSED, though its OFFSPRING or BODY may be."
       (when (and allout-layout
                  allout-auto-activation
                  use-layout
-                 (and (not (eq allout-auto-activation 'activate))
-                      (if (eq allout-auto-activation 'ask)
+                 (and (not (string= allout-auto-activation "activate"))
+                      (if (string= allout-auto-activation "ask")
                           (if (y-or-n-p (format "Expose %s with layout '%s'? "
                                                 (buffer-name)
                                                 use-layout))
@@ -3448,7 +3399,7 @@ Returns the qualifying command, if any, else nil."
 (defun allout-find-file-hook ()
   "Activate `allout-mode' on non-nil `allout-auto-activation', `allout-layout'.
 
-See `allout-init' for setup instructions."
+See `allout-auto-activation' for setup instructions."
   (if (and allout-auto-activation
            (not (allout-mode-p))
            allout-layout)
@@ -4394,7 +4345,7 @@ subtopics into siblings of the item."
           (if (and (not beg-hidden) (not end-hidden))
               (allout-unprotected (kill-line arg))
             (kill-line arg))
-        (run-hook-with-args 'allout-after-copy-or-kill-hook beg end)
+        (run-hooks 'allout-after-copy-or-kill-hook)
         (allout-deannotate-hidden beg end)
 
         (if allout-numbered-bullet
@@ -4446,7 +4397,7 @@ Topic exposure is marked with text-properties, to be used by
     (unwind-protect                     ; for possible barf-if-buffer-read-only.
         (allout-unprotected (kill-region beg end))
       (allout-deannotate-hidden beg end)
-      (run-hook-with-args 'allout-after-copy-or-kill-hook beg end)
+      (run-hooks 'allout-after-copy-or-kill-hook)
 
       (save-excursion
         (allout-renumber-to-depth depth))
@@ -4503,7 +4454,8 @@ Topic exposure is marked with text-properties, to be used by
   (allout-unprotected
    (let ((inhibit-read-only t)
          (buffer-undo-list t))
-     (remove-text-properties begin end '(allout-was-hidden t)))))
+     (remove-text-properties begin (min end (point-max))
+                             '(allout-was-hidden t)))))
 ;;;_    > allout-hide-by-annotation (begin end)
 (defun allout-hide-by-annotation (begin end)
   "Translate text properties indicating exposure status into actual exposure."
@@ -6312,8 +6264,8 @@ save.  See `allout-encrypt-unencrypted-on-saves' for more info."
 (defun outlineify-sticky (&optional arg)
   "Activate outline mode and establish file var so it is started subsequently.
 
-See doc-string for `allout-layout' and `allout-init' for details on
-setup for auto-startup."
+See `allout-layout' and customization of `allout-auto-activation'
+for details on preparing emacs for automatic allout activation."
 
   (interactive "P")