;;; allout.el --- extensive outline mode for use alone and with other modes
-;; Copyright (C) 1992, 1993, 1994, 2001, 2002, 2003, 2004, 2005, 2006,
-;; 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
+;; Copyright (C) 1992-1994, 2001-2011 Free Software Foundation, Inc.
;; Author: Ken Manheimer <ken dot manheimer at gmail dot com>
;; Maintainer: Ken Manheimer <ken dot manheimer at gmail dot com>
;; Created: Dec 1991 -- first release to usenet
;; Version: 2.3
-;; Keywords: outlines wp languages
+;; Keywords: outlines, wp, languages, PGP, GnuPG
;; Website: http://myriadicity.net/Sundry/EmacsAllout
;; This file is part of GNU Emacs.
;; emacs local file variables need to be enabled when the
;; file was visited -- see `enable-local-variables'.)
;; - Configurable per-file initial exposure settings
-;; - Symmetric-key and key-pair topic encryption, plus symmetric passphrase
-;; mnemonic support, with verification against an established passphrase
-;; (using a stashed encrypted dummy string) and user-supplied hint
-;; maintenance. Encryption is via the Emacs 'epg' library. See
-;; allout-toggle-current-subtree-encryption docstring.
+;; - Symmetric-key and key-pair topic encryption. Encryption is via the
+;; Emacs 'epg' library. See allout-toggle-current-subtree-encryption
+;; docstring.
;; - Automatic topic-number maintenance
;; - "Hot-spot" operation, for single-keystroke maneuvering and
;; exposure control (see the allout-mode docstring)
;; See the `allout-mode' function's docstring for an introduction to the
;; mode.
;;
-;; The latest development version and helpful notes are available at
-;; http://myriadicity.net/Sundry/EmacsAllout .
+;; Directions to 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)
;;; Code:
-;;;_* Dependency autoloads
+;;;_* Dependency loads
(require 'overlay)
(eval-when-compile
;; Most of the requires here are for stuff covered by autoloads, which
;;;_ > defgroup allout, allout-keybindings
(defgroup allout nil
- "Extensive outline mode for use alone and with other modes."
+ "Extensive outline minor-mode, for use stand-alone and with other modes.
+
+See Allout Auto Activation for automatic activation."
:prefix "allout-"
:group 'outlines)
(defgroup allout-keybindings nil
;; used in minor-mode-map-alist to indirect to the actual
;; allout-mode-map-var value, which can be adjusted and reassigned.
+ ;; allout-mode-map-value for keymap reference in various places:
(setq allout-mode-map-value map)
- ;; The defalias reexecution is necessary when allout-mode-map-value is
- ;; changing from nil, and it doesn't hurt to do it every time, so:
- (defalias 'allout-mode-map allout-mode-map-value))
+ ;; the function value keymap of allout-mode-map is used in
+ ;; minor-mode-map-alist - update it:
+ (fset allout-mode-map allout-mode-map-value))
;;;_ * intialize the mode map:
;; ensure that allout-mode-map has some setting even if allout-mode hasn't
;; been invoked:
("[(control ?a)]" allout-beginning-of-current-entry)
("[(control ?e)]" allout-end-of-entry)
("[(control ?i)]" allout-show-children)
- ("[(control ?i)]" allout-show-children)
("[(control ?s)]" allout-show-current-subtree)
("[(control ?t)]" allout-toggle-current-subtree-exposure)
;; Let user customize if they want to preempt describe-prefix-bindings ^h use.
("[?<]" allout-shift-out)
("[(control ?m)]" allout-rebullet-topic)
("[?*]" allout-rebullet-current-heading)
- ("[?']" allout-number-siblings)
+ ("[?#]" allout-number-siblings)
("[(control ?k)]" allout-kill-topic)
("[(meta ?k)]" allout-copy-topic-as-kill)
("[?@]" allout-resolve-xref)
: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 nil, neither auto-mode-activation nor auto-layout are
-enabled.
+With value \"activate\", only auto-mode-activation is enabled.
+Auto-layout is not.
-See the docstring for `allout-init' for the proper interface to
-this variable."
+With value nil, inhibit any automatic allout-mode activation."
+ :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.
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:
;;;###autoload
(put 'allout-presentation-padding 'safe-local-variable 'integerp)
-;;;_ = allout-abbreviate-flattened-numbering
-(defcustom allout-abbreviate-flattened-numbering nil
+;;;_ = allout-flattened-numbering-abbreviation
+(define-obsolete-variable-alias 'allout-abbreviate-flattened-numbering
+ 'allout-flattened-numbering-abbreviation "24.0")
+(defcustom allout-flattened-numbering-abbreviation nil
"If non-nil, `allout-flatten-exposed-to-buffer' abbreviates topic
numbers to minimal amount with some context. Otherwise, entire
numbers are always used."
(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.*
;;;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
- NEW-START -- integer indicating position of start of the first new item.
- NEW-END -- integer indicating position of end of the last new item.
-Some edits that introduce new items may missed by this hook:
-specifically edits that native allout routines do not control.
-
This hook might be invoked multiple times by a single command.")
;;;_ = allout-structure-deleted-hook
(defvar allout-structure-deleted-hook nil
that native allout routines do not control.
This hook might be invoked multiple times by a single command.")
+;;;_ = allout-after-copy-or-kill-hook
+(defvar allout-after-copy-or-kill-hook nil
+ "*Hook that's run after copying outline 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.
;;;_ > allout-mode-p ()
;; Must define this macro above any uses, or byte compilation will lack
;; proper def, if file isn't loaded -- eg, during emacs build!
+;;;###autoload
(defmacro allout-mode-p ()
"Return t if `allout-mode' is active in current buffer."
'allout-mode)
"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."
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
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
`allout-structure-added-hook'
`allout-structure-deleted-hook'
`allout-structure-shifted-hook'
+`allout-after-copy-or-kill-hook'
Terminology
(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))
See `allout-overlay-interior-modification-handler' for details."
- (if (and (allout-mode-p) undo-in-progress (allout-hidden-p))
- (allout-show-to-offshoot))
+ (when (and (allout-mode-p) undo-in-progress (allout-hidden-p))
+ (allout-show-children))
;; allout-overlay-interior-modification-handler on an overlay handles
;; this in other emacs, via `allout-exposure-category's 'modification-hooks.
(not modified)
(<= 33 key-num)
(setq mapped-binding
- ;; translate as a keybinding:
- (key-binding (vconcat allout-command-prefix
- (vector
- (if (and (<= 97 key-num) ; "a"
- (>= 122 key-num)) ; "z"
- (- key-num 96) key-num)))
- t)))
+ (or
+ ;; try control-modified versions of keys:
+ (key-binding (vconcat allout-command-prefix
+ (vector
+ (if (and (<= 97 key-num) ; "a"
+ (>= 122 key-num)) ; "z"
+ (- key-num 96) key-num)))
+ t)
+ ;; try non-modified versions of keys:
+ (key-binding (vconcat allout-command-prefix
+ (vector key-num))
+ t))))
;; Qualified as an allout command -- do hot-spot operation.
(setq allout-post-goto-bullet t)
;; accept-defaults nil, or else we get allout-item-icon-key-handler.
(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)
(depth (allout-depth)))
(allout-annotate-hidden beg end)
- (if (and (not beg-hidden) (not end-hidden))
- (allout-unprotected (kill-line arg))
- (kill-line arg))
- (allout-deannotate-hidden beg end)
-
- (if allout-numbered-bullet
- (save-excursion ; Renumber subsequent topics if needed:
- (if (not (save-match-data (looking-at allout-regexp)))
- (allout-next-heading))
- (allout-renumber-to-depth depth)))
- (run-hook-with-args 'allout-structure-deleted-hook depth (point)))))
+ (unwind-protect
+ (if (and (not beg-hidden) (not end-hidden))
+ (allout-unprotected (kill-line arg))
+ (kill-line arg))
+ (run-hooks 'allout-after-copy-or-kill-hook)
+ (allout-deannotate-hidden beg end)
+
+ (if allout-numbered-bullet
+ (save-excursion ; Renumber subsequent topics if needed:
+ (if (not (save-match-data (looking-at allout-regexp)))
+ (allout-next-heading))
+ (allout-renumber-to-depth depth)))
+ (run-hook-with-args 'allout-structure-deleted-hook depth (point))))))
;;;_ > allout-copy-line-as-kill ()
(defun allout-copy-line-as-kill ()
"Like allout-kill-topic, but save to kill ring instead of deleting."
(forward-char 1)))
(allout-annotate-hidden beg (setq end (point)))
- (unwind-protect
+ (unwind-protect ; for possible barf-if-buffer-read-only.
(allout-unprotected (kill-region beg end))
- (if buffer-read-only
- ;; eg, during copy-as-kill.
- (allout-deannotate-hidden beg end)))
+ (allout-deannotate-hidden beg end)
+ (run-hooks 'allout-after-copy-or-kill-hook)
- (save-excursion
- (allout-renumber-to-depth depth))
- (run-hook-with-args 'allout-structure-deleted-hook depth (point))))
+ (save-excursion
+ (allout-renumber-to-depth depth))
+ (run-hook-with-args 'allout-structure-deleted-hook depth (point)))))
;;;_ > allout-copy-topic-as-kill ()
(defun allout-copy-topic-as-kill ()
"Like `allout-kill-topic', but save to kill ring instead of deleting."
(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."
;; Goto initial topic, and register preceeding stuff, if any:
(if (> (allout-goto-prefix-doublechecked) start)
;; First topic follows beginning point -- register preliminary stuff:
- (setq result (list (list 0 "" nil
- (buffer-substring start (1- (point)))))))
+ (setq result
+ (list (list 0 "" nil
+ (buffer-substring-no-properties start
+ (1- (point)))))))
(while (and (not done)
(not (eobp)) ; Loop until we've covered the region.
(not (> (point) end)))
(setq strings nil)
(while (> next (point)) ; Get all the exposed text in
(setq strings
- (cons (buffer-substring
+ (cons (buffer-substring-no-properties
beg
;To hidden text or end of line:
(progn
bullet)))
(cond ((listp format)
(list depth
- (if allout-abbreviate-flattened-numbering
+ (if allout-flattened-numbering-abbreviation
(allout-stringify-flat-index format
gone-out)
(allout-stringify-flat-index-plain
(with-temp-buffer
(insert text)
;; convey the text characteristics of the original buffer:
- (allout-set-buffer-multibyte multibyte)
+ (set-buffer-multibyte multibyte)
(when encoding
(set-buffer-file-coding-system encoding)
(if (not decrypt)
(setq result-text
(if decrypt
- (epg-decrypt-string epg-context
- (encode-coding-string massaged-text
- (or encoding 'utf-8)))
+ (condition-case err
+ (epg-decrypt-string epg-context
+ (encode-coding-string massaged-text
+ (or encoding 'utf-8)))
+ (epg-error
+ (signal 'egp-error
+ (cons (concat (cadr err) " - gpg version problem?")
+ (cddr err)))))
(replace-regexp-in-string "\n$" ""
(epg-encrypt-string epg-context
(encode-coding-string massaged-text
(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")
'previous-single-property-change)
;; No docstring because xemacs defalias doesn't support it.
)
-;;;_ > allout-set-buffer-multibyte
-(if (fboundp 'set-buffer-multibyte)
- (defalias 'allout-set-buffer-multibyte 'set-buffer-multibyte)
- (with-no-warnings
- ;; this definition is used only in older or alternative emacs, where
- ;; the setting is our only recourse.
- (defun allout-set-buffer-multibyte (is-multibyte)
- (set enable-multibyte-characters is-multibyte))))
;;;_ > allout-select-safe-coding-system
(defalias 'allout-select-safe-coding-system
(if (fboundp 'select-safe-coding-system)