From 11c46e150707cc87b7733b57f34bc83e4227d31c Mon Sep 17 00:00:00 2001 From: Ken Manheimer Date: Wed, 9 Feb 2011 19:31:18 -0500 Subject: [PATCH] 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. --- lisp/allout.el | 202 +++++++++++++++++++------------------------------ 1 file changed, 77 insertions(+), 125 deletions(-) diff --git a/lisp/allout.el b/lisp/allout.el index 49c2dba322..5d87415a57 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") -- 2.20.1