;;; allout.el --- extensive outline mode for use alone and with other modes
-;; Copyright (C) 1992-1994, 2001-2011 Free Software Foundation, Inc.
+;; Copyright (C) 1992-1994, 2001-2012 Free Software Foundation, Inc.
;; Author: Ken Manheimer <ken dot manheimer at gmail...>
;; Maintainer: Ken Manheimer <ken dot manheimer at gmail...>
Functions can be bound to multiple keys, but binding keys to
multiple functions will not work - the last binding for a key
prevails."
+ :version "24.1"
:type 'allout-keybindings-binding
:group 'allout-keybindings
:set 'allout-compose-and-institute-keymap
parentheses, with the literal key, as above, preceded by the name(s)
of the modifiers, eg: [(control ?a)]
See the existing keys for examples."
+ :version "24.1"
:type 'allout-keybindings-binding
:group 'allout-keybindings
:set 'allout-compose-and-institute-keymap
;;;_ = allout-inhibit-auto-fill-on-headline
(defcustom allout-inhibit-auto-fill-on-headline nil
"If non-nil, auto-fill will be inhibited while on topic's header line."
+ :version "24.1"
:type 'boolean
:group 'allout)
(make-variable-buffer-local 'allout-inhibit-auto-fill-on-headline)
"If non-nil, `allout-flatten-exposed-to-buffer' abbreviates topic
numbers to minimal amount with some context. Otherwise, entire
numbers are always used."
+ :version "24.1"
:type 'boolean
:group 'allout)
;;;_ : Topic header format
;;;_ = allout-regexp
(defvar allout-regexp ""
- "*Regular expression to match the beginning of a heading line.
+ "Regular expression to match the beginning of a heading line.
Any line whose beginning matches this regexp is considered a
heading. This var is set according to the user configuration vars
(make-variable-buffer-local 'allout-bullets-string-len)
;;;_ = allout-depth-specific-regexp
(defvar allout-depth-specific-regexp ""
- "*Regular expression to match a heading line prefix for a particular depth.
+ "Regular expression to match a heading line prefix for a particular depth.
This expression is used to search for depth-specific topic
headers at depth 2 and greater. Use `allout-depth-one-regexp'
(make-variable-buffer-local 'allout-depth-specific-regexp)
;;;_ = allout-depth-one-regexp
(defvar allout-depth-one-regexp ""
- "*Regular expression to match a heading line prefix for depth one.
+ "Regular expression to match a heading line prefix for depth one.
This var is set according to the user configuration vars by
`set-allout-regexp'. It is prepared with format strings for two
,expr))
;;;_ = allout-mode-hook
(defvar allout-mode-hook nil
- "*Hook that's run when allout mode starts.")
+ "Hook run when allout mode starts.")
;;;_ = allout-mode-deactivate-hook
-(defvar allout-mode-deactivate-hook nil
- "*Hook that's run when allout mode ends.")
(define-obsolete-variable-alias 'allout-mode-deactivate-hook
'allout-mode-off-hook "24.1")
+(defvar allout-mode-deactivate-hook nil
+ "Hook run when allout mode ends.")
;;;_ = allout-exposure-category
(defvar allout-exposure-category nil
"Symbol for use as allout invisible-text overlay category.")
-;;;_ = allout-exposure-change-hook
-(defvar allout-exposure-change-hook nil
- "*Hook that's run after allout outline subtree exposure changes.
+;;;_ = allout-exposure-change-functions
+(define-obsolete-variable-alias 'allout-exposure-change-hook
+ 'allout-exposure-change-functions "24.3")
+(defcustom allout-exposure-change-functions nil
+ "Abnormal hook run after allout outline subtree exposure changes.
It is run at the conclusion of `allout-flag-region'.
Functions on the hook must take three arguments:
- TO -- integer indicating the point of the end of the change.
- FLAG -- change mode: nil for exposure, otherwise concealment.
-This hook might be invoked multiple times by a single command.")
-;;;_ = allout-structure-added-hook
-(defvar allout-structure-added-hook nil
- "*Hook that's run after addition of items to the outline.
+This hook might be invoked multiple times by a single command."
+ :type 'hook
+ :group 'allout
+ :version "24.3")
+;;;_ = allout-structure-added-functions
+(define-obsolete-variable-alias 'allout-structure-added-hook
+ 'allout-structure-added-functions "24.3")
+(defcustom allout-structure-added-functions nil
+ "Abnormal hook run after adding items to an Allout outline.
Functions on the hook should take two arguments:
- NEW-START -- integer indicating position of start of the first new item.
- NEW-END -- integer indicating position of end of the last new item.
-This hook might be invoked multiple times by a single command.")
-;;;_ = allout-structure-deleted-hook
-(defvar allout-structure-deleted-hook nil
- "*Hook that's run after disciplined deletion of subtrees from the outline.
+This hook might be invoked multiple times by a single command."
+ :type 'hook
+ :group 'allout
+ :version "24.3")
+;;;_ = allout-structure-deleted-functions
+(define-obsolete-variable-alias 'allout-structure-deleted-hook
+ 'allout-structure-deleted-functions "24.3")
+(defcustom allout-structure-deleted-functions nil
+ "Abnormal hook run after deleting subtrees from an Allout outline.
Functions on the hook must take two arguments:
- DEPTH -- integer indicating the depth of the subtree that was deleted.
Some edits that remove or invalidate items may be 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-shifted-hook
-(defvar allout-structure-shifted-hook nil
- "*Hook that's run after shifting of items in the outline.
+This hook might be invoked multiple times by a single command."
+ :type 'hook
+ :group 'allout
+ :version "24.3")
+;;;_ = allout-structure-shifted-functions
+(define-obsolete-variable-alias 'allout-structure-shifted-hook
+ 'allout-structure-shifted-functions "24.3")
+(defcustom allout-structure-shifted-functions nil
+ "Abnormal hook run after shifting items in an Allout outline.
Functions on the hook should take two arguments:
- DEPTH-CHANGE -- integer indicating depth increase, negative for decrease
Some edits that shift items can be missed by this hook: specifically edits
that native allout routines do not control.
-This hook might be invoked multiple times by a single command.")
+This hook might be invoked multiple times by a single command."
+ :type 'hook
+ :group 'allout
+ :version "24.3")
+
;;;_ = allout-after-copy-or-kill-hook
-(defvar allout-after-copy-or-kill-hook nil
- "*Hook that's run after copying outline text.
+(defcustom allout-after-copy-or-kill-hook nil
+ "Normal hook run after copying outline text.."
+ :type 'hook
+ :group 'allout
+ :version "24.3")
-Functions on the hook should not require any arguments.")
;;;_ = allout-post-undo-hook
-(defvar allout-post-undo-hook nil
- "*Hook that's run after undo activity.
-
+(defcustom allout-post-undo-hook nil
+ "Normal hook run after undo activity.
The item that's current when the hook is run *may* be the one
-that was affected by the undo.
+that was affected by the undo.."
+ :type 'hook
+ :group 'allout
+ :version "24.3")
-Functions on the hook should not require 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.
the Emacs buffer state, if file variable adjustments are enabled. See
`allout-enable-file-variable-adjustment' for details about that.")
(make-variable-buffer-local 'allout-passphrase-verifier-string)
-(make-obsolete 'allout-passphrase-verifier-string
- 'allout-passphrase-verifier-string "23.3")
+(make-obsolete-variable 'allout-passphrase-verifier-string
+ 'allout-passphrase-verifier-string "23.3")
;;;###autoload
(put 'allout-passphrase-verifier-string 'safe-local-variable 'stringp)
;;;_ = allout-passphrase-hint-string
`allout-enable-file-variable-adjustment' for details about that.")
(make-variable-buffer-local 'allout-passphrase-hint-string)
(setq-default allout-passphrase-hint-string "")
-(make-obsolete 'allout-passphrase-hint-string
- 'allout-passphrase-hint-string "23.3")
+(make-obsolete-variable 'allout-passphrase-hint-string
+ 'allout-passphrase-hint-string "23.3")
;;;###autoload
(put 'allout-passphrase-hint-string 'safe-local-variable 'stringp)
;;;_ = allout-after-save-decrypt
MODE is the activation mode - see `allout-auto-activation' for
valid values."
-
+ (declare (obsolete allout-auto-activation "23.3"))
(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."
Extending Allout
-Allout exposure and authoring activites all have associated
+Allout exposure and authoring activities all have associated
hooks, by which independent code can cooperate with allout
without changes to the allout core. Here are key ones:
`allout-mode-hook'
`allout-mode-deactivate-hook' (deprecated)
`allout-mode-off-hook'
-`allout-exposure-change-hook'
-`allout-structure-added-hook'
-`allout-structure-deleted-hook'
-`allout-structure-shifted-hook'
+`allout-exposure-change-functions'
+`allout-structure-added-functions'
+`allout-structure-deleted-functions'
+`allout-structure-shifted-functions'
`allout-after-copy-or-kill-hook'
`allout-post-undo-hook'
plain BULLETs are by default used, according to the DEPTH of the
TOPIC. Choice among the distinctive BULLETs is offered when you
provide a universal argument (\\[universal-argument]) to the
- TOPIC creation command, or when explictly rebulleting a TOPIC. The
+ TOPIC creation command, or when explicitly rebulleting a TOPIC. The
significance of the various distinctive bullets is purely by
convention. See the documentation for the above bullet strings for
more details.
(run-hooks 'allout-post-undo-hook)
(cond ((and (= buffer-saved-size -1)
allout-auto-save-temporarily-disabled)
- ;; user possibly undid a decryption, deinhibit auto-save:
+ ;; user possibly undid a decryption, disinhibit auto-save:
(allout-maybe-resume-auto-save-info-after-encryption))
((save-excursion
(save-restriction
(allout-show-children)))
(end-of-line)
- (run-hook-with-args 'allout-structure-added-hook start end)
+ (run-hook-with-args 'allout-structure-added-functions start end)
)
)
)
nil ;;; number-control
nil ;;; index
t) ;;; do-successors
- (run-hook-with-args 'allout-exposure-change-hook
+ (run-hook-with-args 'allout-exposure-change-functions
from to t))
(setq arg (1- arg))
(if (<= arg 0)
(not (allout-encrypted-topic-p)))
(allout-reindent-body current-depth new-depth))
- (run-hook-with-args 'allout-exposure-change-hook mb me nil)
+ (run-hook-with-args 'allout-exposure-change-functions mb me nil)
;; Recursively rectify successive siblings of orig topic if
;; caller elected for it:
(allout-show-children))))))
(let ((where (point)))
(allout-rebullet-topic 1 (and (> arg 1) 'sans-offspring))
- (run-hook-with-args 'allout-structure-shifted-hook arg where))))
+ (run-hook-with-args 'allout-structure-shifted-functions arg where))))
;;;_ > allout-shift-out (arg)
(defun allout-shift-out (arg)
"Decrease depth of current heading and any topics collapsed within it.
(goto-char child-point)
(allout-shift-out 1))))
(allout-rebullet-topic (* arg -1))))
- (run-hook-with-args 'allout-structure-shifted-hook (* arg -1) where))))
+ (run-hook-with-args 'allout-structure-shifted-functions (* arg -1) where))))
;;;_ : Surgery (kill-ring) functions with special provisions for outlines:
;;;_ > allout-kill-line (&optional arg)
(defun allout-kill-line (&optional arg)
(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))))))
+ (run-hook-with-args 'allout-structure-deleted-functions 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."
(save-excursion
(allout-renumber-to-depth depth))
- (run-hook-with-args 'allout-structure-deleted-hook depth (point)))))
+ (run-hook-with-args 'allout-structure-deleted-functions 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-deannotate-hidden (allout-mark-marker t) (point)))
(if (not resituate)
(exchange-point-and-mark))
- (run-hook-with-args 'allout-structure-added-hook subj-beg subj-end))))
+ (run-hook-with-args 'allout-structure-added-functions subj-beg subj-end))))
;;;_ > allout-yank (&optional arg)
(defun allout-yank (&optional arg)
"`allout-mode' yank, with depth and numbering adjustment of yanked topics.
;;;_ > allout-flag-region (from to flag)
(defun allout-flag-region (from to flag)
"Conceal text between FROM and TO if FLAG is non-nil, else reveal it.
-
-Exposure-change hook `allout-exposure-change-hook' is run with the same
-arguments as this function, after the exposure changes are made."
+After the exposure changes are made, run the abnormal hook
+`allout-exposure-change-functions' with the same arguments as
+this function."
;; We use outline invisibility spec.
(remove-overlays from to 'category 'allout-exposure-category)
(overlay-put o (pop props) (pop props))
(error nil))))))
(setq allout-this-command-hid-text t))
- (run-hook-with-args 'allout-exposure-change-hook from to flag))
+ (run-hook-with-args 'allout-exposure-change-functions from to flag))
;;;_ > allout-flag-current-subtree (flag)
(defun allout-flag-current-subtree (flag)
"Conceal currently-visible topic's subtree if FLAG non-nil, else reveal it."
Expose children and grandchildren of first topic at current
level, and expose children of subsequent topics at current
level *except* for the last, which should be opened completely."
- (list 'save-excursion
- '(if (not (or (allout-goto-prefix-doublechecked)
- (allout-next-heading)))
- (error "allout-new-exposure: Can't find any outline topics"))
- (list 'allout-expose-topic (list 'quote spec))))
+ `(save-excursion
+ (if (not (or (allout-goto-prefix-doublechecked)
+ (allout-next-heading)))
+ (error "allout-new-exposure: Can't find any outline topics"))
+ (allout-expose-topic ',spec)))
;;;_ #7 Systematic outline presentation -- copying, printing, flattening
Further, encrypting with a KEYMODE-CUE universal argument greater
than 4 - eg, preceded by a doubled Ctrl-U - causes association of
the specified recipients with the file, replacing those currently
-associated with it. This can be used to deassociate any
+associated with it. This can be used to dissociate any
recipients with the file, by selecting no recipients in the
dialog.
Further, encrypting with a KEYMODE-CUE universal argument greater
than 4 - eg, preceded by a doubled Ctrl-U - causes association of
the specified recipients with the file, replacing those currently
-associated with it. This can be used to deassociate any
+associated with it. This can be used to dissociate any
recipients with the file, by selecting no recipients in the
dialog.
(allout-inhibit-auto-save-info-for-decryption was-buffer-saved-size)
(allout-maybe-resume-auto-save-info-after-encryption))
- (run-hook-with-args 'allout-structure-added-hook
+ (run-hook-with-args 'allout-structure-added-functions
bullet-pos subtree-end))))
;;;_ > allout-encrypt-string (text decrypt allout-buffer keymode-cue
;;; &optional rejected)
Further, encrypting with a KEYMODE-CUE universal argument greater
than 4 - eg, preceded by a doubled Ctrl-U - causes association of
the specified recipients with the file, replacing those currently
-associated with it. This can be used to deassociate any
+associated with it. This can be used to dissociate any
recipients with the file, by selecting no recipients in the
dialog.
(if (/= arg 1)
(condition-case nil (line-move (1- arg)) (error nil)))
- ;; Move to beginning-of-line, ignoring fields and invisibles.
+ ;; Move to beginning-of-line, ignoring fields and invisible text.
(skip-chars-backward "^\n")
(while (and (not (bobp))
(let ((prop