;;; allout.el --- extensive outline mode for use alone and with other modes
-;; Copyright (C) 1992, 1993, 1994, 2001, 2002 Free Software Foundation, Inc.
+;; Copyright (C) 1992, 93, 94, 2001, 02, 2004 Free Software Foundation, Inc.
;; Author: Ken Manheimer <klm@zope.com>
;; Maintainer: Ken Manheimer <klm@zope.com>
;;
;; The outline menubar additions provide 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
+;; for instructions on priming your Emacs session for automatic
;; activation of `allout-mode'.
;;
;; See the docstring of the variables `allout-layout' and
With value t, auto-mode-activation and auto-layout are enabled.
\(This also depends on `allout-find-file-hook' being installed in
-`find-file-hooks', which is also done by `allout-init'.)
+`find-file-hook', which is also done by `allout-init'.)
With value `ask', auto-mode-activation is enabled, and endorsement for
performing auto-layout is asked of the user each time.
var and the respective allout-*-bullets-string vars.
The value of an asterisk (`*') provides for backwards compatibility
-with the original emacs outline mode. See `allout-plain-bullets-string'
+with the original Emacs outline mode. See `allout-plain-bullets-string'
and `allout-distinctive-bullets-string' for the range of available
bullets."
:type 'string
Non-nil restricts the topic creation and modification
functions to asterix-padded prefixes, so they look exactly
-like the original emacs-outline style prefixes.
+like the original Emacs-outline style prefixes.
Whatever the setting of this variable, both old and new style prefixes
are always respected by the topic maneuvering functions."
(defcustom allout-inhibit-protection nil
"*Non-nil disables warnings and confirmation-checks for concealed-text edits.
-Outline mode uses emacs change-triggered functions to detect unruly
+Outline mode uses Emacs change-triggered functions to detect unruly
changes to concealed regions. Set this var non-nil to disable the
protection, potentially increasing text-entry responsiveness a bit.
;;;_ : Version
;;;_ = allout-version
(defvar allout-version
- (let ((rcs-rev "$Revision: 1.47 $"))
+ (let ((rcs-rev "$Revision$"))
(condition-case err
(save-match-data
(string-match "Revision: \\([0-9]+\\.[0-9]+\\)" rcs-rev)
(defvar allout-mode-map nil "Keybindings for (allout) outline minor mode.")
;;;_ > produce-allout-mode-map (keymap-alist &optional base-map)
(defun produce-allout-mode-map (keymap-list &optional base-map)
- "Produce keymap for use as allout-mode-map, from keymap-list.
+ "Produce keymap for use as allout-mode-map, from KEYMAP-LIST.
Built on top of optional BASE-MAP, or empty sparse map if none specified.
See doc string for allout-keybindings-list for format of binding list."
(car (cdr cell)))))))
keymap-list)
map))
-;;;_ = allout-prior-bindings - being deprecated.
-(defvar allout-prior-bindings nil
- "Variable for use in V18, with `allout-added-bindings', for
-resurrecting, on mode deactivation, bindings that existed before
-activation. Being deprecated.")
-;;;_ = allout-added-bindings - being deprecated
-(defvar allout-added-bindings nil
- "Variable for use in V18, with `allout-prior-bindings', for
-resurrecting, on mode deactivation, bindings that existed before
-activation. Being deprecated.")
+
;;;_ : Menu bar
+(defvar allout-mode-exposure-menu)
+(defvar allout-mode-editing-menu)
+(defvar allout-mode-navigation-menu)
+(defvar allout-mode-misc-menu)
(defun produce-allout-mode-menubar-entries ()
(require 'easymenu)
(easy-menu-define allout-mode-exposure-menu
to track repeats.")
;;;_ > allout-write-file-hook ()
(defun allout-write-file-hook ()
- "In `allout-mode', run as a `local-write-file-hooks' activity.
+ "In `allout-mode', run as a `write-contents-functions' activity.
Currently just sets `allout-during-write-cue', so outline change-protection
knows to keep inactive during file write."
- 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
+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)
-`allout-find-file-hook' in `find-file-hooks', and giving
+`allout-find-file-hook' in `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:
+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)"
(curr-mode 'allout-auto-activation))
(cond ((not mode)
- (setq find-file-hooks (delq hook find-file-hooks))
+ (setq find-file-hook (delq hook find-file-hook))
(if (interactive-p)
(message "Allout outline mode auto-activation inhibited.")))
((eq mode 'report)
- (if (memq hook find-file-hooks)
+ (if (memq hook find-file-hook)
;; Just punt and use the reports from each of the modes:
(allout-init (symbol-value curr-mode))
(allout-init nil)
(message "Allout outline mode auto-activation inhibited.")))
- (t (add-hook 'find-file-hooks hook)
+ (t (add-hook 'find-file-hook hook)
(set curr-mode ; `set', not `setq'!
(cond ((eq mode 'activate)
(message
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'.
+priming your Emacs session for automatic activation of `allout-mode'.
The bindings are dictated by the `allout-keybindings-list' and
Like above 'copy-exposed', but convert topic
prefixes to section.subsection... numeric
format.
-ESC ESC (allout-init t) Setup emacs session for outline mode
+ESC ESC (allout-init t) Setup Emacs session for outline mode
auto-activation.
HOT-SPOT Operation
Topic hierarchy constituents - TOPICS and SUBTOPICS:
-TOPIC: A basic, coherent component of an emacs outline. It can
+TOPIC: A basic, coherent component of an Emacs outline. It can
contain other topics, and it can be subsumed by other topics,
CURRENT topic:
The visible topic most immediately containing the cursor.
; active state or *de*activation
; specifically requested:
(setq allout-explicitly-deactivated t)
- (if (string-match "^18\." emacs-version)
- ; Revoke those keys that remain
- ; as we set them:
- (let ((curr-loc (current-local-map)))
- (mapcar (function
- (lambda (cell)
- (if (eq (lookup-key curr-loc (car cell))
- (car (cdr cell)))
- (define-key curr-loc (car cell)
- (assq (car cell) allout-prior-bindings)))))
- allout-added-bindings)
- (allout-resumptions 'allout-added-bindings)
- (allout-resumptions 'allout-prior-bindings)))
(if allout-old-style-prefixes
(progn
(allout-resumptions 'selective-display)
(if (and (boundp 'before-change-functions) before-change-functions)
(allout-resumptions 'before-change-functions))
- (setq local-write-file-hooks
- (delq 'allout-write-file-hook
- local-write-file-hooks))
+ (setq write-contents-functions
+ (delq 'allout-write-file-hook
+ write-contents-functions))
(allout-resumptions 'paragraph-start)
(allout-resumptions 'paragraph-separate)
(allout-resumptions (if (string-match "^18" emacs-version)
(cons '(allout-mode . allout-mode-map)
minor-mode-map-alist))))
- ; V18 minor-mode key bindings:
- ; Stash record of added bindings
- ; for later revocation:
- (allout-resumptions 'allout-added-bindings
- (list allout-keybindings-list))
- (allout-resumptions 'allout-prior-bindings
- (list (current-local-map)))
; and add them:
(use-local-map (produce-allout-mode-map allout-keybindings-list
(current-local-map)))
)
; selective-display is the
- ; emacs conditional exposure
+ ; Emacs conditional exposure
; mechanism:
(allout-resumptions 'selective-display '(t))
(if allout-inhibit-protection
; Temporarily set by any outline
; functions that can be trusted to
; deal properly with concealed text.
- (add-hook 'local-write-file-hooks 'allout-write-file-hook)
+ (add-hook 'write-contents-functions 'allout-write-file-hook)
; Custom auto-fill func, to support
; respect for topic headline,
; hanging-indents, etc:
(defun allout-sibling-index (&optional depth)
"Item number of this prospective topic among its siblings.
-If optional arg depth is greater than current depth, then we're
+If optional arg DEPTH is greater than current depth, then we're
opening a new level, and return 0.
If less than this depth, ascend to that depth and count..."
"Produce a location \"chart\" of subtopics of the containing topic.
Optional argument LEVELS specifies the depth \(relative to start
-depth) for the chart. Subsequent optional args are not for public
-use.
+depth) for the chart.
Charts are used to capture outline structure, so that outline altering
routines need assess the structure only once, and then use the chart
The chart for a topics' offspring precedes the entry for the topic
itself.
-The other function parameters are for internal recursion, and should
-not be specified by external callers. ORIG-DEPTH is depth of topic at
-starting point, and PREV-DEPTH is depth of prior topic."
+\(fn &optional levels)"
+
+ ;; The other function parameters are for internal recursion, and should
+ ;; not be specified by external callers. ORIG-DEPTH is depth of topic at
+ ;; starting point, and PREV-DEPTH is depth of prior topic."
(let ((original (not orig-depth)) ; `orig-depth' set only in recursion.
chart curr-depth)
;; Loop over the current levels' siblings. Besides being more
;; efficient than tail-recursing over a level, it avoids exceeding
- ;; the typically quite constrained emacs max-lisp-eval-depth.
+ ;; the typically quite constrained Emacs max-lisp-eval-depth.
;;
;; Probably would speed things up to implement loop-based stack
;; operation rather than recursing for lower levels. Bah.
(setq chart (cdr chart))))
result))
;;;_ X allout-chart-spec (chart spec &optional exposing)
-(defun allout-chart-spec (chart spec &optional exposing)
- "Not yet \(if ever) implemented.
-
-Produce exposure directives given topic/subtree CHART and an exposure SPEC.
-
-Exposure spec indicates the locations to be exposed and the prescribed
-exposure status. Optional arg EXPOSING is an integer, with 0
-indicating pending concealment, anything higher indicating depth to
-which subtopic headers should be exposed, and negative numbers
-indicating (negative of) the depth to which subtopic headers and
-bodies should be exposed.
-
-The produced list can have two types of entries. Bare numbers
-indicate points in the buffer where topic headers that should be
-exposed reside.
-
- - bare negative numbers indicates that the topic starting at the
- point which is the negative of the number should be opened,
- including their entries.
- - bare positive values indicate that this topic header should be
- opened.
- - Lists signify the beginning and end points of regions that should
- be flagged, and the flag to employ. (For concealment: `\(\?r\)', and
- exposure:"
- (while spec
- (cond ((listp spec)
- )
- )
- (setq spec (cdr spec)))
- )
+;; (defun allout-chart-spec (chart spec &optional exposing)
+;; "Not yet \(if ever) implemented.
+
+;; Produce exposure directives given topic/subtree CHART and an exposure SPEC.
+
+;; Exposure spec indicates the locations to be exposed and the prescribed
+;; exposure status. Optional arg EXPOSING is an integer, with 0
+;; indicating pending concealment, anything higher indicating depth to
+;; which subtopic headers should be exposed, and negative numbers
+;; indicating (negative of) the depth to which subtopic headers and
+;; bodies should be exposed.
+
+;; The produced list can have two types of entries. Bare numbers
+;; indicate points in the buffer where topic headers that should be
+;; exposed reside.
+
+;; - bare negative numbers indicates that the topic starting at the
+;; point which is the negative of the number should be opened,
+;; including their entries.
+;; - bare positive values indicate that this topic header should be
+;; opened.
+;; - Lists signify the beginning and end points of regions that should
+;; be flagged, and the flag to employ. (For concealment: `\(\?r\)', and
+;; exposure:"
+;; (while spec
+;; (cond ((listp spec)
+;; )
+;; )
+;; (setq spec (cdr spec)))
+;; )
;;;_ - Within Topic
;;;_ > allout-goto-prefix ()
writes, like crypt and zip modes.)
Locally bound in outline buffers to `before-change-functions', which
-in emacs 19 is run before any change to the buffer.
+in Emacs 19 is run before any change to the buffer.
Any functions which set [`this-command' to `undo', or which set]
`allout-override-protect' non-nil (as does, eg, allout-flag-chars)
; Both beginning and end chars must
; be exposed:
(save-excursion (if (memq this-command '(newline open-line))
- ;; Compensate for stupid emacs {new,
+ ;; Compensate for stupid Emacs {new,
;; open-}line display optimization:
(setq beg (1+ beg)
end (1+ end)))
(save-match-data
(if (equal this-command 'undo)
;; Allow undo without inhibition.
- ;; - Undoing new and open-line hits stupid emacs redisplay
+ ;; - Undoing new and open-line hits stupid Emacs redisplay
;; optimization (em 19 cmds.c, ~ line 200).
;; - Presumably, undoing what was properly protected when
;; done.
(let* ((this-key-num (cond
((numberp last-command-char)
last-command-char)
- ;; XXX Only xemacs has characterp.
+ ;; XXX Only XEmacs has characterp.
((and (fboundp 'characterp)
(characterp last-command-char))
(char-to-int last-command-char))
;;;_ > allout-flag-region (from to flag)
(defmacro allout-flag-region (from to flag)
- "Hide or show lines from FROM to TO, via emacs selective-display FLAG char.
+ "Hide or show lines from FROM to TO, via Emacs selective-display FLAG char.
Ie, text following flag C-m \(carriage-return) is hidden until the
next C-j (newline) char.
;;;_ > allout-isearch-expose (mode)
(defun allout-isearch-expose (mode)
- "Mode is either 'clear, 'start, 'continue, or 'final."
+ "MODE is either 'clear, 'start, 'continue, or 'final."
;; allout-isearch-prior-pos encodes exposure status of prior pos:
;; (pos was-vis header-pos end-pos)
;; pos - point of concern
)
;;;_ > allout-distinctive-bullet (bullet)
(defun allout-distinctive-bullet (bullet)
- "True if bullet is one of those on `allout-distinctive-bullets-string'."
+ "True if BULLET is one of those on `allout-distinctive-bullets-string'."
(string-match (regexp-quote bullet) allout-distinctive-bullets-string))
;;;_ > allout-numbered-type-prefix (&optional prefix)
(defun allout-numbered-type-prefix (&optional prefix)
)
;;;_ > allout-open-topic (relative-depth &optional before use_sib_bullet)
(defun allout-open-topic (relative-depth &optional before use_sib_bullet)
- "Open a new topic at depth DEPTH.
+ "Open a new topic at depth RELATIVE-DEPTH.
New topic is situated after current one, unless optional flag BEFORE
is non-nil, or unless current line is complete empty (not even
(do-auto-fill))))
;;;_ > allout-reindent-body (old-depth new-depth &optional number)
(defun allout-reindent-body (old-depth new-depth &optional number)
- "Reindent body lines which were indented at old-depth to new-depth.
+ "Reindent body lines which were indented at OLD-DEPTH to NEW-DEPTH.
Optional arg NUMBER indicates numbering is being added, and it must
be accommodated.
"Adjust bullet of current topic prefix.
-All args are optional.
-
If SOLICIT is non-nil, then the choice of bullet is solicited from
user. If it's a character, then that character is offered as the
default, otherwise the one suited to the context \(according to
distinction or depth) is offered. If non-nil, then the
context-specific bullet is just used.
-Second arg DEPTH forces the topic prefix to that depth, regardless
+Second arg NEW-DEPTH forces the topic prefix to that depth, regardless
of the topic's current depth.
Third arg NUMBER-CONTROL can force the prefix to or away from
contained subtopics. See `allout-rebullet-heading' for rebulleting
behavior.
-All arguments are optional.
-
-First arg RELATIVE-DEPTH means to shift the depth of the entire
+Arg RELATIVE-DEPTH means to shift the depth of the entire
topic that amount.
-The rest of the args are for internal recursive use by the function
-itself. The are STARTING-DEPTH, STARTING-POINT, and INDEX."
+\(fn &optional RELATIVE-DEPTH)"
+
+ ;; All args except the first one are for internal recursive use by the
+ ;; function itself.
(let* ((relative-depth (or relative-depth 0))
(new-depth (allout-depth))
max-pos)))
;;;_ > allout-old-expose-topic (spec &rest followers)
(defun allout-old-expose-topic (spec &rest followers)
-
- "Deprecated. Use `allout-expose-topic' \(with different schema
-format) instead.
-
-Dictate wholesale exposure scheme for current topic, according to SPEC.
+ "Dictate wholesale exposure scheme for current topic, according to SPEC.
SPEC is either a number or a list. Optional successive args
dictate exposure for subsequent siblings of current topic.
elements of the list are nested SPECs, dictating the specific exposure
for the corresponding offspring of the topic.
-Optional FOLLOWER arguments dictate exposure for succeeding siblings."
+Optional FOLLOWERS arguments dictate exposure for succeeding siblings."
(interactive "xExposure spec: ")
(let ((depth (allout-current-depth))
(allout-old-expose-topic (car followers))
(setq followers (cdr followers)))
max-pos))
+(make-obsolete 'allout-old-expose-topic
+ "use `allout-expose-topic' (with different schema format) instead."
+ "19.23")
;;;_ > allout-new-exposure '()
(defmacro allout-new-exposure (&rest spec)
"Literal frontend for `allout-expose-topic', doesn't evaluate arguments.
(list 'allout-expose-topic (list 'quote spec))))
;;;_ > allout-exposure '()
(defmacro allout-exposure (&rest spec)
- "Being deprecated - use more recent `allout-new-exposure' instead.
-
-Literal frontend for `allout-old-expose-topic', doesn't evaluate arguments
+ "Literal frontend for `allout-old-expose-topic', doesn't evaluate arguments
and retains start position."
(list 'save-excursion
'(if (not (or (allout-goto-prefix)
(error "Can't find any outline topics"))
(cons 'allout-old-expose-topic
(mapcar (function (lambda (x) (list 'quote x))) spec))))
+(make-obsolete 'allout-exposure 'allout-new-exposure "19.23")
;;;_ #7 Systematic outline presentation - copying, printing, flattening
;;;_ > allout-process-exposed (&optional func from to frombuf
;;; tobuf format)
(defun allout-process-exposed (&optional func from to frombuf tobuf
- format &optional start-num)
+ format start-num)
"Map function on exposed parts of current topic; results to another buffer.
-All args are options; default values itemized below.
-
-Apply FUNCTION to exposed portions FROM position TO position in buffer
+Apply FUNC to exposed portions FROM position TO position in buffer
FROMBUF to buffer TOBUF. Sixth optional arg, FORMAT, designates an
alternate presentation form:
except for distinctive bullets.
Defaults:
- FUNCTION: `allout-insert-listified'
+ FUNC: `allout-insert-listified'
FROM: region start, if region active, else start of buffer
TO: region end, if region active, else end of buffer
FROMBUF: current buffer
(defun allout-insert-listified (listified)
"Insert contents of listified outline portion in current buffer.
-Listified is a list representing each topic header and body:
+LISTIFIED is a list representing each topic header and body:
\`(depth prefix text)'
-or \`(depth prefix text bullet-plus)'
+or
+
+ \`(depth prefix text bullet-plus)'
If `bullet-plus' is specified, it is inserted just after the entire prefix."
(setq listified (cdr listified))
(defun allout-flatten-exposed-to-buffer (&optional arg tobuf)
"Present numeric outline of outline's exposed portions in another buffer.
-The resulting outline is not compatable with outline mode - use
+The resulting outline is not compatible with outline mode - use
`allout-copy-exposed-to-buffer' if you want that.
Use `allout-indented-exposed-to-buffer' for indented presentation.
With repeat count, copy the exposed portions of only current topic.
-Other buffer has current buffers name with \" exposed\" appended to
+Other buffer has current buffer's name with \" exposed\" appended to
it, unless optional second arg TOBUF is specified, in which case it is
used verbatim."
(interactive "P")
(defun allout-indented-exposed-to-buffer (&optional arg tobuf)
"Present indented outline of outline's exposed portions in another buffer.
-The resulting outline is not compatable with outline mode - use
+The resulting outline is not compatible with outline mode - use
`allout-copy-exposed-to-buffer' if you want that.
Use `allout-flatten-exposed-to-buffer' for numeric sectional presentation.
With repeat count, copy the exposed portions of only current topic.
-Other buffer has current buffers name with \" exposed\" appended to
+Other buffer has current buffer's name with \" exposed\" appended to
it, unless optional second arg TOBUF is specified, in which case it is
used verbatim."
(interactive "P")
(allout-copy-exposed-to-buffer arg tobuf 'indent))
;;;_ - LaTeX formatting
-;;;_ > allout-latex-verb-quote (str &optional flow)
-(defun allout-latex-verb-quote (str &optional flow)
+;;;_ > allout-latex-verb-quote (string &optional flow)
+(defun allout-latex-verb-quote (string &optional flow)
"Return copy of STRING for literal reproduction across latex processing.
Expresses the original characters \(including carriage returns) of the
string across latex processing."
(concat "\\char" (number-to-string char) "{}"))
((= char ?\n) "\\\\")
(t (char-to-string char)))))
- str
+ string
""))
;;;_ > allout-latex-verbatim-quote-curr-line ()
(defun allout-latex-verbatim-quote-curr-line ()
(insert "\\")
(setq end (1+ end))
(goto-char (1+ (match-end 0))))))
-;;;_ > allout-insert-latex-header (buf)
-(defun allout-insert-latex-header (buf)
+;;;_ > allout-insert-latex-header (buffer)
+(defun allout-insert-latex-header (buffer)
"Insert initial latex commands at point in BUFFER."
;; Much of this is being derived from the stuff in appendix of E in
;; the TeXBook, pg 421.
- (set-buffer buf)
+ (set-buffer buffer)
(let ((doc-style (format "\n\\documentstyle{%s}\n"
"report"))
(page-numbering (if allout-number-pages
hoffset
vspace)
)))
-;;;_ > allout-insert-latex-trailer (buf)
-(defun allout-insert-latex-trailer (buf)
+;;;_ > allout-insert-latex-trailer (buffer)
+(defun allout-insert-latex-trailer (buffer)
"Insert concluding latex commands at point in BUFFER."
- (set-buffer buf)
+ (set-buffer buffer)
(insert "\n\\end{document}\n"))
;;;_ > allout-latexify-one-item (depth prefix bullet text)
(defun allout-latexify-one-item (depth prefix bullet text)
(cons function (symbol-value hook)))))))
;;;_ : my-mark-marker to accommodate divergent emacsen:
(defun my-mark-marker (&optional force buffer)
- "Accommodate the different signature for mark-marker across emacsen.
+ "Accommodate the different signature for mark-marker across Emacsen.
-GNU XEmacs takes two optional args, while mainline GNU Emacs does not,
+XEmacs takes two optional args, while GNU Emacs does not,
so pass them along when appropriate."
(if (featurep 'xemacs)
(mark-marker force buffer)
HCoop / bpt / emacs.git / blobdiff