1 ;;; allout.el --- extensive outline mode for use alone and with other modes
3 ;; Copyright (C) 1992, 1993, 1994, 2001, 2002, 2003, 2004, 2005, 2006,
4 ;; 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
6 ;; Author: Ken Manheimer <ken dot manheimer at gmail dot com>
7 ;; Maintainer: Ken Manheimer <ken dot manheimer at gmail dot com>
8 ;; Created: Dec 1991 -- first release to usenet
10 ;; Keywords: outlines wp languages
11 ;; Website: http://myriadicity.net/Sundry/EmacsAllout
13 ;; This file is part of GNU Emacs.
15 ;; GNU Emacs is free software: you can redistribute it and/or modify
16 ;; it under the terms of the GNU General Public License as published by
17 ;; the Free Software Foundation, either version 3 of the License, or
18 ;; (at your option) any later version.
20 ;; GNU Emacs is distributed in the hope that it will be useful,
21 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
22 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 ;; GNU General Public License for more details.
25 ;; You should have received a copy of the GNU General Public License
26 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
30 ;; Allout outline minor mode provides extensive outline formatting and
31 ;; and manipulation beyond standard emacs outline mode. Some features:
33 ;; - Classic outline-mode topic-oriented navigation and exposure adjustment
34 ;; - Topic-oriented editing including coherent topic and subtopic
35 ;; creation, promotion, demotion, cut/paste across depths, etc.
36 ;; - Incremental search with dynamic exposure and reconcealment of text
37 ;; - Customizable bullet format -- enables programming-language specific
38 ;; outlining, for code-folding editing. (Allout code itself is to try it;
39 ;; formatted as an outline -- do ESC-x eval-buffer in allout.el; but
40 ;; emacs local file variables need to be enabled when the
41 ;; file was visited -- see `enable-local-variables'.)
42 ;; - Configurable per-file initial exposure settings
43 ;; - Symmetric-key and key-pair topic encryption, plus symmetric passphrase
44 ;; mnemonic support, with verification against an established passphrase
45 ;; (using a stashed encrypted dummy string) and user-supplied hint
46 ;; maintenance. Encryption is via the Emacs 'epg' library. See
47 ;; allout-toggle-current-subtree-encryption docstring.
48 ;; - Automatic topic-number maintenance
49 ;; - "Hot-spot" operation, for single-keystroke maneuvering and
50 ;; exposure control (see the allout-mode docstring)
51 ;; - Easy rendering of exposed portions into numbered, latex, indented, etc
53 ;; - Careful attention to whitespace -- enabling blank lines between items
54 ;; and maintenance of hanging indentation (in paragraph auto-fill and
55 ;; across topic promotion and demotion) of topic bodies consistent with
56 ;; indentation of their topic header.
60 ;; See the `allout-mode' function's docstring for an introduction to the
63 ;; The latest development version and helpful notes are available at
64 ;; http://myriadicity.net/Sundry/EmacsAllout .
66 ;; The outline menubar additions provide quick reference to many of
67 ;; the features, and see the docstring of the variable `allout-init'
68 ;; for instructions on priming your Emacs session for automatic
69 ;; activation of allout-mode.
71 ;; See the docstring of the variables `allout-layout' and
72 ;; `allout-auto-activation' for details on automatic activation of
73 ;; `allout-mode' as a minor mode. (It has changed since allout
74 ;; 3.x, for those of you that depend on the old method.)
76 ;; Note -- the lines beginning with `;;;_' are outline topic headers.
77 ;; Just `ESC-x eval-buffer' to give it a whirl.
79 ;; ken manheimer (ken dot manheimer at gmail dot com)
83 ;;;_* Dependency autoloads
86 ;; Most of the requires here are for stuff covered by autoloads, which
87 ;; byte-compiling doesn't trigger.
91 ;; `cl' is required for `assert'. `assert' is not covered by a standard
92 ;; autoload, but it is a macro, so that eval-when-compile is sufficient
93 ;; to byte-compile it in, or to do the require when the buffer evalled.
97 ;;;_* USER CUSTOMIZATION VARIABLES:
99 ;;;_ > defgroup allout, allout-keybindings
101 "Extensive outline mode for use alone and with other modes."
104 (defgroup allout-keybindings nil
105 "Allout outline mode keyboard bindings configuration."
108 ;;;_ + Layout, Mode, and Topic Header Configuration
110 (defvar allout-command-prefix) ; defined below
112 ;;;_ > allout-keybindings incidentals:
113 ;;;_ : internal key binding stuff - in this section for load-order.
114 ;;;_ = allout-mode-map
115 (defvar allout-mode-map 'allout-mode-map
116 "Keybindings place-holder for (allout) outline minor mode.
118 Do NOT set the value of this variable. Instead, customize
119 `allout-command-prefix', `allout-prefixed-keybindings', and
120 `allout-unprefixed-keybindings'.")
121 ;;;_ = allout-mode-map-value
122 (defvar allout-mode-map-value nil
123 "Keymap for allout outline minor mode.
125 Do NOT set the value of this variable. Instead, customize
126 `allout-command-prefix', `allout-prefixed-keybindings', and
127 `allout-unprefixed-keybindings'.")
128 ;;;_ = make allout-mode-map-value an alias for allout-mode-map:
129 ;; this needs to be revised when the value is changed, sigh.
130 (defalias 'allout-mode-map allout-mode-map-value)
131 ;;;_ > allout-compose-and-institute-keymap (&optional varname value)
132 (defun allout-compose-and-institute-keymap (&optional varname value)
133 "Create the allout keymap according to the keybinding specs, and set it.
135 Useful standalone or to effect customizations of the
136 respective allout-mode keybinding variables, `allout-command-prefix',
137 `allout-prefixed-keybindings', and `allout-unprefixed-keybindings'"
138 ;; Set the customization variable, if any:
140 (set-default varname value))
141 (let ((map (make-sparse-keymap)))
142 (when (boundp 'allout-prefixed-keybindings)
143 ;; tolerate first definitions of the variables:
144 (dolist (entry allout-prefixed-keybindings)
146 ;; XXX vector vs non-vector key descriptions?
147 (vconcat allout-command-prefix
148 (car (read-from-string (car entry))))
150 (when (boundp 'allout-unprefixed-keybindings)
151 (dolist (entry allout-unprefixed-keybindings)
152 (define-key map (car (read-from-string (car entry))) (cadr entry))))
153 (substitute-key-definition 'beginning-of-line 'allout-beginning-of-line
155 (substitute-key-definition 'move-beginning-of-line 'allout-beginning-of-line
157 (substitute-key-definition 'end-of-line 'allout-end-of-line
159 (substitute-key-definition 'move-end-of-line 'allout-end-of-line
161 (allout-institute-keymap map)))
162 ;;;_ > allout-institute-keymap (map)
163 (defun allout-institute-keymap (map)
164 "Associate allout-mode bindings with allout as a minor mode."
166 ;; allout-mode-map var is a keymap by virtue of being a defalias for
167 ;; allout-mode-map-value, which has the actual keymap value.
168 ;; allout-mode-map's symbol value is just 'allout-mode-map, so it can be
169 ;; used in minor-mode-map-alist to indirect to the actual
170 ;; allout-mode-map-var value, which can be adjusted and reassigned.
172 ;; allout-mode-map-value for keymap reference in various places:
173 (setq allout-mode-map-value map)
174 ;; the function value keymap of allout-mode-map is used in
175 ;; minor-mode-map-alist - update it:
176 (fset allout-mode-map allout-mode-map-value))
177 ;;;_ * intialize the mode map:
178 ;; ensure that allout-mode-map has some setting even if allout-mode hasn't
180 (allout-compose-and-institute-keymap)
181 ;;;_ = allout-command-prefix
182 (defcustom allout-command-prefix "\C-c "
183 "Key sequence to be used as prefix for outline mode command key bindings.
185 Default is '\C-c<space>'; just '\C-c' is more short-and-sweet, if you're
186 willing to let allout use a bunch of \C-c keybindings."
188 :group 'allout-keybindings
189 :set 'allout-compose-and-institute-keymap)
190 ;;;_ = allout-keybindings-binding
191 (define-widget 'allout-keybindings-binding 'lazy
192 "Structure of allout keybindings customization items."
194 (list (string :tag "Key" :value "[(meta control shift ?f)]")
195 (function :tag "Function name"
196 :value allout-forward-current-level))))
197 ;;;_ = allout-prefixed-keybindings
198 (defcustom allout-prefixed-keybindings
199 '(("[(control ?n)]" allout-next-visible-heading)
200 ("[(control ?p)]" allout-previous-visible-heading)
201 ("[(control ?u)]" allout-up-current-level)
202 ("[(control ?f)]" allout-forward-current-level)
203 ("[(control ?b)]" allout-backward-current-level)
204 ("[(control ?a)]" allout-beginning-of-current-entry)
205 ("[(control ?e)]" allout-end-of-entry)
206 ("[(control ?i)]" allout-show-children)
207 ("[(control ?s)]" allout-show-current-subtree)
208 ("[(control ?t)]" allout-toggle-current-subtree-exposure)
209 ;; Let user customize if they want to preempt describe-prefix-bindings ^h use.
210 ;; ("[(control ?h)]" allout-hide-current-subtree)
211 ("[?h]" allout-hide-current-subtree)
212 ("[(control ?o)]" allout-show-current-entry)
213 ("[?!]" allout-show-all)
214 ("[?x]" allout-toggle-current-subtree-encryption)
215 ("[? ]" allout-open-sibtopic)
216 ("[?.]" allout-open-subtopic)
217 ("[?,]" allout-open-supertopic)
218 ("[?']" allout-shift-in)
219 ("[?>]" allout-shift-in)
220 ("[?<]" allout-shift-out)
221 ("[(control ?m)]" allout-rebullet-topic)
222 ("[?*]" allout-rebullet-current-heading)
223 ("[?#]" allout-number-siblings)
224 ("[(control ?k)]" allout-kill-topic)
225 ("[(meta ?k)]" allout-copy-topic-as-kill)
226 ("[?@]" allout-resolve-xref)
227 ("[?=?c]" allout-copy-exposed-to-buffer)
228 ("[?=?i]" allout-indented-exposed-to-buffer)
229 ("[?=?t]" allout-latexify-exposed)
230 ("[?=?p]" allout-flatten-exposed-to-buffer)
232 "Allout-mode key bindings that are prefixed with `allout-command-prefix'.
234 See `allout-unprefixed-keybindings' for the list of keybindings
235 that are not prefixed.
237 Use vector format for the keys:
238 - put literal keys after a '?' question mark, eg: '?a', '?.'
239 - enclose control, shift, or meta-modified keys as sequences within
240 parentheses, with the literal key, as above, preceded by the name(s)
241 of the modifers, eg: [(control ?a)]
242 See the existing keys for examples.
244 Functions can be bound to multiple keys, but binding keys to
245 multiple functions will not work - the last binding for a key
247 :type 'allout-keybindings-binding
248 :group 'allout-keybindings
249 :set 'allout-compose-and-institute-keymap
251 ;;;_ = allout-unprefixed-keybindings
252 (defcustom allout-unprefixed-keybindings
253 '(("[(control ?k)]" allout-kill-line)
254 ("[(meta ?k)]" allout-copy-line-as-kill)
255 ("[(control ?y)]" allout-yank)
256 ("[(meta ?y)]" allout-yank-pop)
258 "Allout-mode functions bound to keys without any added prefix.
260 This is in contrast to the majority of allout-mode bindings on
261 `allout-prefixed-bindings', whose bindings are created with a
262 preceeding command key.
264 Use vector format for the keys:
265 - put literal keys after a '?' question mark, eg: '?a', '?.'
266 - enclose control, shift, or meta-modified keys as sequences within
267 parentheses, with the literal key, as above, preceded by the name(s)
268 of the modifers, eg: [(control ?a)]
269 See the existing keys for examples."
270 :type 'allout-keybindings-binding
271 :group 'allout-keybindings
272 :set 'allout-compose-and-institute-keymap
275 ;;;_ = allout-auto-activation
276 (defcustom allout-auto-activation nil
277 "Regulates auto-activation modality of allout outlines -- see `allout-init'.
279 Setq-default by `allout-init' to regulate whether or not allout
280 outline mode is automatically activated when the buffer-specific
281 variable `allout-layout' is non-nil, and whether or not the layout
282 dictated by `allout-layout' should be imposed on mode activation.
284 With value t, auto-mode-activation and auto-layout are enabled.
285 \(This also depends on `allout-find-file-hook' being installed in
286 `find-file-hook', which is also done by `allout-init'.)
288 With value `ask', auto-mode-activation is enabled, and endorsement for
289 performing auto-layout is asked of the user each time.
291 With value `activate', only auto-mode-activation is enabled,
294 With value nil, neither auto-mode-activation nor auto-layout are
297 See the docstring for `allout-init' for the proper interface to
299 :type '(choice (const :tag "On" t)
300 (const :tag "Ask about layout" "ask")
301 (const :tag "Mode only" "activate")
302 (const :tag "Off" nil))
304 ;;;_ = allout-default-layout
305 (defcustom allout-default-layout '(-2 : 0)
306 "Default allout outline layout specification.
308 This setting specifies the outline exposure to use when
309 `allout-layout' has the local value `t'. This docstring describes the
310 layout specifications.
312 A list value specifies a default layout for the current buffer,
313 to be applied upon activation of `allout-mode'. Any non-nil
314 value will automatically trigger `allout-mode', provided
315 `allout-init' has been called to enable this behavior.
317 The types of elements in the layout specification are:
319 INTEGER -- dictate the relative depth to open the corresponding topic(s),
321 -- negative numbers force the topic to be closed before opening
322 to the absolute value of the number, so all siblings are open
324 -- positive numbers open to the relative depth indicated by the
325 number, but do not force already opened subtopics to be closed.
326 -- 0 means to close topic -- hide all subitems.
327 : -- repeat spec -- apply the preceeding element to all siblings at
328 current level, *up to* those siblings that would be covered by specs
329 following the `:' on the list. Ie, apply to all topics at level but
330 trailing ones accounted for by trailing specs. (Only the first of
331 multiple colons at the same level is honored -- later ones are ignored.)
332 * -- completely exposes the topic, including bodies
333 + -- exposes all subtopics, but not the bodies
334 - -- exposes the body of the corresponding topic, but not subtopics
335 LIST -- a nested layout spec, to be applied intricately to its
336 corresponding item(s)
340 Collapse the top-level topics to show their children and
341 grandchildren, but completely collapse the final top-level topic.
343 Close the first topic so only the immediate subtopics are shown,
344 leave the subsequent topics exposed as they are until the second
345 second to last topic, which is exposed at least one level, and
346 completely close the last topic.
348 Expose children and grandchildren of all topics at current
349 level except the last two; expose children of the second to
350 last and completely expose the last one, including its subtopics.
352 See `allout-expose-topic' for more about the exposure process.
354 Also, allout's mode-specific provisions will make topic prefixes default
355 to the comment-start string, if any, of the language of the file. This
356 is modulo the setting of `allout-use-mode-specific-leader', which see."
357 :type 'allout-layout-type
359 ;;;_ : allout-layout-type
360 (define-widget 'allout-layout-type 'lazy
361 "Allout layout format customization basic building blocks."
363 (choice (integer :tag "integer (<= zero is strict)")
364 (const :tag ": (repeat prior)" :)
365 (const :tag "* (completely expose)" *)
366 (const :tag "+ (expose all offspring, headlines only)" +)
367 (const :tag "- (expose topic body but not offspring)" -)
368 (allout-layout-type :tag "<Nested layout>"))))
370 ;;;_ = allout-inhibit-auto-fill
371 (defcustom allout-inhibit-auto-fill nil
372 "If non-nil, auto-fill will be inhibited in the allout buffers.
374 You can customize this setting to set it for all allout buffers, or set it
375 in individual buffers if you want to inhibit auto-fill only in particular
376 buffers. (You could use a function on `allout-mode-hook' to inhibit
377 auto-fill according, eg, to the major mode.)
379 If you don't set this and auto-fill-mode is enabled, allout will use the
380 value that `normal-auto-fill-function', if any, when allout mode starts, or
381 else allout's special hanging-indent maintaining auto-fill function,
385 (make-variable-buffer-local 'allout-inhibit-auto-fill)
386 ;;;_ = allout-use-hanging-indents
387 (defcustom allout-use-hanging-indents t
388 "If non-nil, topic body text auto-indent defaults to indent of the header.
389 Ie, it is indented to be just past the header prefix. This is
390 relevant mostly for use with `indented-text-mode', or other situations
391 where auto-fill occurs."
394 (make-variable-buffer-local 'allout-use-hanging-indents)
396 (put 'allout-use-hanging-indents 'safe-local-variable
397 (if (fboundp 'booleanp) 'booleanp '(lambda (x) (member x '(t nil)))))
398 ;;;_ = allout-reindent-bodies
399 (defcustom allout-reindent-bodies (if allout-use-hanging-indents
401 "Non-nil enables auto-adjust of topic body hanging indent with depth shifts.
403 When active, topic body lines that are indented even with or beyond
404 their topic header are reindented to correspond with depth shifts of
407 A value of t enables reindent in non-programming-code buffers, ie
408 those that do not have the variable `comment-start' set. A value of
409 `force' enables reindent whether or not `comment-start' is set."
410 :type '(choice (const nil) (const t) (const text) (const force))
413 (make-variable-buffer-local 'allout-reindent-bodies)
415 (put 'allout-reindent-bodies 'safe-local-variable
416 '(lambda (x) (memq x '(nil t text force))))
418 ;;;_ = allout-show-bodies
419 (defcustom allout-show-bodies nil
420 "If non-nil, show entire body when exposing a topic, rather than
424 (make-variable-buffer-local 'allout-show-bodies)
426 (put 'allout-show-bodies 'safe-local-variable
427 (if (fboundp 'booleanp) 'booleanp '(lambda (x) (member x '(t nil)))))
429 ;;;_ = allout-beginning-of-line-cycles
430 (defcustom allout-beginning-of-line-cycles t
431 "If non-nil, \\[allout-beginning-of-line] will cycle through smart-placement options.
433 Cycling only happens on when the command is repeated, not when it
434 follows a different command.
436 Smart-placement means that repeated calls to this function will
439 - if the cursor is on a non-headline body line and not on the first column:
440 then it goes to the first column
441 - if the cursor is on the first column of a non-headline body line:
442 then it goes to the start of the headline within the item body
443 - if the cursor is on the headline and not the start of the headline:
444 then it goes to the start of the headline
445 - if the cursor is on the start of the headline:
446 then it goes to the bullet character (for hotspot navigation)
447 - if the cursor is on the bullet character:
448 then it goes to the first column of that line (the headline)
449 - if the cursor is on the first column of the headline:
450 then it goes to the start of the headline within the item body.
452 In this fashion, you can use the beginning-of-line command to do
453 its normal job and then, when repeated, advance through the
454 entry, cycling back to start.
456 If this configuration variable is nil, then the cursor is just
457 advanced to the beginning of the line and remains there on
459 :type 'boolean :group 'allout)
460 ;;;_ = allout-end-of-line-cycles
461 (defcustom allout-end-of-line-cycles t
462 "If non-nil, \\[allout-end-of-line] will cycle through smart-placement options.
464 Cycling only happens on when the command is repeated, not when it
465 follows a different command.
467 Smart placement means that repeated calls to this function will
470 - if the cursor is not on the end-of-line,
471 then it goes to the end-of-line
472 - if the cursor is on the end-of-line but not the end-of-entry,
473 then it goes to the end-of-entry, exposing it if necessary
474 - if the cursor is on the end-of-entry,
475 then it goes to the end of the head line
477 In this fashion, you can use the end-of-line command to do its
478 normal job and then, when repeated, advance through the entry,
479 cycling back to start.
481 If this configuration variable is nil, then the cursor is just
482 advanced to the end of the line and remains there on repeated
484 :type 'boolean :group 'allout)
486 ;;;_ = allout-header-prefix
487 (defcustom allout-header-prefix "."
488 ;; this string is treated as literal match. it will be `regexp-quote'd, so
489 ;; one cannot use regular expressions to match varying header prefixes.
490 "Leading string which helps distinguish topic headers.
492 Outline topic header lines are identified by a leading topic
493 header prefix, which mostly have the value of this var at their front.
494 Level 1 topics are exceptions. They consist of only a single
495 character, which is typically set to the `allout-primary-bullet'."
498 (make-variable-buffer-local 'allout-header-prefix)
500 (put 'allout-header-prefix 'safe-local-variable 'stringp)
501 ;;;_ = allout-primary-bullet
502 (defcustom allout-primary-bullet "*"
503 "Bullet used for top-level outline topics.
505 Outline topic header lines are identified by a leading topic header
506 prefix, which is concluded by bullets that includes the value of this
507 var and the respective allout-*-bullets-string vars.
509 The value of an asterisk (`*') provides for backwards compatibility
510 with the original Emacs outline mode. See `allout-plain-bullets-string'
511 and `allout-distinctive-bullets-string' for the range of available
515 (make-variable-buffer-local 'allout-primary-bullet)
517 (put 'allout-primary-bullet 'safe-local-variable 'stringp)
518 ;;;_ = allout-plain-bullets-string
519 (defcustom allout-plain-bullets-string ".,"
520 "The bullets normally used in outline topic prefixes.
522 See `allout-distinctive-bullets-string' for the other kind of
525 DO NOT include the close-square-bracket, `]', as a bullet.
527 Outline mode has to be reactivated in order for changes to the value
528 of this var to take effect."
531 (make-variable-buffer-local 'allout-plain-bullets-string)
533 (put 'allout-plain-bullets-string 'safe-local-variable 'stringp)
534 ;;;_ = allout-distinctive-bullets-string
535 (defcustom allout-distinctive-bullets-string "*+-=>()[{}&!?#%\"X@$~_\\:;^"
536 "Persistent outline header bullets used to distinguish special topics.
538 These bullets are distinguish topics with particular character.
539 They are not used by default in the topic creation routines, but
540 are offered as options when you modify topic creation with a
541 universal argument \(\\[universal-argument]), or during rebulleting \(\\[allout-rebullet-current-heading]).
543 Distinctive bullets are not cycled when topics are shifted or
544 otherwise automatically rebulleted, so their marking is
545 persistent until deliberately changed. Their significance is
546 purely by convention, however. Some conventions suggest
549 `(' - open paren -- an aside or incidental point
550 `?' - question mark -- uncertain or outright question
551 `!' - exclamation point/bang -- emphatic
552 `[' - open square bracket -- meta-note, about item instead of item's subject
553 `\"' - double quote -- a quotation or other citation
554 `=' - equal sign -- an assignment, some kind of definition
555 `^' - carat -- relates to something above
557 Some are more elusive, but their rationale may be recognizable:
559 `+' - plus -- pending consideration, completion
560 `_' - underscore -- done, completed
561 `&' - ampersand -- addendum, furthermore
563 \(Some other non-plain bullets have special meaning to the
564 software. By default:
566 `~' marks encryptable topics -- see `allout-topic-encryption-bullet'
567 `#' marks auto-numbered bullets -- see `allout-numbered-bullet'.)
569 See `allout-plain-bullets-string' for the standard, alternating
572 You must run `set-allout-regexp' in order for outline mode to
573 adopt changes of this value.
575 DO NOT include the close-square-bracket, `]', on either of the bullet
579 (make-variable-buffer-local 'allout-distinctive-bullets-string)
581 (put 'allout-distinctive-bullets-string 'safe-local-variable 'stringp)
583 ;;;_ = allout-use-mode-specific-leader
584 (defcustom allout-use-mode-specific-leader t
585 "When non-nil, use mode-specific topic-header prefixes.
587 Allout outline mode will use the mode-specific `allout-mode-leaders' or
588 comment-start string, if any, to lead the topic prefix string, so topic
589 headers look like comments in the programming language. It will also use
590 the comment-start string, with an '_' appended, for `allout-primary-bullet'.
592 String values are used as literals, not regular expressions, so
593 do not escape any regulare-expression characters.
595 Value t means to first check for assoc value in `allout-mode-leaders'
596 alist, then use comment-start string, if any, then use default (`.').
597 \(See note about use of comment-start strings, below.)
599 Set to the symbol for either of `allout-mode-leaders' or
600 `comment-start' to use only one of them, respectively.
602 Value nil means to always use the default (`.') and leave
603 `allout-primary-bullet' unaltered.
605 comment-start strings that do not end in spaces are tripled in
606 the header-prefix, and an `_' underscore is tacked on the end, to
607 distinguish them from regular comment strings. comment-start
608 strings that do end in spaces are not tripled, but an underscore
609 is substituted for the space. [This presumes that the space is
610 for appearance, not comment syntax. You can use
611 `allout-mode-leaders' to override this behavior, when
613 :type '(choice (const t) (const nil) string
614 (const allout-mode-leaders)
615 (const comment-start))
618 (put 'allout-use-mode-specific-leader 'safe-local-variable
619 '(lambda (x) (or (memq x '(t nil allout-mode-leaders comment-start))
621 ;;;_ = allout-mode-leaders
622 (defvar allout-mode-leaders '()
623 "Specific allout-prefix leading strings per major modes.
625 Use this if the mode's comment-start string isn't what you
626 prefer, or if the mode lacks a comment-start string. See
627 `allout-use-mode-specific-leader' for more details.
629 If you're constructing a string that will comment-out outline
630 structuring so it can be included in program code, append an extra
631 character, like an \"_\" underscore, to distinguish the lead string
632 from regular comments that start at the beginning-of-line.")
634 ;;;_ = allout-old-style-prefixes
635 (defcustom allout-old-style-prefixes nil
636 "When non-nil, use only old-and-crusty `outline-mode' `*' topic prefixes.
638 Non-nil restricts the topic creation and modification
639 functions to asterix-padded prefixes, so they look exactly
640 like the original Emacs-outline style prefixes.
642 Whatever the setting of this variable, both old and new style prefixes
643 are always respected by the topic maneuvering functions."
646 (make-variable-buffer-local 'allout-old-style-prefixes)
648 (put 'allout-old-style-prefixes 'safe-local-variable
649 (if (fboundp 'booleanp) 'booleanp '(lambda (x) (member x '(t nil)))))
650 ;;;_ = allout-stylish-prefixes -- alternating bullets
651 (defcustom allout-stylish-prefixes t
652 "Do fancy stuff with topic prefix bullets according to level, etc.
654 Non-nil enables topic creation, modification, and repositioning
655 functions to vary the topic bullet char (the char that marks the topic
656 depth) just preceding the start of the topic text) according to level.
657 Otherwise, only asterisks (`*') and distinctive bullets are used.
659 This is how an outline can look (but sans indentation) with stylish
664 . + One level 3 subtopic
665 . . One level 4 subtopic
666 . . A second 4 subtopic
667 . + Another level 3 subtopic
668 . #1 A numbered level 4 subtopic
670 . ! Another level 4 subtopic with a different distinctive bullet
671 . #4 And another numbered level 4 subtopic
673 This would be an outline with stylish prefixes inhibited (but the
674 numbered and other distinctive bullets retained):
678 . * One level 3 subtopic
679 . * One level 4 subtopic
680 . * A second 4 subtopic
681 . * Another level 3 subtopic
682 . #1 A numbered level 4 subtopic
684 . ! Another level 4 subtopic with a different distinctive bullet
685 . #4 And another numbered level 4 subtopic
687 Stylish and constant prefixes (as well as old-style prefixes) are
688 always respected by the topic maneuvering functions, regardless of
689 this variable setting.
691 The setting of this var is not relevant when `allout-old-style-prefixes'
695 (make-variable-buffer-local 'allout-stylish-prefixes)
697 (put 'allout-stylish-prefixes 'safe-local-variable
698 (if (fboundp 'booleanp) 'booleanp '(lambda (x) (member x '(t nil)))))
700 ;;;_ = allout-numbered-bullet
701 (defcustom allout-numbered-bullet "#"
702 "String designating bullet of topics that have auto-numbering; nil for none.
704 Topics having this bullet have automatic maintenance of a sibling
705 sequence-number tacked on, just after the bullet. Conventionally set
706 to \"#\", you can set it to a bullet of your choice. A nil value
707 disables numbering maintenance."
708 :type '(choice (const nil) string)
710 (make-variable-buffer-local 'allout-numbered-bullet)
712 (put 'allout-numbered-bullet 'safe-local-variable
713 (if (fboundp 'string-or-null-p)
715 '(lambda (x) (or (stringp x) (null x)))))
716 ;;;_ = allout-file-xref-bullet
717 (defcustom allout-file-xref-bullet "@"
718 "Bullet signifying file cross-references, for `allout-resolve-xref'.
720 Set this var to the bullet you want to use for file cross-references."
721 :type '(choice (const nil) string)
724 (put 'allout-file-xref-bullet 'safe-local-variable
725 (if (fboundp 'string-or-null-p)
727 '(lambda (x) (or (stringp x) (null x)))))
728 ;;;_ = allout-presentation-padding
729 (defcustom allout-presentation-padding 2
730 "Presentation-format white-space padding factor, for greater indent."
734 (make-variable-buffer-local 'allout-presentation-padding)
736 (put 'allout-presentation-padding 'safe-local-variable 'integerp)
738 ;;;_ = allout-abbreviate-flattened-numbering
739 (defcustom allout-abbreviate-flattened-numbering nil
740 "If non-nil, `allout-flatten-exposed-to-buffer' abbreviates topic
741 numbers to minimal amount with some context. Otherwise, entire
742 numbers are always used."
746 ;;;_ + LaTeX formatting
747 ;;;_ - allout-number-pages
748 (defcustom allout-number-pages nil
749 "Non-nil turns on page numbering for LaTeX formatting of an outline."
752 ;;;_ - allout-label-style
753 (defcustom allout-label-style "\\large\\bf"
754 "Font and size of labels for LaTeX formatting of an outline."
757 ;;;_ - allout-head-line-style
758 (defcustom allout-head-line-style "\\large\\sl "
759 "Font and size of entries for LaTeX formatting of an outline."
762 ;;;_ - allout-body-line-style
763 (defcustom allout-body-line-style " "
764 "Font and size of entries for LaTeX formatting of an outline."
767 ;;;_ - allout-title-style
768 (defcustom allout-title-style "\\Large\\bf"
769 "Font and size of titles for LaTeX formatting of an outline."
773 (defcustom allout-title '(or buffer-file-name (buffer-name))
774 "Expression to be evaluated to determine the title for LaTeX
778 ;;;_ - allout-line-skip
779 (defcustom allout-line-skip ".05cm"
780 "Space between lines for LaTeX formatting of an outline."
784 (defcustom allout-indent ".3cm"
785 "LaTeX formatted depth-indent spacing."
789 ;;;_ + Topic encryption
790 ;;;_ = allout-encryption group
791 (defgroup allout-encryption nil
792 "Settings for topic encryption features of allout outliner."
794 ;;;_ = allout-topic-encryption-bullet
795 (defcustom allout-topic-encryption-bullet "~"
796 "Bullet signifying encryption of the entry's body."
797 :type '(choice (const nil) string)
799 :group 'allout-encryption)
800 ;;;_ = allout-encrypt-unencrypted-on-saves
801 (defcustom allout-encrypt-unencrypted-on-saves t
802 "When saving, should topics pending encryption be encrypted?
804 The idea is to prevent file-system exposure of any un-encrypted stuff, and
805 mostly covers both deliberate file writes and auto-saves.
807 - Yes: encrypt all topics pending encryption, even if it's the one
808 currently being edited. (In that case, the currently edited topic
809 will be automatically decrypted before any user interaction, so they
810 can continue editing but the copy on the file system will be
812 Auto-saves will use the \"All except current topic\" mode if this
813 one is selected, to avoid practical difficulties -- see below.
814 - All except current topic: skip the topic currently being edited, even if
815 it's pending encryption. This may expose the current topic on the
816 file sytem, but avoids the nuisance of prompts for the encryption
817 passphrase in the middle of editing for, eg, autosaves.
818 This mode is used for auto-saves for both this option and \"Yes\".
819 - No: leave it to the user to encrypt any unencrypted topics.
821 For practical reasons, auto-saves always use the 'except-current policy
822 when auto-encryption is enabled. (Otherwise, spurious passphrase prompts
823 and unavoidable timing collisions are too disruptive.) If security for a
824 file requires that even the current topic is never auto-saved in the clear,
825 disable auto-saves for that file."
827 :type '(choice (const :tag "Yes" t)
828 (const :tag "All except current topic" except-current)
829 (const :tag "No" nil))
831 :group 'allout-encryption)
832 (make-variable-buffer-local 'allout-encrypt-unencrypted-on-saves)
835 ;;;_ = allout-developer group
836 (defgroup allout-developer nil
837 "Allout settings developers care about, including topic encryption and more."
839 ;;;_ = allout-run-unit-tests-on-load
840 (defcustom allout-run-unit-tests-on-load nil
841 "When non-nil, unit tests will be run at end of loading the allout module.
843 Generally, allout code developers are the only ones who'll want to set this.
845 \(If set, this makes it an even better practice to exercise changes by
846 doing byte-compilation with a repeat count, so the file is loaded after
849 See `allout-run-unit-tests' to see what's run."
851 :group 'allout-developer)
853 ;;;_ + Miscellaneous customization
855 ;;;_ = allout-enable-file-variable-adjustment
856 (defcustom allout-enable-file-variable-adjustment t
857 "If non-nil, some allout outline actions edit Emacs local file var text.
859 This can range from changes to existing entries, addition of new ones,
860 and creation of a new local variables section when necessary.
862 Emacs file variables adjustments are also inhibited if `enable-local-variables'
865 Operations potentially causing edits include allout encryption routines.
866 For details, see `allout-toggle-current-subtree-encryption's docstring."
869 (make-variable-buffer-local 'allout-enable-file-variable-adjustment)
871 ;;;_* CODE -- no user customizations below.
873 ;;;_ #1 Internal Outline Formatting and Configuration
875 ;;;_ = allout-version
876 (defvar allout-version "2.3"
877 "Version of currently loaded outline package. (allout.el)")
878 ;;;_ > allout-version
879 (defun allout-version (&optional here)
880 "Return string describing the loaded outline version."
882 (let ((msg (concat "Allout Outline Mode v " allout-version)))
883 (if here (insert msg))
886 ;;;_ : Mode activation (defined here because it's referenced early)
888 (defvar allout-mode nil "Allout outline mode minor-mode flag.")
889 (make-variable-buffer-local 'allout-mode)
890 ;;;_ = allout-layout nil
891 (defvar allout-layout nil ; LEAVE GLOBAL VALUE NIL -- see docstring.
892 "Buffer-specific setting for allout layout.
894 In buffers where this is non-nil (and if `allout-init' has been run, to
895 enable this behavior), `allout-mode' will be automatically activated. The
896 layout dictated by the value will be used to set the initial exposure when
897 `allout-mode' is activated.
899 \*You should not setq-default this variable non-nil unless you want every
900 visited file to be treated as an allout file.*
902 The value would typically be set by a file local variable. For
903 example, the following lines at the bottom of an Emacs Lisp file:
906 ;;;allout-layout: (0 : -1 -1 0)
909 dictate activation of `allout-mode' mode when the file is visited
910 \(presuming allout-init was already run), followed by the
911 equivalent of `(allout-expose-topic 0 : -1 -1 0)'. (This is
912 the layout used for the allout.el source file.)
914 `allout-default-layout' describes the specification format.
915 `allout-layout' can additionally have the value `t', in which
916 case the value of `allout-default-layout' is used.")
917 (make-variable-buffer-local 'allout-layout)
919 (put 'allout-layout 'safe-local-variable
920 '(lambda (x) (or (numberp x) (listp x) (memq x '(: * + -)))))
922 ;;;_ : Topic header format
924 (defvar allout-regexp ""
925 "*Regular expression to match the beginning of a heading line.
927 Any line whose beginning matches this regexp is considered a
928 heading. This var is set according to the user configuration vars
929 by `set-allout-regexp'.")
930 (make-variable-buffer-local 'allout-regexp)
931 ;;;_ = allout-bullets-string
932 (defvar allout-bullets-string ""
933 "A string dictating the valid set of outline topic bullets.
935 This var should *not* be set by the user -- it is set by `set-allout-regexp',
936 and is produced from the elements of `allout-plain-bullets-string'
937 and `allout-distinctive-bullets-string'.")
938 (make-variable-buffer-local 'allout-bullets-string)
939 ;;;_ = allout-bullets-string-len
940 (defvar allout-bullets-string-len 0
941 "Length of current buffers' `allout-plain-bullets-string'.")
942 (make-variable-buffer-local 'allout-bullets-string-len)
943 ;;;_ = allout-depth-specific-regexp
944 (defvar allout-depth-specific-regexp ""
945 "*Regular expression to match a heading line prefix for a particular depth.
947 This expression is used to search for depth-specific topic
948 headers at depth 2 and greater. Use `allout-depth-one-regexp'
949 for to seek topics at depth one.
951 This var is set according to the user configuration vars by
952 `set-allout-regexp'. It is prepared with format strings for two
953 decimal numbers, which should each be one less than the depth of the
954 topic prefix to be matched.")
955 (make-variable-buffer-local 'allout-depth-specific-regexp)
956 ;;;_ = allout-depth-one-regexp
957 (defvar allout-depth-one-regexp ""
958 "*Regular expression to match a heading line prefix for depth one.
960 This var is set according to the user configuration vars by
961 `set-allout-regexp'. It is prepared with format strings for two
962 decimal numbers, which should each be one less than the depth of the
963 topic prefix to be matched.")
964 (make-variable-buffer-local 'allout-depth-one-regexp)
965 ;;;_ = allout-line-boundary-regexp
966 (defvar allout-line-boundary-regexp ()
967 "`allout-regexp' prepended with a newline for the search target.
969 This is properly set by `set-allout-regexp'.")
970 (make-variable-buffer-local 'allout-line-boundary-regexp)
971 ;;;_ = allout-bob-regexp
972 (defvar allout-bob-regexp ()
973 "Like `allout-line-boundary-regexp', for headers at beginning of buffer.")
974 (make-variable-buffer-local 'allout-bob-regexp)
975 ;;;_ = allout-header-subtraction
976 (defvar allout-header-subtraction (1- (length allout-header-prefix))
977 "Allout-header prefix length to subtract when computing topic depth.")
978 (make-variable-buffer-local 'allout-header-subtraction)
979 ;;;_ = allout-plain-bullets-string-len
980 (defvar allout-plain-bullets-string-len (length allout-plain-bullets-string)
981 "Length of `allout-plain-bullets-string', updated by `set-allout-regexp'.")
982 (make-variable-buffer-local 'allout-plain-bullets-string-len)
984 ;;;_ = allout-doublecheck-at-and-shallower
985 (defconst allout-doublecheck-at-and-shallower 3
986 "Validate apparent topics of this depth and shallower as being non-aberrant.
988 Verified with `allout-aberrant-container-p'. The usefulness of
989 this check is limited to shallow depths, because the
990 determination of aberrance is according to the mistaken item
991 being followed by a legitimate item of excessively greater depth.
993 The classic example of a mistaken item, for a standard allout
994 outline configuration, is a body line that begins with an '...'
995 ellipsis. This happens to contain a legitimate depth-2 header
996 prefix, constituted by two '..' dots at the beginning of the
997 line. The only thing that can distinguish it *in principle* from
998 a legitimate one is if the following real header is at a depth
999 that is discontinuous from the depth of 2 implied by the
1000 ellipsis, ie depth 4 or more. As the depth being tested gets
1001 greater, the likelihood of this kind of disqualification is
1002 lower, and the usefulness of this test is lower.
1004 Extending the depth of the doublecheck increases the amount it is
1005 applied, increasing the cost of the test - on casual estimation,
1006 for outlines with many deep topics, geometrically (O(n)?).
1007 Taken together with decreasing likelihood that the test will be
1008 useful at greater depths, more modest doublecheck limits are more
1009 suitably economical.")
1010 ;;;_ X allout-reset-header-lead (header-lead)
1011 (defun allout-reset-header-lead (header-lead)
1012 "Reset the leading string used to identify topic headers."
1013 (interactive "sNew lead string: ")
1014 (setq allout-header-prefix header-lead)
1015 (setq allout-header-subtraction (1- (length allout-header-prefix)))
1016 (set-allout-regexp))
1017 ;;;_ X allout-lead-with-comment-string (header-lead)
1018 (defun allout-lead-with-comment-string (&optional header-lead)
1019 "Set the topic-header leading string to specified string.
1021 Useful when for encapsulating outline structure in programming
1022 language comments. Returns the leading string."
1025 (if (not (stringp header-lead))
1026 (setq header-lead (read-string
1027 "String prefix for topic headers: ")))
1028 (setq allout-reindent-bodies nil)
1029 (allout-reset-header-lead header-lead)
1031 ;;;_ > allout-infer-header-lead-and-primary-bullet ()
1032 (defun allout-infer-header-lead-and-primary-bullet ()
1033 "Determine appropriate `allout-header-prefix' and `allout-primary-bullet'.
1035 Works according to settings of:
1038 `allout-header-prefix' (default)
1039 `allout-use-mode-specific-leader'
1040 and `allout-mode-leaders'.
1042 Apply this via (re)activation of `allout-mode', rather than
1043 invoking it directly."
1044 (let* ((use-leader (and (boundp 'allout-use-mode-specific-leader)
1045 (if (or (stringp allout-use-mode-specific-leader)
1046 (memq allout-use-mode-specific-leader
1047 '(allout-mode-leaders
1050 allout-use-mode-specific-leader
1051 ;; Oops -- garbled value, equate with effect of t:
1055 ((not use-leader) nil)
1056 ;; Use the explicitly designated leader:
1057 ((stringp use-leader) use-leader)
1058 (t (or (and (memq use-leader '(t allout-mode-leaders))
1059 ;; Get it from outline mode leaders?
1060 (cdr (assq major-mode allout-mode-leaders)))
1061 ;; ... didn't get from allout-mode-leaders...
1062 (and (memq use-leader '(t comment-start))
1064 ;; Use comment-start, maybe tripled, and with
1068 (substring comment-start
1069 (1- (length comment-start))))
1070 ;; Use comment-start, sans trailing space:
1071 (substring comment-start 0 -1)
1072 (concat comment-start comment-start comment-start))
1073 ;; ... and append underscore, whichever:
1077 (setq allout-header-prefix leader)
1078 (if (not allout-old-style-prefixes)
1079 ;; setting allout-primary-bullet makes the top level topics use --
1080 ;; actually, be -- the special prefix:
1081 (setq allout-primary-bullet leader))
1082 allout-header-prefix)))
1083 (defalias 'allout-infer-header-lead
1084 'allout-infer-header-lead-and-primary-bullet)
1085 ;;;_ > allout-infer-body-reindent ()
1086 (defun allout-infer-body-reindent ()
1087 "Determine proper setting for `allout-reindent-bodies'.
1089 Depends on default setting of `allout-reindent-bodies' (which see)
1090 and presence of setting for `comment-start', to tell whether the
1091 file is programming code."
1092 (if (and allout-reindent-bodies
1094 (not (eq 'force allout-reindent-bodies)))
1095 (setq allout-reindent-bodies nil)))
1096 ;;;_ > set-allout-regexp ()
1097 (defun set-allout-regexp ()
1098 "Generate proper topic-header regexp form for outline functions.
1100 Works with respect to `allout-plain-bullets-string' and
1101 `allout-distinctive-bullets-string'.
1103 Also refresh various data structures that hinge on the regexp."
1106 ;; Derive allout-bullets-string from user configured components:
1107 (setq allout-bullets-string "")
1108 (let ((strings (list 'allout-plain-bullets-string
1109 'allout-distinctive-bullets-string
1110 'allout-primary-bullet))
1117 (setq cur-len (length (setq cur-string (symbol-value (car strings)))))
1118 (while (< index cur-len)
1119 (setq cur-char (aref cur-string index))
1120 (setq allout-bullets-string
1121 (concat allout-bullets-string
1123 ; Single dash would denote a
1124 ; sequence, repeated denotes
1126 ((eq cur-char ?-) "--")
1127 ; literal close-square-bracket
1128 ; doesn't work right in the
1130 ((eq cur-char ?\]) "")
1131 (t (regexp-quote (char-to-string cur-char))))))
1132 (setq index (1+ index)))
1133 (setq strings (cdr strings)))
1135 ;; Derive next for repeated use in allout-pending-bullet:
1136 (setq allout-plain-bullets-string-len (length allout-plain-bullets-string))
1137 (setq allout-header-subtraction (1- (length allout-header-prefix)))
1139 (let (new-part old-part formfeed-part)
1140 (setq new-part (concat "\\("
1141 (regexp-quote allout-header-prefix)
1143 ;; already regexp-quoted in a custom way:
1144 "[" allout-bullets-string "]"
1146 old-part (concat "\\("
1147 (regexp-quote allout-primary-bullet)
1149 (regexp-quote allout-header-prefix)
1152 " ?[^" allout-primary-bullet "]")
1153 formfeed-part "\\(\^L\\)"
1155 allout-regexp (concat new-part
1161 allout-line-boundary-regexp (concat "\n" new-part
1167 allout-bob-regexp (concat "\\`" new-part
1174 (setq allout-depth-specific-regexp
1175 (concat "\\(^\\|\\`\\)"
1178 ;; new-style spacers-then-bullet string:
1180 (allout-format-quote (regexp-quote allout-header-prefix))
1182 "[" (allout-format-quote allout-bullets-string) "]"
1185 ;; old-style all-bullets string, if primary not multi-char:
1186 (if (< 0 allout-header-subtraction)
1189 (allout-format-quote
1190 (regexp-quote allout-primary-bullet))
1191 (allout-format-quote
1192 (regexp-quote allout-primary-bullet))
1193 (allout-format-quote
1194 (regexp-quote allout-primary-bullet))
1196 ;; disqualify greater depths:
1198 (allout-format-quote allout-primary-bullet)
1203 (setq allout-depth-one-regexp
1204 (concat "\\(^\\|\\`\\)"
1208 (regexp-quote allout-header-prefix)
1209 ;; disqualify any bullet char following any amount of
1210 ;; intervening whitespace:
1212 (concat "[^ " allout-bullets-string "]")
1214 (if (< 0 allout-header-subtraction)
1215 ;; Need not support anything like the old
1216 ;; bullet style if the prefix is multi-char.
1219 (regexp-quote allout-primary-bullet)
1220 ;; disqualify deeper primary-bullet sequences:
1221 "[^" allout-primary-bullet "]"))
1225 (defvar allout-mode-exposure-menu)
1226 (defvar allout-mode-editing-menu)
1227 (defvar allout-mode-navigation-menu)
1228 (defvar allout-mode-misc-menu)
1229 (defun produce-allout-mode-menubar-entries ()
1231 (easy-menu-define allout-mode-exposure-menu
1232 allout-mode-map-value
1233 "Allout outline exposure menu."
1235 ["Show Entry" allout-show-current-entry t]
1236 ["Show Children" allout-show-children t]
1237 ["Show Subtree" allout-show-current-subtree t]
1238 ["Hide Subtree" allout-hide-current-subtree t]
1239 ["Hide Leaves" allout-hide-current-leaves t]
1241 ["Show All" allout-show-all t]))
1242 (easy-menu-define allout-mode-editing-menu
1243 allout-mode-map-value
1244 "Allout outline editing menu."
1246 ["Open Sibling" allout-open-sibtopic t]
1247 ["Open Subtopic" allout-open-subtopic t]
1248 ["Open Supertopic" allout-open-supertopic t]
1250 ["Shift Topic In" allout-shift-in t]
1251 ["Shift Topic Out" allout-shift-out t]
1252 ["Rebullet Topic" allout-rebullet-topic t]
1253 ["Rebullet Heading" allout-rebullet-current-heading t]
1254 ["Number Siblings" allout-number-siblings t]
1256 ["Toggle Topic Encryption"
1257 allout-toggle-current-subtree-encryption
1258 (> (allout-current-depth) 1)]))
1259 (easy-menu-define allout-mode-navigation-menu
1260 allout-mode-map-value
1261 "Allout outline navigation menu."
1263 ["Next Visible Heading" allout-next-visible-heading t]
1264 ["Previous Visible Heading"
1265 allout-previous-visible-heading t]
1267 ["Up Level" allout-up-current-level t]
1268 ["Forward Current Level" allout-forward-current-level t]
1269 ["Backward Current Level"
1270 allout-backward-current-level t]
1272 ["Beginning of Entry"
1273 allout-beginning-of-current-entry t]
1274 ["End of Entry" allout-end-of-entry t]
1275 ["End of Subtree" allout-end-of-current-subtree t]))
1276 (easy-menu-define allout-mode-misc-menu
1277 allout-mode-map-value
1278 "Allout outlines miscellaneous bindings."
1280 ["Version" allout-version t]
1282 ["Duplicate Exposed" allout-copy-exposed-to-buffer t]
1283 ["Duplicate Exposed, numbered"
1284 allout-flatten-exposed-to-buffer t]
1285 ["Duplicate Exposed, indented"
1286 allout-indented-exposed-to-buffer t]
1288 ["Set Header Lead" allout-reset-header-lead t]
1289 ["Set New Exposure" allout-expose-topic t])))
1290 ;;;_ : Allout Modal-Variables Utilities
1291 ;;;_ = allout-mode-prior-settings
1292 (defvar allout-mode-prior-settings nil
1293 "Internal `allout-mode' use; settings to be resumed on mode deactivation.
1295 See `allout-add-resumptions' and `allout-do-resumptions'.")
1296 (make-variable-buffer-local 'allout-mode-prior-settings)
1297 ;;;_ > allout-add-resumptions (&rest pairs)
1298 (defun allout-add-resumptions (&rest pairs)
1299 "Set name/value PAIRS.
1301 Old settings are preserved for later resumption using `allout-do-resumptions'.
1303 The new values are set as a buffer local. On resumption, the prior buffer
1304 scope of the variable is restored along with its value. If it was a void
1305 buffer-local value, then it is left as nil on resumption.
1307 The pairs are lists whose car is the name of the variable and car of the
1308 cdr is the new value: '(some-var some-value)'. The pairs can actually be
1309 triples, where the third element qualifies the disposition of the setting,
1310 as described further below.
1312 If the optional third element is the symbol 'extend, then the new value
1313 created by `cons'ing the second element of the pair onto the front of the
1316 If the optional third element is the symbol 'append, then the new value is
1317 extended from the existing one by `append'ing a list containing the second
1318 element of the pair onto the end of the existing value.
1320 Extension, and resumptions in general, should not be used for hook
1321 functions -- use the 'local mode of `add-hook' for that, instead.
1323 The settings are stored on `allout-mode-prior-settings'."
1325 (let* ((pair (pop pairs))
1328 (qualifier (if (> (length pair) 2)
1331 (if (not (symbolp name))
1332 (error "Pair's name, %S, must be a symbol, not %s"
1333 name (type-of name)))
1334 (setq prior-value (condition-case nil
1336 (void-variable nil)))
1337 (when (not (assoc name allout-mode-prior-settings))
1338 ;; Not already added as a resumption, create the prior setting entry.
1339 (if (local-variable-p name (current-buffer))
1340 ;; is already local variable -- preserve the prior value:
1341 (push (list name prior-value) allout-mode-prior-settings)
1342 ;; wasn't local variable, indicate so for resumption by killing
1343 ;; local value, and make it local:
1344 (push (list name) allout-mode-prior-settings)
1345 (make-local-variable name)))
1347 (cond ((eq qualifier 'extend)
1348 (if (not (listp prior-value))
1349 (error "extension of non-list prior value attempted")
1350 (set name (cons value prior-value))))
1351 ((eq qualifier 'append)
1352 (if (not (listp prior-value))
1353 (error "appending of non-list prior value attempted")
1354 (set name (append prior-value (list value)))))
1355 (t (error "unrecognized setting qualifier `%s' encountered"
1357 (set name value)))))
1358 ;;;_ > allout-do-resumptions ()
1359 (defun allout-do-resumptions ()
1360 "Resume all name/value settings registered by `allout-add-resumptions'.
1362 This is used when concluding allout-mode, to resume selected variables to
1363 their settings before allout-mode was started."
1365 (while allout-mode-prior-settings
1366 (let* ((pair (pop allout-mode-prior-settings))
1368 (value-cell (cdr pair)))
1369 (if (not value-cell)
1370 ;; Prior value was global:
1371 (kill-local-variable name)
1372 ;; Prior value was explicit:
1373 (set name (car value-cell))))))
1374 ;;;_ : Mode-specific incidentals
1375 ;;;_ > allout-unprotected (expr)
1376 (defmacro allout-unprotected (expr)
1377 "Enable internal outline operations to alter invisible text."
1378 `(let ((inhibit-read-only (if (not buffer-read-only) t))
1379 (inhibit-field-text-motion t))
1381 ;;;_ = allout-mode-hook
1382 (defvar allout-mode-hook nil
1383 "*Hook that's run when allout mode starts.")
1384 ;;;_ = allout-mode-deactivate-hook
1385 (defvar allout-mode-deactivate-hook nil
1386 "*Hook that's run when allout mode ends.")
1387 (define-obsolete-variable-alias 'allout-mode-deactivate-hook
1388 'allout-mode-off-hook "future")
1389 ;;;_ = allout-exposure-category
1390 (defvar allout-exposure-category nil
1391 "Symbol for use as allout invisible-text overlay category.")
1392 ;;;_ = allout-exposure-change-hook
1393 (defvar allout-exposure-change-hook nil
1394 "*Hook that's run after allout outline subtree exposure changes.
1396 It is run at the conclusion of `allout-flag-region'.
1398 Functions on the hook must take three arguments:
1400 - FROM -- integer indicating the point at the start of the change.
1401 - TO -- integer indicating the point of the end of the change.
1402 - FLAG -- change mode: nil for exposure, otherwise concealment.
1404 This hook might be invoked multiple times by a single command.")
1405 ;;;_ = allout-structure-added-hook
1406 (defvar allout-structure-added-hook nil
1407 "*Hook that's run after addition of items to the outline.
1409 Functions on the hook should take two arguments:
1411 - NEW-START -- integer indicating position of start of the first new item.
1412 - NEW-END -- integer indicating position of end of the last new item.
1414 This hook might be invoked multiple times by a single command.")
1415 ;;;_ = allout-structure-deleted-hook
1416 (defvar allout-structure-deleted-hook nil
1417 "*Hook that's run after disciplined deletion of subtrees from the outline.
1419 Functions on the hook must take two arguments:
1421 - DEPTH -- integer indicating the depth of the subtree that was deleted.
1422 - REMOVED-FROM -- integer indicating the point where the subtree was removed.
1424 Some edits that remove or invalidate items may missed by this hook:
1425 specifically edits that native allout routines do not control.
1427 This hook might be invoked multiple times by a single command.")
1428 ;;;_ = allout-structure-shifted-hook
1429 (defvar allout-structure-shifted-hook nil
1430 "*Hook that's run after shifting of items in the outline.
1432 Functions on the hook should take two arguments:
1434 - DEPTH-CHANGE -- integer indicating depth increase, negative for decrease
1435 - START -- integer indicating the start point of the shifted parent item.
1437 Some edits that shift items can be missed by this hook: specifically edits
1438 that native allout routines do not control.
1440 This hook might be invoked multiple times by a single command.")
1441 ;;;_ = allout-outside-normal-auto-fill-function
1442 (defvar allout-outside-normal-auto-fill-function nil
1443 "Value of normal-auto-fill-function outside of allout mode.
1445 Used by allout-auto-fill to do the mandated normal-auto-fill-function
1446 wrapped within allout's automatic fill-prefix setting.")
1447 (make-variable-buffer-local 'allout-outside-normal-auto-fill-function)
1448 ;;;_ = prevent redundant activation by desktop mode:
1449 (add-to-list 'desktop-minor-mode-handlers '(allout-mode . nil))
1450 ;;;_ = allout-passphrase-verifier-string
1451 (defvar allout-passphrase-verifier-string nil
1452 "Setting used to test solicited encryption passphrases against the one
1453 already associated with a file.
1455 It consists of an encrypted random string useful only to verify that a
1456 passphrase entered by the user is effective for decryption. The passphrase
1457 itself is \*not* recorded in the file anywhere, and the encrypted contents
1458 are random binary characters to avoid exposing greater susceptibility to
1461 The verifier string is retained as an Emacs file variable, as well as in
1462 the Emacs buffer state, if file variable adjustments are enabled. See
1463 `allout-enable-file-variable-adjustment' for details about that.")
1464 (make-variable-buffer-local 'allout-passphrase-verifier-string)
1465 (make-obsolete 'allout-passphrase-verifier-string
1466 'allout-passphrase-verifier-string "23.3")
1468 (put 'allout-passphrase-verifier-string 'safe-local-variable 'stringp)
1469 ;;;_ = allout-passphrase-hint-string
1470 (defvar allout-passphrase-hint-string ""
1471 "Variable used to retain reminder string for file's encryption passphrase.
1473 See the description of `allout-passphrase-hint-handling' for details about how
1474 the reminder is deployed.
1476 The hint is retained as an Emacs file variable, as well as in the Emacs buffer
1477 state, if file variable adjustments are enabled. See
1478 `allout-enable-file-variable-adjustment' for details about that.")
1479 (make-variable-buffer-local 'allout-passphrase-hint-string)
1480 (setq-default allout-passphrase-hint-string "")
1481 (make-obsolete 'allout-passphrase-hint-string
1482 'allout-passphrase-hint-string "23.3")
1484 (put 'allout-passphrase-hint-string 'safe-local-variable 'stringp)
1485 ;;;_ = allout-after-save-decrypt
1486 (defvar allout-after-save-decrypt nil
1487 "Internal variable, is nil or has the value of two points:
1489 - the location of a topic to be decrypted after saving is done
1490 - where to situate the cursor after the decryption is performed
1492 This is used to decrypt the topic that was currently being edited, if it
1493 was encrypted automatically as part of a file write or autosave.")
1494 (make-variable-buffer-local 'allout-after-save-decrypt)
1495 ;;;_ = allout-encryption-plaintext-sanitization-regexps
1496 (defvar allout-encryption-plaintext-sanitization-regexps nil
1497 "List of regexps whose matches are removed from plaintext before encryption.
1499 This is for the sake of removing artifacts, like escapes, that are added on
1500 and not actually part of the original plaintext. The removal is done just
1501 prior to encryption.
1503 Entries must be symbols that are bound to the desired values.
1505 Each value can be a regexp or a list with a regexp followed by a
1506 substitution string. If it's just a regexp, all its matches are removed
1507 before the text is encrypted. If it's a regexp and a substitution, the
1508 substition is used against the regexp matches, a la `replace-match'.")
1509 (make-variable-buffer-local 'allout-encryption-text-removal-regexps)
1510 ;;;_ = allout-encryption-ciphertext-rejection-regexps
1511 (defvar allout-encryption-ciphertext-rejection-regexps nil
1512 "Variable for regexps matching plaintext to remove before encryption.
1514 This is used to detect strings in encryption results that would
1515 register as allout mode structural elements, for exmple, as a
1518 Entries must be symbols that are bound to the desired regexp values.
1520 Encryptions that result in matches will be retried, up to
1521 `allout-encryption-ciphertext-rejection-limit' times, after which
1522 an error is raised.")
1524 (make-variable-buffer-local 'allout-encryption-ciphertext-rejection-regexps)
1525 ;;;_ = allout-encryption-ciphertext-rejection-ceiling
1526 (defvar allout-encryption-ciphertext-rejection-ceiling 5
1527 "Limit on number of times encryption ciphertext is rejected.
1529 See `allout-encryption-ciphertext-rejection-regexps' for rejection reasons.")
1530 (make-variable-buffer-local 'allout-encryption-ciphertext-rejection-ceiling)
1531 ;;;_ > allout-mode-p ()
1532 ;; Must define this macro above any uses, or byte compilation will lack
1533 ;; proper def, if file isn't loaded -- eg, during emacs build!
1534 (defmacro allout-mode-p ()
1535 "Return t if `allout-mode' is active in current buffer."
1537 ;;;_ > allout-write-file-hook-handler ()
1538 (defun allout-write-file-hook-handler ()
1539 "Implement `allout-encrypt-unencrypted-on-saves' policy for file writes."
1541 (if (or (not (allout-mode-p))
1542 (not (boundp 'allout-encrypt-unencrypted-on-saves))
1543 (not allout-encrypt-unencrypted-on-saves))
1545 (let ((except-mark (and (equal allout-encrypt-unencrypted-on-saves
1548 (if (save-excursion (goto-char (point-min))
1549 (allout-next-topic-pending-encryption except-mark))
1551 (message "auto-encrypting pending topics")
1553 (condition-case failure
1554 (setq allout-after-save-decrypt
1555 (allout-encrypt-decrypted except-mark))
1557 "allout-write-file-hook-handler suppressing error %s"
1562 ;;;_ > allout-auto-save-hook-handler ()
1563 (defun allout-auto-save-hook-handler ()
1564 "Implement `allout-encrypt-unencrypted-on-saves' policy for auto save."
1566 (if (and (allout-mode-p) allout-encrypt-unencrypted-on-saves)
1567 ;; Always implement 'except-current policy when enabled.
1568 (let ((allout-encrypt-unencrypted-on-saves 'except-current))
1569 (allout-write-file-hook-handler))))
1570 ;;;_ > allout-after-saves-handler ()
1571 (defun allout-after-saves-handler ()
1572 "Decrypt topic encrypted for save, if it's currently being edited.
1574 Ie, if it was pending encryption and contained the point in its body before
1577 We use values stored in `allout-after-save-decrypt' to locate the topic
1578 and the place for the cursor after the decryption is done."
1579 (if (not (and (allout-mode-p)
1580 (boundp 'allout-after-save-decrypt)
1581 allout-after-save-decrypt))
1583 (goto-char (car allout-after-save-decrypt))
1584 (let ((was-modified (buffer-modified-p)))
1585 (allout-toggle-subtree-encryption)
1586 (if (not was-modified)
1587 (set-buffer-modified-p nil)))
1588 (goto-char (cadr allout-after-save-decrypt))
1589 (setq allout-after-save-decrypt nil))
1591 ;;;_ > allout-called-interactively-p ()
1592 (defmacro allout-called-interactively-p ()
1593 "A version of called-interactively-p independent of emacs version."
1594 ;; ... to ease maintenance of allout without betraying deprecation.
1595 (if (equal (subr-arity (symbol-function 'called-interactively-p))
1597 '(called-interactively-p)
1598 '(called-interactively-p 'interactive)))
1599 ;;;_ = allout-inhibit-aberrance-doublecheck nil
1600 ;; In some exceptional moments, disparate topic depths need to be allowed
1601 ;; momentarily, eg when one topic is being yanked into another and they're
1602 ;; about to be reconciled. let-binding allout-inhibit-aberrance-doublecheck
1603 ;; prevents the aberrance doublecheck to allow, eg, the reconciliation
1604 ;; processing to happen in the presence of such discrepancies. It should
1605 ;; almost never be needed, however.
1606 (defvar allout-inhibit-aberrance-doublecheck nil
1607 "Internal state, for momentarily inhibits aberrance doublecheck.
1609 This should only be momentarily let-bound non-nil, not set
1610 non-nil in a lasting way.")
1612 ;;;_ #2 Mode environment and activation
1613 ;;;_ = allout-explicitly-deactivated
1614 (defvar allout-explicitly-deactivated nil
1615 "If t, `allout-mode's last deactivation was deliberate.
1616 So `allout-post-command-business' should not reactivate it...")
1617 (make-variable-buffer-local 'allout-explicitly-deactivated)
1618 ;;;_ > allout-init (&optional mode)
1619 (defun allout-init (&optional mode)
1620 "Prime `allout-mode' to enable/disable auto-activation, wrt `allout-layout'.
1622 MODE is one of the following symbols:
1624 - nil (or no argument) deactivate auto-activation/layout;
1625 - `activate', enable auto-activation only;
1626 - `ask', enable auto-activation, and enable auto-layout but with
1627 confirmation for layout operation solicited from user each time;
1628 - `report', just report and return the current auto-activation state;
1629 - anything else (eg, t) for auto-activation and auto-layout, without
1630 any confirmation check.
1632 Use this function to setup your Emacs session for automatic activation
1633 of allout outline mode, contingent to the buffer-specific setting of
1634 the `allout-layout' variable. (See `allout-layout' and
1635 `allout-expose-topic' docstrings for more details on auto layout).
1637 `allout-init' works by setting up (or removing) the `allout-mode'
1638 find-file-hook, and giving `allout-auto-activation' a suitable
1641 To prime your Emacs session for full auto-outline operation, include
1642 the following two lines in your Emacs init file:
1648 (if (allout-called-interactively-p)
1652 (concat "Select outline auto setup mode "
1653 "(empty for report, ? for options) ")
1654 '(("nil")("full")("activate")("deactivate")
1655 ("ask") ("report") (""))
1658 (if (string= mode "")
1660 (setq mode (intern-soft mode)))))
1662 ;; convenience aliases, for consistent ref to respective vars:
1663 ((hook 'allout-find-file-hook)
1664 (find-file-hook-var-name (if (boundp 'find-file-hook)
1667 (curr-mode 'allout-auto-activation))
1670 (set find-file-hook-var-name
1671 (delq hook (symbol-value find-file-hook-var-name)))
1672 (if (allout-called-interactively-p)
1673 (message "Allout outline mode auto-activation inhibited.")))
1675 (if (not (memq hook (symbol-value find-file-hook-var-name)))
1677 ;; Just punt and use the reports from each of the modes:
1678 (allout-init (symbol-value curr-mode))))
1679 (t (add-hook find-file-hook-var-name hook)
1680 (set curr-mode ; `set', not `setq'!
1681 (cond ((eq mode 'activate)
1683 "Outline mode auto-activation enabled.")
1686 ;; Return the current mode setting:
1690 (concat "Outline mode auto-activation and "
1691 "-layout (upon confirmation) enabled."))
1694 "Outline mode auto-activation and -layout enabled.")
1696 ;;;_ > allout-setup-menubar ()
1697 (defun allout-setup-menubar ()
1698 "Populate the current buffer's menubar with `allout-mode' stuff."
1699 (let ((menus (list allout-mode-exposure-menu
1700 allout-mode-editing-menu
1701 allout-mode-navigation-menu
1702 allout-mode-misc-menu))
1705 (setq cur (car menus)
1707 (easy-menu-add cur))))
1708 ;;;_ > allout-overlay-preparations
1709 (defun allout-overlay-preparations ()
1710 "Set the properties of the allout invisible-text overlay and others."
1711 (setplist 'allout-exposure-category nil)
1712 (put 'allout-exposure-category 'invisible 'allout)
1713 (put 'allout-exposure-category 'evaporate t)
1714 ;; ??? We use isearch-open-invisible *and* isearch-mode-end-hook. The
1715 ;; latter would be sufficient, but it seems that a separate behavior --
1716 ;; the _transient_ opening of invisible text during isearch -- is keyed to
1717 ;; presence of the isearch-open-invisible property -- even though this
1718 ;; property controls the isearch _arrival_ behavior. This is the case at
1719 ;; least in emacs 21, 22.1, and xemacs 21.4.
1720 (put 'allout-exposure-category 'isearch-open-invisible
1721 'allout-isearch-end-handler)
1722 (if (featurep 'xemacs)
1723 (put 'allout-exposure-category 'start-open t)
1724 (put 'allout-exposure-category 'insert-in-front-hooks
1725 '(allout-overlay-insert-in-front-handler)))
1726 (put 'allout-exposure-category 'modification-hooks
1727 '(allout-overlay-interior-modification-handler)))
1728 ;;;_ > define-minor-mode allout-mode
1731 (define-minor-mode allout-mode
1733 "Toggle minor mode for controlling exposure and editing of text outlines.
1734 \\<allout-mode-map-value>
1736 Allout outline mode always runs as a minor mode.
1738 Allout outline mode provides extensive outline oriented
1739 formatting and manipulation. It enables structural editing of
1740 outlines, as well as navigation and exposure. It also is
1741 specifically aimed at accommodating syntax-sensitive text like
1742 programming languages. \(For example, see the allout code itself,
1743 which is organized as an allout outline.)
1745 In addition to typical outline navigation and exposure, allout includes:
1747 - topic-oriented authoring, including keystroke-based topic creation,
1748 repositioning, promotion/demotion, cut, and paste
1749 - incremental search with dynamic exposure and reconcealment of hidden text
1750 - adjustable format, so programming code can be developed in outline-structure
1751 - easy topic encryption and decryption, symmetric or key-pair
1752 - \"Hot-spot\" operation, for single-keystroke maneuvering and exposure control
1753 - integral outline layout, for automatic initial exposure when visiting a file
1754 - independent extensibility, using comprehensive exposure and authoring hooks
1756 and many other features.
1758 Below is a description of the key bindings, and then description
1759 of special `allout-mode' features and terminology. See also the
1760 outline menubar additions for quick reference to many of the
1761 features, and see the docstring of the function `allout-init' for
1762 instructions on priming your emacs session for automatic
1763 activation of `allout-mode'.
1765 The bindings are those listed in `allout-prefixed-keybindings'
1766 and `allout-unprefixed-keybindings'. We recommend customizing
1767 `allout-command-prefix' to use just `\\C-c' as the command
1768 prefix, if the allout bindings don't conflict with any personal
1769 bindings you have on \\C-c. In any case, outline structure
1770 navigation and authoring is simplified by positioning the cursor
1771 on an item's bullet character, the \"hot-spot\" -- then you can
1772 invoke allout commands with just the un-prefixed,
1773 un-control-shifted command letters. This is described further in
1774 the HOT-SPOT Operation section.
1778 \\[allout-hide-current-subtree] `allout-hide-current-subtree'
1779 \\[allout-show-children] `allout-show-children'
1780 \\[allout-show-current-subtree] `allout-show-current-subtree'
1781 \\[allout-show-current-entry] `allout-show-current-entry'
1782 \\[allout-show-all] `allout-show-all'
1786 \\[allout-next-visible-heading] `allout-next-visible-heading'
1787 \\[allout-previous-visible-heading] `allout-previous-visible-heading'
1788 \\[allout-up-current-level] `allout-up-current-level'
1789 \\[allout-forward-current-level] `allout-forward-current-level'
1790 \\[allout-backward-current-level] `allout-backward-current-level'
1791 \\[allout-end-of-entry] `allout-end-of-entry'
1792 \\[allout-beginning-of-current-entry] `allout-beginning-of-current-entry' (alternately, goes to hot-spot)
1793 \\[allout-beginning-of-line] `allout-beginning-of-line' -- like regular beginning-of-line, but
1794 if immediately repeated cycles to the beginning of the current item
1795 and then to the hot-spot (if `allout-beginning-of-line-cycles' is set).
1798 Topic Header Production:
1799 -----------------------
1800 \\[allout-open-sibtopic] `allout-open-sibtopic' Create a new sibling after current topic.
1801 \\[allout-open-subtopic] `allout-open-subtopic' ... an offspring of current topic.
1802 \\[allout-open-supertopic] `allout-open-supertopic' ... a sibling of the current topic's parent.
1804 Topic Level and Prefix Adjustment:
1805 ---------------------------------
1806 \\[allout-shift-in] `allout-shift-in' Shift current topic and all offspring deeper
1807 \\[allout-shift-out] `allout-shift-out' ... less deep
1808 \\[allout-rebullet-current-heading] `allout-rebullet-current-heading' Prompt for alternate bullet for
1810 \\[allout-rebullet-topic] `allout-rebullet-topic' Reconcile bullets of topic and
1811 its' offspring -- distinctive bullets are not changed, others
1812 are alternated according to nesting depth.
1813 \\[allout-number-siblings] `allout-number-siblings' Number bullets of topic and siblings --
1814 the offspring are not affected.
1815 With repeat count, revoke numbering.
1817 Topic-oriented Killing and Yanking:
1818 ----------------------------------
1819 \\[allout-kill-topic] `allout-kill-topic' Kill current topic, including offspring.
1820 \\[allout-copy-topic-as-kill] `allout-copy-topic-as-kill' Copy current topic, including offspring.
1821 \\[allout-kill-line] `allout-kill-line' kill-line, attending to outline structure.
1822 \\[allout-copy-line-as-kill] `allout-copy-line-as-kill' Copy line but don't delete it.
1823 \\[allout-yank] `allout-yank' Yank, adjusting depth of yanked topic to
1824 depth of heading if yanking into bare topic
1825 heading (ie, prefix sans text).
1826 \\[allout-yank-pop] `allout-yank-pop' Is to allout-yank as yank-pop is to yank
1828 Topic-oriented Encryption:
1829 -------------------------
1830 \\[allout-toggle-current-subtree-encryption] `allout-toggle-current-subtree-encryption'
1831 Encrypt/Decrypt topic content
1835 M-x outlineify-sticky Activate outline mode for current buffer,
1836 and establish a default file-var setting
1837 for `allout-layout'.
1838 \\[allout-mark-topic] `allout-mark-topic'
1839 \\[allout-copy-exposed-to-buffer] `allout-copy-exposed-to-buffer'
1840 Duplicate outline, sans concealed text, to
1841 buffer with name derived from derived from that
1842 of current buffer -- \"*BUFFERNAME exposed*\".
1843 \\[allout-flatten-exposed-to-buffer] `allout-flatten-exposed-to-buffer'
1844 Like above 'copy-exposed', but convert topic
1845 prefixes to section.subsection... numeric
1847 \\[eval-expression] (allout-init t) Setup Emacs session for outline mode
1852 Outline mode supports gpg encryption of topics, with support for
1853 symmetric and key-pair modes, and auto-encryption of topics
1854 pending encryption on save.
1856 Topics pending encryption are, by default, automatically
1857 encrypted during file saves, including checkpoint saves, to avoid
1858 exposing the plain text of encrypted topics in the file system.
1859 If the content of the topic containing the cursor was encrypted
1860 for a save, it is automatically decrypted for continued editing.
1862 NOTE: A few GnuPG v2 versions improperly preserve incorrect
1863 symmetric decryption keys, preventing entry of the correct key on
1864 subsequent decryption attempts until the cache times-out. That
1865 can take several minutes. \(Decryption of other entries is not
1866 affected.) Upgrade your EasyPG version, if you can, and you can
1867 deliberately clear your gpg-agent's cache by sending it a '-HUP'
1870 See `allout-toggle-current-subtree-encryption' function docstring
1871 and `allout-encrypt-unencrypted-on-saves' customization variable
1876 Hot-spot operation provides a means for easy, single-keystroke outline
1877 navigation and exposure control.
1879 When the text cursor is positioned directly on the bullet character of
1880 a topic, regular characters (a to z) invoke the commands of the
1881 corresponding allout-mode keymap control chars. For example, \"f\"
1882 would invoke the command typically bound to \"C-c<space>C-f\"
1883 \(\\[allout-forward-current-level] `allout-forward-current-level').
1885 Thus, by positioning the cursor on a topic bullet, you can
1886 execute the outline navigation and manipulation commands with a
1887 single keystroke. Regular navigation keys (eg, \\[forward-char], \\[next-line]) don't get
1888 this special translation, so you can use them to get out of the
1889 hot-spot and back to normal editing operation.
1891 In allout-mode, the normal beginning-of-line command (\\[allout-beginning-of-line]) is
1892 replaced with one that makes it easy to get to the hot-spot. If you
1893 repeat it immediately it cycles (if `allout-beginning-of-line-cycles'
1894 is set) to the beginning of the item and then, if you hit it again
1895 immediately, to the hot-spot. Similarly, `allout-beginning-of-current-entry'
1896 \(\\[allout-beginning-of-current-entry]) moves to the hot-spot when the cursor is already located
1897 at the beginning of the current entry.
1901 Allout exposure and authoring activites all have associated
1902 hooks, by which independent code can cooperate with allout
1903 without changes to the allout core. Here are key ones:
1906 `allout-mode-deactivate-hook' \(deprecated)
1907 `allout-mode-off-hook'
1908 `allout-exposure-change-hook'
1909 `allout-structure-added-hook'
1910 `allout-structure-deleted-hook'
1911 `allout-structure-shifted-hook'
1915 Topic hierarchy constituents -- TOPICS and SUBTOPICS:
1917 ITEM: A unitary outline element, including the HEADER and ENTRY text.
1918 TOPIC: An ITEM and any ITEMs contained within it, ie having greater DEPTH
1919 and with no intervening items of lower DEPTH than the container.
1921 The visible ITEM most immediately containing the cursor.
1922 DEPTH: The degree of nesting of an ITEM; it increases with containment.
1923 The DEPTH is determined by the HEADER PREFIX. The DEPTH is also
1925 LEVEL: The same as DEPTH.
1928 Those ITEMs whose TOPICs contain an ITEM.
1929 PARENT: An ITEM's immediate ANCESTOR. It has a DEPTH one less than that
1932 The ITEMs contained within an ITEM's TOPIC.
1934 An OFFSPRING of its ANCESTOR TOPICs.
1936 An immediate SUBTOPIC of its PARENT.
1938 TOPICs having the same PARENT and DEPTH.
1940 Topic text constituents:
1942 HEADER: The first line of an ITEM, include the ITEM PREFIX and HEADER
1944 ENTRY: The text content of an ITEM, before any OFFSPRING, but including
1945 the HEADER text and distinct from the ITEM PREFIX.
1946 BODY: Same as ENTRY.
1947 PREFIX: The leading text of an ITEM which distinguishes it from normal
1948 ENTRY text. Allout recognizes the outline structure according
1949 to the strict PREFIX format. It consists of a PREFIX-LEAD string,
1950 PREFIX-PADDING, and a BULLET. The BULLET might be followed by a
1951 number, indicating the ordinal number of the topic among its
1952 siblings, or an asterisk indicating encryption, plus an optional
1953 space. After that is the ITEM HEADER text, which is not part of
1956 The relative length of the PREFIX determines the nesting DEPTH
1959 The string at the beginning of a HEADER PREFIX, by default a `.'.
1960 It can be customized by changing the setting of
1961 `allout-header-prefix' and then reinitializing `allout-mode'.
1963 When the PREFIX-LEAD is set to the comment-string of a
1964 programming language, outline structuring can be embedded in
1965 program code without interfering with processing of the text
1966 (by emacs or the language processor) as program code. This
1967 setting happens automatically when allout mode is used in
1968 programming-mode buffers. See `allout-use-mode-specific-leader'
1969 docstring for more detail.
1971 Spaces or asterisks which separate the PREFIX-LEAD and the
1972 bullet, determining the ITEM's DEPTH.
1973 BULLET: A character at the end of the ITEM PREFIX, it must be one of
1974 the characters listed on `allout-plain-bullets-string' or
1975 `allout-distinctive-bullets-string'. When creating a TOPIC,
1976 plain BULLETs are by default used, according to the DEPTH of the
1977 TOPIC. Choice among the distinctive BULLETs is offered when you
1978 provide a universal argugment \(\\[universal-argument]) to the
1979 TOPIC creation command, or when explictly rebulleting a TOPIC. The
1980 significance of the various distinctive bullets is purely by
1981 convention. See the documentation for the above bullet strings for
1984 The state of a TOPIC which determines the on-screen visibility
1985 of its OFFSPRING and contained ENTRY text.
1987 TOPICs and ENTRY text whose EXPOSURE is inhibited. Concealed
1988 text is represented by \"...\" ellipses.
1990 CONCEALED TOPICs are effectively collapsed within an ANCESTOR.
1991 CLOSED: A TOPIC whose immediate OFFSPRING and body-text is CONCEALED.
1992 OPEN: A TOPIC that is not CLOSED, though its OFFSPRING or BODY may be."
1995 :keymap 'allout-mode-map
1997 (let ((write-file-hook-var-name (cond ((boundp 'write-file-functions)
1998 'write-file-functions)
1999 ((boundp 'write-file-hooks)
2001 (t 'local-write-file-hooks)))
2002 (use-layout (if (listp allout-layout)
2004 allout-default-layout)))
2006 (if (not (allout-mode-p))
2010 ; Activation not explicitly
2011 ; requested, and either in
2012 ; active state or *de*activation
2013 ; specifically requested:
2014 (allout-do-resumptions)
2016 (remove-from-invisibility-spec '(allout . t))
2017 (remove-hook 'pre-command-hook 'allout-pre-command-business t)
2018 (remove-hook 'post-command-hook 'allout-post-command-business t)
2019 (remove-hook 'before-change-functions 'allout-before-change-handler t)
2020 (remove-hook 'isearch-mode-end-hook 'allout-isearch-end-handler t)
2021 (remove-hook write-file-hook-var-name
2022 'allout-write-file-hook-handler t)
2023 (remove-hook 'auto-save-hook 'allout-auto-save-hook-handler t)
2025 (remove-overlays (point-min) (point-max)
2026 'category 'allout-exposure-category))
2029 (if allout-old-style-prefixes
2030 ;; Inhibit all the fancy formatting:
2031 (allout-add-resumptions '(allout-primary-bullet "*")))
2033 (allout-overlay-preparations) ; Doesn't hurt to redo this.
2035 (allout-infer-header-lead-and-primary-bullet)
2036 (allout-infer-body-reindent)
2039 (allout-add-resumptions '(allout-encryption-ciphertext-rejection-regexps
2040 allout-line-boundary-regexp
2042 '(allout-encryption-ciphertext-rejection-regexps
2046 (allout-compose-and-institute-keymap)
2047 (produce-allout-mode-menubar-entries)
2049 (add-to-invisibility-spec '(allout . t))
2051 (allout-add-resumptions '(line-move-ignore-invisible t))
2052 (add-hook 'pre-command-hook 'allout-pre-command-business nil t)
2053 (add-hook 'post-command-hook 'allout-post-command-business nil t)
2054 (add-hook 'before-change-functions 'allout-before-change-handler nil t)
2055 (add-hook 'isearch-mode-end-hook 'allout-isearch-end-handler nil t)
2056 (add-hook write-file-hook-var-name 'allout-write-file-hook-handler
2058 (add-hook 'auto-save-hook 'allout-auto-save-hook-handler nil t)
2060 ;; Stash auto-fill settings and adjust so custom allout auto-fill
2061 ;; func will be used if auto-fill is active or activated. (The
2062 ;; custom func respects topic headline, maintains hanging-indents,
2064 (allout-add-resumptions (list 'allout-former-auto-filler
2066 ;; Register allout-auto-fill to be used if
2067 ;; filling is active:
2068 (list 'allout-outside-normal-auto-fill-function
2069 normal-auto-fill-function)
2070 '(normal-auto-fill-function allout-auto-fill)
2071 ;; Paragraphs are broken by topic headlines.
2072 (list 'paragraph-start
2073 (concat paragraph-start "\\|^\\("
2074 allout-regexp "\\)"))
2075 (list 'paragraph-separate
2076 (concat paragraph-separate "\\|^\\("
2077 allout-regexp "\\)")))
2078 (if (and auto-fill-function (not allout-inhibit-auto-fill))
2079 ;; allout-auto-fill will use the stashed values and so forth.
2080 (allout-add-resumptions '(auto-fill-function allout-auto-fill)))
2082 (allout-setup-menubar)
2084 ;; Do auto layout if warranted:
2085 (when (and allout-layout
2086 allout-auto-activation
2088 (and (not (eq allout-auto-activation 'activate))
2089 (if (eq allout-auto-activation 'ask)
2090 (if (y-or-n-p (format "Expose %s with layout '%s'? "
2094 (message "Skipped %s layout." (buffer-name))
2098 (message "Adjusting '%s' exposure..." (buffer-name))
2100 (allout-this-or-next-heading)
2103 (apply 'allout-expose-topic (list use-layout))
2104 (message "Adjusting '%s' exposure... done."
2106 ;; Problem applying exposure -- notify user, but don't
2107 ;; interrupt, eg, file visit:
2108 (error (message "%s" (car (cdr err)))
2110 ) ; when allout-layout
2111 ) ; if (allout-mode-p)
2113 ) ; define-minor-mode
2114 ;;;_ > allout-minor-mode alias
2115 (defalias 'allout-minor-mode 'allout-mode)
2116 ;;;_ > allout-unload-function
2117 (defun allout-unload-function ()
2118 "Unload the allout outline library."
2119 (save-current-buffer
2120 (dolist (buffer (buffer-list))
2122 (when (allout-mode-p) (allout-mode))))
2123 ;; continue standard unloading
2126 ;;;_ - Position Assessment
2127 ;;;_ > allout-hidden-p (&optional pos)
2128 (defsubst allout-hidden-p (&optional pos)
2129 "Non-nil if the character after point was made invisible by allout."
2130 (eq (get-char-property (or pos (point)) 'invisible) 'allout))
2132 ;;;_ > allout-overlay-insert-in-front-handler (ol after beg end
2133 ;;; &optional prelen)
2134 (defun allout-overlay-insert-in-front-handler (ol after beg end
2136 "Shift the overlay so stuff inserted in front of it is excluded."
2138 ;; ??? Shouldn't moving the overlay should be unnecessary, if overlay
2139 ;; front-advance on the overlay worked as expected?
2140 (move-overlay ol (1+ beg) (overlay-end ol))))
2141 ;;;_ > allout-overlay-interior-modification-handler (ol after beg end
2142 ;;; &optional prelen)
2143 (defun allout-overlay-interior-modification-handler (ol after beg end
2145 "Get confirmation before making arbitrary changes to invisible text.
2147 We expose the invisible text and ask for confirmation. Refusal or
2148 `keyboard-quit' abandons the changes, with keyboard-quit additionally
2149 reclosing the opened text.
2151 No confirmation is necessary when `inhibit-read-only' is set -- eg, allout
2152 internal functions use this feature cohesively bunch changes."
2154 (when (and (not inhibit-read-only) (not after))
2155 (let ((start (point))
2156 (ol-start (overlay-start ol))
2157 (ol-end (overlay-end ol))
2160 (while (< (point) end)
2161 (when (allout-hidden-p)
2162 (allout-show-to-offshoot)
2163 (if (allout-hidden-p)
2164 (save-excursion (forward-char 1)
2165 (allout-show-to-offshoot)))
2167 (setq first (point))))
2168 (goto-char (if (featurep 'xemacs)
2169 (next-property-change (1+ (point)) nil end)
2170 (next-char-property-change (1+ (point)) end))))
2176 (substitute-command-keys
2177 (concat "Modify concealed text? (\"no\" just aborts,"
2178 " \\[keyboard-quit] also reconceals) "))))
2179 (progn (goto-char start)
2180 (error "Concealed-text change refused")))
2181 (quit (allout-flag-region ol-start ol-end nil)
2182 (allout-flag-region ol-start ol-end t)
2183 (error "Concealed-text change abandoned, text reconcealed"))))
2184 (goto-char start))))
2185 ;;;_ > allout-before-change-handler (beg end)
2186 (defun allout-before-change-handler (beg end)
2187 "Protect against changes to invisible text.
2189 See `allout-overlay-interior-modification-handler' for details."
2191 (when (and (allout-mode-p) undo-in-progress (allout-hidden-p))
2192 (allout-show-children))
2194 ;; allout-overlay-interior-modification-handler on an overlay handles
2195 ;; this in other emacs, via `allout-exposure-category's 'modification-hooks.
2196 (when (and (featurep 'xemacs) (allout-mode-p))
2197 ;; process all of the pending overlays:
2200 (let ((overlay (allout-get-invisibility-overlay)))
2202 (allout-overlay-interior-modification-handler
2203 overlay nil beg end nil))))))
2204 ;;;_ > allout-isearch-end-handler (&optional overlay)
2205 (defun allout-isearch-end-handler (&optional overlay)
2206 "Reconcile allout outline exposure on arriving in hidden text after isearch.
2208 Optional OVERLAY parameter is for when this function is used by
2209 `isearch-open-invisible' overlay property. It is otherwise unused, so this
2210 function can also be used as an `isearch-mode-end-hook'."
2212 (if (and (allout-mode-p) (allout-hidden-p))
2213 (allout-show-to-offshoot)))
2215 ;;;_ #3 Internal Position State-Tracking -- "allout-recent-*" funcs
2216 ;; All the basic outline functions that directly do string matches to
2217 ;; evaluate heading prefix location set the variables
2218 ;; `allout-recent-prefix-beginning' and `allout-recent-prefix-end'
2219 ;; when successful. Functions starting with `allout-recent-' all
2220 ;; use this state, providing the means to avoid redundant searches
2221 ;; for just-established data. This optimization can provide
2222 ;; significant speed improvement, but it must be employed carefully.
2223 ;;;_ = allout-recent-prefix-beginning
2224 (defvar allout-recent-prefix-beginning 0
2225 "Buffer point of the start of the last topic prefix encountered.")
2226 (make-variable-buffer-local 'allout-recent-prefix-beginning)
2227 ;;;_ = allout-recent-prefix-end
2228 (defvar allout-recent-prefix-end 0
2229 "Buffer point of the end of the last topic prefix encountered.")
2230 (make-variable-buffer-local 'allout-recent-prefix-end)
2231 ;;;_ = allout-recent-depth
2232 (defvar allout-recent-depth 0
2233 "Depth of the last topic prefix encountered.")
2234 (make-variable-buffer-local 'allout-recent-depth)
2235 ;;;_ = allout-recent-end-of-subtree
2236 (defvar allout-recent-end-of-subtree 0
2237 "Buffer point last returned by `allout-end-of-current-subtree'.")
2238 (make-variable-buffer-local 'allout-recent-end-of-subtree)
2239 ;;;_ > allout-prefix-data ()
2240 (defsubst allout-prefix-data ()
2241 "Register allout-prefix state data.
2243 For reference by `allout-recent' funcs. Return
2244 the new value of `allout-recent-prefix-beginning'."
2245 (setq allout-recent-prefix-end (or (match-end 1) (match-end 2) (match-end 3))
2246 allout-recent-prefix-beginning (or (match-beginning 1)
2248 (match-beginning 3))
2249 allout-recent-depth (max 1 (- allout-recent-prefix-end
2250 allout-recent-prefix-beginning
2251 allout-header-subtraction)))
2252 allout-recent-prefix-beginning)
2253 ;;;_ > nullify-allout-prefix-data ()
2254 (defsubst nullify-allout-prefix-data ()
2255 "Mark allout prefix data as being uninformative."
2256 (setq allout-recent-prefix-end (point)
2257 allout-recent-prefix-beginning (point)
2258 allout-recent-depth 0)
2259 allout-recent-prefix-beginning)
2260 ;;;_ > allout-recent-depth ()
2261 (defsubst allout-recent-depth ()
2262 "Return depth of last heading encountered by an outline maneuvering function.
2264 All outline functions which directly do string matches to assess
2265 headings set the variables `allout-recent-prefix-beginning' and
2266 `allout-recent-prefix-end' if successful. This function uses those settings
2267 to return the current depth."
2269 allout-recent-depth)
2270 ;;;_ > allout-recent-prefix ()
2271 (defsubst allout-recent-prefix ()
2272 "Like `allout-recent-depth', but returns text of last encountered prefix.
2274 All outline functions which directly do string matches to assess
2275 headings set the variables `allout-recent-prefix-beginning' and
2276 `allout-recent-prefix-end' if successful. This function uses those settings
2277 to return the current prefix."
2278 (buffer-substring-no-properties allout-recent-prefix-beginning
2279 allout-recent-prefix-end))
2280 ;;;_ > allout-recent-bullet ()
2281 (defmacro allout-recent-bullet ()
2282 "Like allout-recent-prefix, but returns bullet of last encountered prefix.
2284 All outline functions which directly do string matches to assess
2285 headings set the variables `allout-recent-prefix-beginning' and
2286 `allout-recent-prefix-end' if successful. This function uses those settings
2287 to return the current depth of the most recently matched topic."
2288 '(buffer-substring-no-properties (1- allout-recent-prefix-end)
2289 allout-recent-prefix-end))
2293 ;;;_ - Position Assessment
2294 ;;;_ : Location Predicates
2295 ;;;_ > allout-do-doublecheck ()
2296 (defsubst allout-do-doublecheck ()
2297 "True if current item conditions qualify for checking on topic aberrance."
2299 ;; presume integrity of outline and yanked content during yank -- necessary
2300 ;; to allow for level disparity of yank location and yanked text:
2301 (not allout-inhibit-aberrance-doublecheck)
2302 ;; allout-doublecheck-at-and-shallower is ceiling for doublecheck:
2303 (<= allout-recent-depth allout-doublecheck-at-and-shallower)))
2304 ;;;_ > allout-aberrant-container-p ()
2305 (defun allout-aberrant-container-p ()
2306 "True if topic, or next sibling with children, contains them discontinuously.
2308 Discontinuous means an immediate offspring that is nested more
2309 than one level deeper than the topic.
2311 If topic has no offspring, then the next sibling with offspring will
2312 determine whether or not this one is determined to be aberrant.
2314 If true, then the allout-recent-* settings are calibrated on the
2315 offspring that qaulifies it as aberrant, ie with depth that
2316 exceeds the topic by more than one."
2318 ;; This is most clearly understood when considering standard-prefix-leader
2319 ;; low-level topics, which can all too easily match text not intended as
2320 ;; headers. For example, any line with a leading '.' or '*' and lacking a
2321 ;; following bullet qualifies without this protection. (A sequence of
2322 ;; them can occur naturally, eg a typical textual bullet list.) We
2323 ;; disqualify such low-level sequences when they are followed by a
2324 ;; discontinuously contained child, inferring that the sequences are not
2325 ;; actually connected with their prospective context.
2327 (let ((depth (allout-depth))
2328 (start-point (point))
2332 (while (and (not done)
2333 (re-search-forward allout-line-boundary-regexp nil 0))
2334 (allout-prefix-data)
2335 (goto-char allout-recent-prefix-beginning)
2337 ;; sibling -- continue:
2338 ((eq allout-recent-depth depth))
2339 ;; first offspring is excessive -- aberrant:
2340 ((> allout-recent-depth (1+ depth))
2341 (setq done t aberrant t))
2342 ;; next non-sibling is lower-depth -- not aberrant:
2343 (t (setq done t))))))
2346 (goto-char start-point)
2347 ;; recalibrate allout-recent-*
2350 ;;;_ > allout-on-current-heading-p ()
2351 (defun allout-on-current-heading-p ()
2352 "Return non-nil if point is on current visible topics' header line.
2354 Actually, returns prefix beginning point."
2356 (allout-beginning-of-current-line)
2358 (and (looking-at allout-regexp)
2359 (allout-prefix-data)
2360 (or (not (allout-do-doublecheck))
2361 (not (allout-aberrant-container-p)))))))
2362 ;;;_ > allout-on-heading-p ()
2363 (defalias 'allout-on-heading-p 'allout-on-current-heading-p)
2364 ;;;_ > allout-e-o-prefix-p ()
2365 (defun allout-e-o-prefix-p ()
2366 "True if point is located where current topic prefix ends, heading begins."
2367 (and (save-match-data
2368 (save-excursion (let ((inhibit-field-text-motion t))
2369 (beginning-of-line))
2370 (looking-at allout-regexp))
2371 (= (point) (save-excursion (allout-end-of-prefix)(point))))))
2372 ;;;_ : Location attributes
2373 ;;;_ > allout-depth ()
2374 (defun allout-depth ()
2375 "Return depth of topic most immediately containing point.
2377 Does not do doublecheck for aberrant topic header.
2379 Return zero if point is not within any topic.
2381 Like `allout-current-depth', but respects hidden as well as visible topics."
2383 (let ((start-point (point)))
2384 (if (and (allout-goto-prefix)
2385 (not (< start-point (point))))
2388 ;; Oops, no prefix, nullify it:
2389 (nullify-allout-prefix-data)
2390 ;; ... and return 0:
2392 ;;;_ > allout-current-depth ()
2393 (defun allout-current-depth ()
2394 "Return depth of visible topic most immediately containing point.
2396 Return zero if point is not within any topic."
2398 (if (allout-back-to-current-heading)
2400 (- allout-recent-prefix-end
2401 allout-recent-prefix-beginning
2402 allout-header-subtraction))
2404 ;;;_ > allout-get-current-prefix ()
2405 (defun allout-get-current-prefix ()
2406 "Topic prefix of the current topic."
2408 (if (allout-goto-prefix)
2409 (allout-recent-prefix))))
2410 ;;;_ > allout-get-bullet ()
2411 (defun allout-get-bullet ()
2412 "Return bullet of containing topic (visible or not)."
2414 (and (allout-goto-prefix)
2415 (allout-recent-bullet))))
2416 ;;;_ > allout-current-bullet ()
2417 (defun allout-current-bullet ()
2418 "Return bullet of current (visible) topic heading, or none if none found."
2421 (allout-back-to-current-heading)
2422 (buffer-substring-no-properties (- allout-recent-prefix-end 1)
2423 allout-recent-prefix-end))
2424 ;; Quick and dirty provision, ostensibly for missing bullet:
2425 (args-out-of-range nil))
2427 ;;;_ > allout-get-prefix-bullet (prefix)
2428 (defun allout-get-prefix-bullet (prefix)
2429 "Return the bullet of the header prefix string PREFIX."
2430 ;; Doesn't make sense if we're old-style prefixes, but this just
2431 ;; oughtn't be called then, so forget about it...
2432 (if (string-match allout-regexp prefix)
2433 (substring prefix (1- (match-end 2)) (match-end 2))))
2434 ;;;_ > allout-sibling-index (&optional depth)
2435 (defun allout-sibling-index (&optional depth)
2436 "Item number of this prospective topic among its siblings.
2438 If optional arg DEPTH is greater than current depth, then we're
2439 opening a new level, and return 0.
2441 If less than this depth, ascend to that depth and count..."
2444 (cond ((and depth (<= depth 0) 0))
2445 ((or (null depth) (= depth (allout-depth)))
2447 (while (allout-previous-sibling allout-recent-depth nil)
2448 (setq index (1+ index)))
2450 ((< depth allout-recent-depth)
2451 (allout-ascend-to-depth depth)
2452 (allout-sibling-index))
2454 ;;;_ > allout-topic-flat-index ()
2455 (defun allout-topic-flat-index ()
2456 "Return a list indicating point's numeric section.subsect.subsubsect...
2457 Outermost is first."
2458 (let* ((depth (allout-depth))
2459 (next-index (allout-sibling-index depth))
2461 (while (> next-index 0)
2462 (setq rev-sibls (cons next-index rev-sibls))
2463 (setq depth (1- depth))
2464 (setq next-index (allout-sibling-index depth)))
2468 ;;;_ - Navigation routines
2469 ;;;_ > allout-beginning-of-current-line ()
2470 (defun allout-beginning-of-current-line ()
2471 "Like beginning of line, but to visible text."
2473 ;; This combination of move-beginning-of-line and beginning-of-line is
2474 ;; deliberate, but the (beginning-of-line) may now be superfluous.
2475 (let ((inhibit-field-text-motion t))
2476 (move-beginning-of-line 1)
2478 (while (and (not (bobp)) (or (not (bolp)) (allout-hidden-p)))
2480 (if (or (allout-hidden-p) (not (bolp)))
2481 (forward-char -1)))))
2482 ;;;_ > allout-end-of-current-line ()
2483 (defun allout-end-of-current-line ()
2484 "Move to the end of line, past concealed text if any."
2485 ;; This is for symmetry with `allout-beginning-of-current-line' --
2486 ;; `move-end-of-line' doesn't suffer the same problem as
2487 ;; `move-beginning-of-line'.
2488 (let ((inhibit-field-text-motion t))
2490 (while (allout-hidden-p)
2492 (if (allout-hidden-p) (forward-char 1)))))
2493 ;;;_ > allout-beginning-of-line ()
2494 (defun allout-beginning-of-line ()
2495 "Beginning-of-line with `allout-beginning-of-line-cycles' behavior, if set."
2499 (if (or (not allout-beginning-of-line-cycles)
2500 (not (equal last-command this-command)))
2502 (if (and (not (bolp))
2503 (allout-hidden-p (1- (point))))
2504 (goto-char (allout-previous-single-char-property-change
2505 (1- (point)) 'invisible)))
2506 (move-beginning-of-line 1))
2508 (let ((beginning-of-body
2510 (while (and (allout-do-doublecheck)
2511 (allout-aberrant-container-p)
2512 (allout-previous-visible-heading 1)))
2513 (allout-beginning-of-current-entry)
2515 (cond ((= (current-column) 0)
2516 (goto-char beginning-of-body))
2517 ((< (point) beginning-of-body)
2518 (allout-beginning-of-current-line))
2519 ((= (point) beginning-of-body)
2520 (goto-char (allout-current-bullet-pos)))
2521 (t (allout-beginning-of-current-line)
2522 (if (< (point) beginning-of-body)
2523 ;; we were on the headline after its start:
2524 (goto-char beginning-of-body)))))))
2525 ;;;_ > allout-end-of-line ()
2526 (defun allout-end-of-line ()
2527 "End-of-line with `allout-end-of-line-cycles' behavior, if set."
2531 (if (or (not allout-end-of-line-cycles)
2532 (not (equal last-command this-command)))
2533 (allout-end-of-current-line)
2534 (let ((end-of-entry (save-excursion
2535 (allout-end-of-entry)
2538 (allout-end-of-current-line))
2539 ((or (allout-hidden-p) (save-excursion
2542 (allout-back-to-current-heading)
2543 (allout-show-current-entry)
2544 (allout-show-children)
2545 (allout-end-of-entry))
2546 ((>= (point) end-of-entry)
2547 (allout-back-to-current-heading)
2548 (allout-end-of-current-line))
2550 (if (not (allout-mark-active-p))
2552 (allout-end-of-entry))))))
2553 ;;;_ > allout-mark-active-p ()
2554 (defun allout-mark-active-p ()
2555 "True if the mark is currently or always active."
2556 ;; `(cond (boundp...))' (or `(if ...)') invokes special byte-compiler
2557 ;; provisions, at least in fsf emacs to prevent warnings about lack of,
2558 ;; eg, region-active-p.
2559 (cond ((boundp 'mark-active)
2561 ((fboundp 'region-active-p)
2564 ;;;_ > allout-next-heading ()
2565 (defsubst allout-next-heading ()
2566 "Move to the heading for the topic (possibly invisible) after this one.
2568 Returns the location of the heading, or nil if none found.
2570 We skip anomalous low-level topics, a la `allout-aberrant-container-p'."
2573 (if (looking-at allout-regexp)
2576 (when (re-search-forward allout-line-boundary-regexp nil 0)
2577 (allout-prefix-data)
2578 (goto-char allout-recent-prefix-beginning)
2581 (and (allout-do-doublecheck)
2582 ;; this will set allout-recent-* on the first non-aberrant topic,
2583 ;; whether it's the current one or one that disqualifies it:
2584 (allout-aberrant-container-p))
2585 ;; this may or may not be the same as above depending on doublecheck:
2586 (goto-char allout-recent-prefix-beginning))))
2587 ;;;_ > allout-this-or-next-heading
2588 (defun allout-this-or-next-heading ()
2589 "Position cursor on current or next heading."
2590 ;; A throwaway non-macro that is defined after allout-next-heading
2591 ;; and usable by allout-mode.
2592 (if (not (allout-goto-prefix-doublechecked)) (allout-next-heading)))
2593 ;;;_ > allout-previous-heading ()
2594 (defun allout-previous-heading ()
2595 "Move to the prior (possibly invisible) heading line.
2597 Return the location of the beginning of the heading, or nil if not found.
2599 We skip anomalous low-level topics, a la `allout-aberrant-container-p'."
2603 (let ((start-point (point)))
2604 ;; allout-goto-prefix-doublechecked calls us, so we can't use it here.
2605 (allout-goto-prefix)
2607 (when (or (re-search-backward allout-line-boundary-regexp nil 0)
2608 (looking-at allout-bob-regexp))
2609 (goto-char (allout-prefix-data))
2610 (if (and (allout-do-doublecheck)
2611 (allout-aberrant-container-p))
2612 (or (allout-previous-heading)
2613 (and (goto-char start-point)
2614 ;; recalibrate allout-recent-*:
2618 ;;;_ > allout-get-invisibility-overlay ()
2619 (defun allout-get-invisibility-overlay ()
2620 "Return the overlay at point that dictates allout invisibility."
2621 (let ((overlays (overlays-at (point)))
2623 (while (and overlays (not got))
2624 (if (equal (overlay-get (car overlays) 'invisible) 'allout)
2625 (setq got (car overlays))
2628 ;;;_ > allout-back-to-visible-text ()
2629 (defun allout-back-to-visible-text ()
2630 "Move to most recent prior character that is visible, and return point."
2631 (if (allout-hidden-p)
2632 (goto-char (overlay-start (allout-get-invisibility-overlay))))
2635 ;;;_ - Subtree Charting
2636 ;;;_ " These routines either produce or assess charts, which are
2637 ;;; nested lists of the locations of topics within a subtree.
2639 ;;; Charts enable efficient subtree navigation by providing a reusable basis
2640 ;;; for elaborate, compound assessment and adjustment of a subtree.
2642 ;;;_ > allout-chart-subtree (&optional levels visible orig-depth prev-depth)
2643 (defun allout-chart-subtree (&optional levels visible orig-depth prev-depth)
2644 "Produce a location \"chart\" of subtopics of the containing topic.
2646 Optional argument LEVELS specifies a depth limit (relative to start
2647 depth) for the chart. Null LEVELS means no limit.
2649 When optional argument VISIBLE is non-nil, the chart includes
2650 only the visible subelements of the charted subjects.
2652 The remaining optional args are for internal use by the function.
2654 Point is left at the end of the subtree.
2656 Charts are used to capture outline structure, so that outline-altering
2657 routines need assess the structure only once, and then use the chart
2658 for their elaborate manipulations.
2660 The chart entries for the topics are in reverse order, so the
2661 last topic is listed first. The entry for each topic consists of
2662 an integer indicating the point at the beginning of the topic
2663 prefix. Charts for offspring consists of a list containing,
2664 recursively, the charts for the respective subtopics. The chart
2665 for a topics' offspring precedes the entry for the topic itself.
2667 The other function parameters are for internal recursion, and should
2668 not be specified by external callers. ORIG-DEPTH is depth of topic at
2669 starting point, and PREV-DEPTH is depth of prior topic."
2671 (let ((original (not orig-depth)) ; `orig-depth' set only in recursion.
2674 (if original ; Just starting?
2675 ; Register initial settings and
2676 ; position to first offspring:
2677 (progn (setq orig-depth (allout-depth))
2678 (or prev-depth (setq prev-depth (1+ orig-depth)))
2680 (allout-next-visible-heading 1)
2681 (allout-next-heading))))
2683 ;; Loop over the current levels' siblings. Besides being more
2684 ;; efficient than tail-recursing over a level, it avoids exceeding
2685 ;; the typically quite constrained Emacs max-lisp-eval-depth.
2687 ;; Probably would speed things up to implement loop-based stack
2688 ;; operation rather than recursing for lower levels. Bah.
2690 (while (and (not (eobp))
2691 ; Still within original topic?
2692 (< orig-depth (setq curr-depth allout-recent-depth))
2693 (cond ((= prev-depth curr-depth)
2694 ;; Register this one and move on:
2695 (setq chart (cons allout-recent-prefix-beginning chart))
2696 (if (and levels (<= levels 1))
2697 ;; At depth limit -- skip sublevels:
2698 (or (allout-next-sibling curr-depth)
2699 ;; or no more siblings -- proceed to
2700 ;; next heading at lesser depth:
2701 (while (and (<= curr-depth
2702 allout-recent-depth)
2704 (allout-next-visible-heading 1)
2705 (allout-next-heading)))))
2707 (allout-next-visible-heading 1)
2708 (allout-next-heading))))
2710 ((and (< prev-depth curr-depth)
2713 ;; Recurse on deeper level of curr topic:
2715 (cons (allout-chart-subtree (and levels
2721 ;; ... then continue with this one.
2724 ;; ... else nil if we've ascended back to prev-depth.
2728 (if original ; We're at the last sibling on
2729 ; the original level. Position
2731 (progn (and (not (eobp)) (forward-char -1))
2732 (and (= (preceding-char) ?\n)
2733 (= (aref (buffer-substring (max 1 (- (point) 3))
2738 (setq allout-recent-end-of-subtree (point))))
2740 chart ; (nreverse chart) not necessary,
2741 ; and maybe not preferable.
2743 ;;;_ > allout-chart-siblings (&optional start end)
2744 (defun allout-chart-siblings (&optional start end)
2745 "Produce a list of locations of this and succeeding sibling topics.
2746 Effectively a top-level chart of siblings. See `allout-chart-subtree'
2747 for an explanation of charts."
2749 (when (allout-goto-prefix-doublechecked)
2750 (let ((chart (list (point))))
2751 (while (allout-next-sibling)
2752 (setq chart (cons (point) chart)))
2753 (if chart (setq chart (nreverse chart)))))))
2754 ;;;_ > allout-chart-to-reveal (chart depth)
2755 (defun allout-chart-to-reveal (chart depth)
2757 "Return a flat list of hidden points in subtree CHART, up to DEPTH.
2759 If DEPTH is nil, include hidden points at any depth.
2761 Note that point can be left at any of the points on chart, or at the
2765 (while (and (or (null depth) (> depth 0))
2767 (setq here (car chart))
2769 (let ((further (allout-chart-to-reveal here (if (null depth)
2772 ;; We're on the start of a subtree -- recurse with it, if there's
2773 ;; more depth to go:
2774 (if further (setq result (append further result)))
2775 (setq chart (cdr chart)))
2777 (if (allout-hidden-p)
2778 (setq result (cons here result)))
2779 (setq chart (cdr chart))))
2781 ;;;_ X allout-chart-spec (chart spec &optional exposing)
2782 ;; (defun allout-chart-spec (chart spec &optional exposing)
2783 ;; "Not yet (if ever) implemented.
2785 ;; Produce exposure directives given topic/subtree CHART and an exposure SPEC.
2787 ;; Exposure spec indicates the locations to be exposed and the prescribed
2788 ;; exposure status. Optional arg EXPOSING is an integer, with 0
2789 ;; indicating pending concealment, anything higher indicating depth to
2790 ;; which subtopic headers should be exposed, and negative numbers
2791 ;; indicating (negative of) the depth to which subtopic headers and
2792 ;; bodies should be exposed.
2794 ;; The produced list can have two types of entries. Bare numbers
2795 ;; indicate points in the buffer where topic headers that should be
2798 ;; - bare negative numbers indicates that the topic starting at the
2799 ;; point which is the negative of the number should be opened,
2800 ;; including their entries.
2801 ;; - bare positive values indicate that this topic header should be
2803 ;; - Lists signify the beginning and end points of regions that should
2804 ;; be flagged, and the flag to employ. (For concealment: `(\?r)', and
2807 ;; (cond ((listp spec)
2810 ;; (setq spec (cdr spec)))
2814 ;;;_ > allout-goto-prefix ()
2815 (defun allout-goto-prefix ()
2816 "Put point at beginning of immediately containing outline topic.
2818 Goes to most immediate subsequent topic if none immediately containing.
2820 Not sensitive to topic visibility.
2822 Returns the point at the beginning of the prefix, or nil if none."
2826 (while (and (not done)
2827 (search-backward "\n" nil 1))
2829 (if (looking-at allout-regexp)
2830 (setq done (allout-prefix-data))
2833 (cond ((looking-at allout-regexp)
2834 (allout-prefix-data))
2835 ((allout-next-heading))
2838 ;;;_ > allout-goto-prefix-doublechecked ()
2839 (defun allout-goto-prefix-doublechecked ()
2840 "Put point at beginning of immediately containing outline topic.
2842 Like `allout-goto-prefix', but shallow topics (according to
2843 `allout-doublecheck-at-and-shallower') are checked and
2844 disqualified for child containment discontinuity, according to
2845 `allout-aberrant-container-p'."
2846 (if (allout-goto-prefix)
2847 (if (and (allout-do-doublecheck)
2848 (allout-aberrant-container-p))
2849 (allout-previous-heading)
2852 ;;;_ > allout-end-of-prefix ()
2853 (defun allout-end-of-prefix (&optional ignore-decorations)
2854 "Position cursor at beginning of header text.
2856 If optional IGNORE-DECORATIONS is non-nil, put just after bullet,
2857 otherwise skip white space between bullet and ensuing text."
2859 (if (not (allout-goto-prefix-doublechecked))
2861 (goto-char allout-recent-prefix-end)
2863 (if ignore-decorations
2865 (while (looking-at "[0-9]") (forward-char 1))
2866 (if (and (not (eolp)) (looking-at "\\s-")) (forward-char 1))))
2867 ;; Reestablish where we are:
2868 (allout-current-depth)))
2869 ;;;_ > allout-current-bullet-pos ()
2870 (defun allout-current-bullet-pos ()
2871 "Return position of current (visible) topic's bullet."
2873 (if (not (allout-current-depth))
2875 (1- allout-recent-prefix-end)))
2876 ;;;_ > allout-back-to-current-heading (&optional interactive)
2877 (defun allout-back-to-current-heading (&optional interactive)
2878 "Move to heading line of current topic, or beginning if not in a topic.
2880 If interactive, we position at the end of the prefix.
2882 Return value of resulting point, unless we started outside
2883 of (before any) topics, in which case we return nil."
2887 (allout-beginning-of-current-line)
2888 (let ((bol-point (point)))
2889 (when (allout-goto-prefix-doublechecked)
2890 (if (<= (point) bol-point)
2892 (setq bol-point (point))
2893 (allout-beginning-of-current-line)
2894 (if (not (= bol-point (point)))
2895 (if (looking-at allout-regexp)
2896 (allout-prefix-data)))
2898 (allout-end-of-prefix)
2900 (goto-char (point-min))
2902 ;;;_ > allout-back-to-heading ()
2903 (defalias 'allout-back-to-heading 'allout-back-to-current-heading)
2904 ;;;_ > allout-pre-next-prefix ()
2905 (defun allout-pre-next-prefix ()
2906 "Skip forward to just before the next heading line.
2908 Returns that character position."
2910 (if (allout-next-heading)
2911 (goto-char (1- allout-recent-prefix-beginning))))
2912 ;;;_ > allout-end-of-subtree (&optional current include-trailing-blank)
2913 (defun allout-end-of-subtree (&optional current include-trailing-blank)
2914 "Put point at the end of the last leaf in the containing topic.
2916 Optional CURRENT means put point at the end of the containing
2919 Optional INCLUDE-TRAILING-BLANK means include a trailing blank line, if
2920 any, as part of the subtree. Otherwise, that trailing blank will be
2921 excluded as delimiting whitespace between topics.
2923 Returns the value of point."
2926 (allout-back-to-current-heading)
2927 (allout-goto-prefix-doublechecked))
2928 (let ((level allout-recent-depth))
2929 (allout-next-heading)
2930 (while (and (not (eobp))
2931 (> allout-recent-depth level))
2932 (allout-next-heading))
2934 (allout-end-of-entry)
2936 (if (and (not include-trailing-blank) (= ?\n (preceding-char)))
2938 (setq allout-recent-end-of-subtree (point))))
2939 ;;;_ > allout-end-of-current-subtree (&optional include-trailing-blank)
2940 (defun allout-end-of-current-subtree (&optional include-trailing-blank)
2942 "Put point at end of last leaf in currently visible containing topic.
2944 Optional INCLUDE-TRAILING-BLANK means include a trailing blank line, if
2945 any, as part of the subtree. Otherwise, that trailing blank will be
2946 excluded as delimiting whitespace between topics.
2948 Returns the value of point."
2950 (allout-end-of-subtree t include-trailing-blank))
2951 ;;;_ > allout-beginning-of-current-entry (&optional interactive)
2952 (defun allout-beginning-of-current-entry (&optional interactive)
2953 "When not already there, position point at beginning of current topic header.
2955 If already there, move cursor to bullet for hot-spot operation.
2956 \(See `allout-mode' doc string for details of hot-spot operation.)"
2958 (let ((start-point (point)))
2959 (move-beginning-of-line 1)
2960 (if (< 0 (allout-current-depth))
2961 (goto-char allout-recent-prefix-end)
2962 (goto-char (point-min)))
2963 (allout-end-of-prefix)
2964 (if (and interactive
2965 (= (point) start-point))
2966 (goto-char (allout-current-bullet-pos)))))
2967 ;;;_ > allout-end-of-entry (&optional inclusive)
2968 (defun allout-end-of-entry (&optional inclusive)
2969 "Position the point at the end of the current topics' entry.
2971 Optional INCLUSIVE means also include trailing empty line, if any. When
2972 unset, whitespace between items separates them even when the items are
2975 (allout-pre-next-prefix)
2976 (if (and (not inclusive) (not (bobp)) (= ?\n (preceding-char)))
2979 ;;;_ > allout-end-of-current-heading ()
2980 (defun allout-end-of-current-heading ()
2982 (allout-beginning-of-current-entry)
2983 (search-forward "\n" nil t)
2985 (defalias 'allout-end-of-heading 'allout-end-of-current-heading)
2986 ;;;_ > allout-get-body-text ()
2987 (defun allout-get-body-text ()
2988 "Return the unmangled body text of the topic immediately containing point."
2990 (allout-end-of-prefix)
2991 (if (not (search-forward "\n" nil t))
2994 (let ((pre-body (point)))
2997 (allout-end-of-entry t)
2998 (if (not (= pre-body (point)))
2999 (buffer-substring-no-properties (1+ pre-body) (point))))
3006 ;;;_ > allout-ascend-to-depth (depth)
3007 (defun allout-ascend-to-depth (depth)
3008 "Ascend to depth DEPTH, returning depth if successful, nil if not."
3009 (if (and (> depth 0)(<= depth (allout-depth)))
3010 (let (last-ascended)
3011 (while (and (< depth allout-recent-depth)
3012 (setq last-ascended (allout-ascend))))
3013 (goto-char allout-recent-prefix-beginning)
3014 (if (allout-called-interactively-p) (allout-end-of-prefix))
3015 (and last-ascended allout-recent-depth))))
3016 ;;;_ > allout-ascend (&optional dont-move-if-unsuccessful)
3017 (defun allout-ascend (&optional dont-move-if-unsuccessful)
3018 "Ascend one level, returning resulting depth if successful, nil if not.
3020 Point is left at the beginning of the level whether or not
3021 successful, unless optional DONT-MOVE-IF-UNSUCCESSFUL is set, in
3022 which case point is returned to its original starting location."
3023 (if dont-move-if-unsuccessful
3024 (setq dont-move-if-unsuccessful (point)))
3026 (if (allout-beginning-of-level)
3027 (let ((bolevel (point))
3028 (bolevel-depth allout-recent-depth))
3029 (allout-previous-heading)
3030 (cond ((< allout-recent-depth bolevel-depth)
3031 allout-recent-depth)
3032 ((= allout-recent-depth bolevel-depth)
3033 (if dont-move-if-unsuccessful
3034 (goto-char dont-move-if-unsuccessful))
3038 ;; some topic after very first is lower depth than first:
3042 (if (allout-called-interactively-p) (allout-end-of-prefix))))
3043 ;;;_ > allout-descend-to-depth (depth)
3044 (defun allout-descend-to-depth (depth)
3045 "Descend to depth DEPTH within current topic.
3047 Returning depth if successful, nil if not."
3048 (let ((start-point (point))
3049 (start-depth (allout-depth)))
3051 (and (> (allout-depth) 0)
3052 (not (= depth allout-recent-depth)) ; ... not there yet
3053 (allout-next-heading) ; ... go further
3054 (< start-depth allout-recent-depth))) ; ... still in topic
3055 (if (and (> (allout-depth) 0)
3056 (= allout-recent-depth depth))
3058 (goto-char start-point)
3061 ;;;_ > allout-up-current-level (arg)
3062 (defun allout-up-current-level (arg)
3063 "Move out ARG levels from current visible topic."
3065 (let ((start-point (point)))
3066 (allout-back-to-current-heading)
3067 (if (not (allout-ascend))
3068 (progn (goto-char start-point)
3069 (error "Can't ascend past outermost level"))
3070 (if (allout-called-interactively-p) (allout-end-of-prefix))
3071 allout-recent-prefix-beginning)))
3074 ;;;_ > allout-next-sibling (&optional depth backward)
3075 (defun allout-next-sibling (&optional depth backward)
3076 "Like `allout-forward-current-level', but respects invisible topics.
3078 Traverse at optional DEPTH, or current depth if none specified.
3080 Go backward if optional arg BACKWARD is non-nil.
3082 Return the start point of the new topic if successful, nil otherwise."
3084 (if (if backward (bobp) (eobp))
3086 (let ((target-depth (or depth (allout-depth)))
3087 (start-point (point))
3088 (start-prefix-beginning allout-recent-prefix-beginning)
3093 ;; done too few single steps to resort to the leap routine:
3096 (not (if backward (bobp) (eobp)))
3097 ;; still traversable:
3098 (if backward (allout-previous-heading) (allout-next-heading))
3099 ;; we're below the target depth
3100 (> (setq last-depth allout-recent-depth) target-depth))
3101 (setq count (1+ count))
3102 (if (> count 7) ; lists are commonly 7 +- 2, right?-)
3105 (or (allout-next-sibling-leap target-depth backward)
3107 (goto-char start-point)
3108 (if depth (allout-depth) target-depth)
3111 (and (> (or last-depth (allout-depth)) 0)
3112 (= allout-recent-depth target-depth))
3113 (not (= start-prefix-beginning
3114 allout-recent-prefix-beginning)))
3115 allout-recent-prefix-beginning)
3117 (goto-char start-point)
3118 (if depth (allout-depth) target-depth)
3120 ;;;_ > allout-next-sibling-leap (&optional depth backward)
3121 (defun allout-next-sibling-leap (&optional depth backward)
3122 "Like `allout-next-sibling', but by direct search for topic at depth.
3124 Traverse at optional DEPTH, or current depth if none specified.
3126 Go backward if optional arg BACKWARD is non-nil.
3128 Return the start point of the new topic if successful, nil otherwise.
3130 Costs more than regular `allout-next-sibling' for short traversals:
3132 - we have to check the prior (next, if travelling backwards)
3133 item to confirm connectivity with the prior topic, and
3134 - if confirmed, we have to reestablish the allout-recent-* settings with
3135 some extra navigation
3136 - if confirmation fails, we have to do more work to recover
3138 It is an increasingly big win when there are many intervening
3139 offspring before the next sibling, however, so
3140 `allout-next-sibling' resorts to this if it finds itself in that
3143 (if (if backward (bobp) (eobp))
3145 (let* ((start-point (point))
3146 (target-depth (or depth (allout-depth)))
3147 (search-whitespace-regexp nil)
3148 (depth-biased (- target-depth 2))
3149 (expression (if (<= target-depth 1)
3150 allout-depth-one-regexp
3151 (format allout-depth-specific-regexp
3152 depth-biased depth-biased)))
3156 (setq found (save-match-data
3158 (re-search-backward expression nil 'to-limit)
3160 (re-search-forward expression nil 'to-limit))))
3161 (if (and found (allout-aberrant-container-p))
3163 (setq done (or found (if backward (bobp) (eobp)))))
3165 (progn (goto-char start-point)
3167 ;; rationale: if any intervening items were at a lower depth, we
3168 ;; would now be on the first offspring at the target depth -- ie,
3169 ;; the preceeding item (per the search direction) must be at a
3170 ;; lesser depth. that's all we need to check.
3171 (if backward (allout-next-heading) (allout-previous-heading))
3172 (if (< allout-recent-depth target-depth)
3173 ;; return to start and reestablish allout-recent-*:
3175 (goto-char start-point)
3179 ;; locate cursor and set allout-recent-*:
3180 (allout-goto-prefix))))))
3181 ;;;_ > allout-previous-sibling (&optional depth backward)
3182 (defun allout-previous-sibling (&optional depth backward)
3183 "Like `allout-forward-current-level' backwards, respecting invisible topics.
3185 Optional DEPTH specifies depth to traverse, default current depth.
3187 Optional BACKWARD reverses direction.
3189 Return depth if successful, nil otherwise."
3190 (allout-next-sibling depth (not backward))
3192 ;;;_ > allout-snug-back ()
3193 (defun allout-snug-back ()
3194 "Position cursor at end of previous topic.
3196 Presumes point is at the start of a topic prefix."
3197 (if (or (bobp) (eobp))
3200 (if (or (bobp) (not (= ?\n (preceding-char))))
3204 ;;;_ > allout-beginning-of-level ()
3205 (defun allout-beginning-of-level ()
3206 "Go back to the first sibling at this level, visible or not."
3207 (allout-end-of-level 'backward))
3208 ;;;_ > allout-end-of-level (&optional backward)
3209 (defun allout-end-of-level (&optional backward)
3210 "Go to the last sibling at this level, visible or not."
3212 (let ((depth (allout-depth)))
3213 (while (allout-previous-sibling depth nil))
3214 (prog1 allout-recent-depth
3215 (if (allout-called-interactively-p) (allout-end-of-prefix)))))
3216 ;;;_ > allout-next-visible-heading (arg)
3217 (defun allout-next-visible-heading (arg)
3218 "Move to the next ARG'th visible heading line, backward if arg is negative.
3220 Move to buffer limit in indicated direction if headings are exhausted."
3223 (let* ((inhibit-field-text-motion t)
3224 (backward (if (< arg 0) (setq arg (* -1 arg))))
3225 (step (if backward -1 1))
3226 (progress (allout-current-bullet-pos))
3231 ;; Boundary condition:
3232 (not (if backward (bobp)(eobp)))
3233 ;; Move, skipping over all concealed lines in one fell swoop:
3234 (prog1 (condition-case nil (or (line-move step) t)
3236 (allout-beginning-of-current-line)
3237 ;; line-move can wind up on the same line if long.
3238 ;; when moving forward, that would yield no-progress
3239 (when (and (not backward)
3240 (<= (point) progress))
3241 ;; ensure progress by doing line-move from end-of-line:
3243 (condition-case nil (or (line-move step) t)
3245 (allout-beginning-of-current-line)
3246 (setq progress (point))))
3247 ;; Deal with apparent header line:
3249 (if (not (looking-at allout-regexp))
3250 ;; not a header line, keep looking:
3252 (allout-prefix-data)
3253 (if (and (allout-do-doublecheck)
3254 (allout-aberrant-container-p))
3255 ;; skip this aberrant prospective header line:
3257 ;; this prospective headerline qualifies -- register:
3258 (setq got allout-recent-prefix-beginning)
3259 ;; and break the loop:
3261 ;; Register this got, it may be the last:
3262 (if got (setq prev got))
3263 (setq arg (1- arg)))
3264 (cond (got ; Last move was to a prefix:
3265 (allout-end-of-prefix))
3266 (prev ; Last move wasn't, but prev was:
3268 (allout-end-of-prefix))
3269 ((not backward) (end-of-line) nil))))
3270 ;;;_ > allout-previous-visible-heading (arg)
3271 (defun allout-previous-visible-heading (arg)
3272 "Move to the previous heading line.
3274 With argument, repeats or can move forward if negative.
3275 A heading line is one that starts with a `*' (or that `allout-regexp'
3278 (prog1 (allout-next-visible-heading (- arg))
3279 (if (allout-called-interactively-p) (allout-end-of-prefix))))
3280 ;;;_ > allout-forward-current-level (arg)
3281 (defun allout-forward-current-level (arg)
3282 "Position point at the next heading of the same level.
3284 Takes optional repeat-count, goes backward if count is negative.
3286 Returns resulting position, else nil if none found."
3288 (let ((start-depth (allout-current-depth))
3290 (backward (> 0 arg)))
3291 (if (= 0 start-depth)
3292 (error "No siblings, not in a topic..."))
3293 (if backward (setq arg (* -1 arg)))
3294 (allout-back-to-current-heading)
3295 (while (and (not (zerop arg))
3297 (allout-previous-sibling)
3298 (allout-next-sibling)))
3299 (setq arg (1- arg)))
3300 (if (not (allout-called-interactively-p))
3302 (allout-end-of-prefix)
3303 (if (not (zerop arg))
3304 (error "Hit %s level %d topic, traversed %d of %d requested"
3305 (if backward "first" "last")
3307 (- (abs start-arg) arg)
3308 (abs start-arg))))))
3309 ;;;_ > allout-backward-current-level (arg)
3310 (defun allout-backward-current-level (arg)
3311 "Inverse of `allout-forward-current-level'."
3313 (if (allout-called-interactively-p)
3314 (let ((current-prefix-arg (* -1 arg)))
3315 (call-interactively 'allout-forward-current-level))
3316 (allout-forward-current-level (* -1 arg))))
3321 ;;;_ = allout-post-goto-bullet
3322 (defvar allout-post-goto-bullet nil
3323 "Outline internal var, for `allout-pre-command-business' hot-spot operation.
3325 When set, tells post-processing to reposition on topic bullet, and
3326 then unset it. Set by `allout-pre-command-business' when implementing
3327 hot-spot operation, where literal characters typed over a topic bullet
3328 are mapped to the command of the corresponding control-key on the
3329 `allout-mode-map-value'.")
3330 (make-variable-buffer-local 'allout-post-goto-bullet)
3331 ;;;_ = allout-command-counter
3332 (defvar allout-command-counter 0
3333 "Counter that monotonically increases in allout-mode buffers.
3335 Set by `allout-pre-command-business', to support allout addons in
3336 coordinating with allout activity.")
3337 (make-variable-buffer-local 'allout-command-counter)
3338 ;;;_ > allout-post-command-business ()
3339 (defun allout-post-command-business ()
3340 "Outline `post-command-hook' function.
3342 - Implement (and clear) `allout-post-goto-bullet', for hot-spot
3345 - Decrypt topic currently being edited if it was encrypted for a save."
3347 ; Apply any external change func:
3348 (if (not (allout-mode-p)) ; In allout-mode.
3351 (if (and (boundp 'allout-after-save-decrypt)
3352 allout-after-save-decrypt)
3353 (allout-after-saves-handler))
3355 ;; Implement allout-post-goto-bullet, if set:
3356 (if (and allout-post-goto-bullet
3357 (allout-current-bullet-pos))
3358 (progn (goto-char (allout-current-bullet-pos))
3359 (setq allout-post-goto-bullet nil)))
3361 ;;;_ > allout-pre-command-business ()
3362 (defun allout-pre-command-business ()
3363 "Outline `pre-command-hook' function for outline buffers.
3365 Among other things, implements special behavior when the cursor is on the
3366 topic bullet character.
3368 When the cursor is on the bullet character, self-insert
3369 characters are reinterpreted as the corresponding
3370 control-character in the `allout-mode-map-value'. The
3371 `allout-mode' `post-command-hook' insures that the cursor which
3372 has moved as a result of such reinterpretation is positioned on
3373 the bullet character of the destination topic.
3375 The upshot is that you can get easy, single (ie, unmodified) key
3376 outline maneuvering operations by positioning the cursor on the bullet
3377 char. When in this mode you can use regular cursor-positioning
3378 command/keystrokes to relocate the cursor off of a bullet character to
3379 return to regular interpretation of self-insert characters."
3381 (if (not (allout-mode-p))
3383 ;; Increment allout-command-counter
3384 (setq allout-command-counter (1+ allout-command-counter))
3385 ;; Do hot-spot navigation.
3386 (if (and (eq this-command 'self-insert-command)
3387 (eq (point)(allout-current-bullet-pos)))
3388 (allout-hotspot-key-handler))))
3389 ;;;_ > allout-hotspot-key-handler ()
3390 (defun allout-hotspot-key-handler ()
3391 "Catchall handling of key bindings in hot-spots.
3393 Translates unmodified keystrokes to corresponding allout commands, when
3394 they would qualify if prefixed with the allout-command-prefix, and sets
3395 this-command accordingly.
3397 Returns the qualifying command, if any, else nil."
3399 (let* ((modified (event-modifiers last-command-event))
3400 (key-num (cond ((numberp last-command-event) last-command-event)
3401 ;; for XEmacs character type:
3402 ((and (fboundp 'characterp)
3403 (apply 'characterp (list last-command-event)))
3404 (apply 'char-to-int (list last-command-event)))
3412 ;; exclude control chars and escape:
3415 (setq mapped-binding
3417 ;; try control-modified versions of keys:
3418 (key-binding (vconcat allout-command-prefix
3420 (if (and (<= 97 key-num) ; "a"
3421 (>= 122 key-num)) ; "z"
3422 (- key-num 96) key-num)))
3424 ;; try non-modified versions of keys:
3425 (key-binding (vconcat allout-command-prefix
3428 ;; Qualified as an allout command -- do hot-spot operation.
3429 (setq allout-post-goto-bullet t)
3430 ;; accept-defaults nil, or else we get allout-item-icon-key-handler.
3431 (setq mapped-binding (key-binding (vector key-num))))
3433 (while (keymapp mapped-binding)
3434 (setq mapped-binding
3435 (lookup-key mapped-binding (vector (read-char)))))
3437 (when mapped-binding
3438 (setq this-command mapped-binding)))))
3440 ;;;_ > allout-find-file-hook ()
3441 (defun allout-find-file-hook ()
3442 "Activate `allout-mode' on non-nil `allout-auto-activation', `allout-layout'.
3444 See `allout-init' for setup instructions."
3445 (if (and allout-auto-activation
3446 (not (allout-mode-p))
3450 ;;;_ - Topic Format Assessment
3451 ;;;_ > allout-solicit-alternate-bullet (depth &optional current-bullet)
3452 (defun allout-solicit-alternate-bullet (depth &optional current-bullet)
3454 "Prompt for and return a bullet char as an alternative to the current one.
3456 Offer one suitable for current depth DEPTH as default."
3458 (let* ((default-bullet (or (and (stringp current-bullet) current-bullet)
3459 (allout-bullet-for-depth depth)))
3460 (sans-escapes (regexp-sans-escapes allout-bullets-string))
3463 (goto-char (allout-current-bullet-pos))
3464 (setq choice (solicit-char-in-string
3465 (format "Select bullet: %s ('%s' default): "
3467 (allout-substring-no-properties default-bullet))
3471 (if (string= choice "") default-bullet choice))
3473 ;;;_ > allout-distinctive-bullet (bullet)
3474 (defun allout-distinctive-bullet (bullet)
3475 "True if BULLET is one of those on `allout-distinctive-bullets-string'."
3476 (string-match (regexp-quote bullet) allout-distinctive-bullets-string))
3477 ;;;_ > allout-numbered-type-prefix (&optional prefix)
3478 (defun allout-numbered-type-prefix (&optional prefix)
3479 "True if current header prefix bullet is numbered bullet."
3480 (and allout-numbered-bullet
3481 (string= allout-numbered-bullet
3483 (allout-get-prefix-bullet prefix)
3484 (allout-get-bullet)))))
3485 ;;;_ > allout-encrypted-type-prefix (&optional prefix)
3486 (defun allout-encrypted-type-prefix (&optional prefix)
3487 "True if current header prefix bullet is for an encrypted entry (body)."
3488 (and allout-topic-encryption-bullet
3489 (string= allout-topic-encryption-bullet
3491 (allout-get-prefix-bullet prefix)
3492 (allout-get-bullet)))))
3493 ;;;_ > allout-bullet-for-depth (&optional depth)
3494 (defun allout-bullet-for-depth (&optional depth)
3495 "Return outline topic bullet suited to optional DEPTH, or current depth."
3496 ;; Find bullet in plain-bullets-string modulo DEPTH.
3497 (if allout-stylish-prefixes
3498 (char-to-string (aref allout-plain-bullets-string
3499 (% (max 0 (- depth 2))
3500 allout-plain-bullets-string-len)))
3501 allout-primary-bullet)
3504 ;;;_ - Topic Production
3505 ;;;_ > allout-make-topic-prefix (&optional prior-bullet
3506 (defun allout-make-topic-prefix (&optional prior-bullet
3512 ;; Depth null means use current depth, non-null means we're either
3513 ;; opening a new topic after current topic, lower or higher, or we're
3514 ;; changing level of current topic.
3515 ;; Solicit dominates specified bullet-char.
3517 "Generate a topic prefix suitable for optional arg DEPTH, or current depth.
3519 All the arguments are optional.
3521 PRIOR-BULLET indicates the bullet of the prefix being changed, or
3522 nil if none. This bullet may be preserved (other options
3523 notwithstanding) if it is on the `allout-distinctive-bullets-string',
3526 Second arg NEW indicates that a new topic is being opened after the
3527 topic at point, if non-nil. Default bullet for new topics, eg, may
3528 be set (contingent to other args) to numbered bullets if previous
3529 sibling is one. The implication otherwise is that the current topic
3530 is being adjusted -- shifted or rebulleted -- and we don't consider
3531 bullet or previous sibling.
3533 Third arg DEPTH forces the topic prefix to that depth, regardless of
3534 the current topics' depth.
3536 If SOLICIT is non-nil, then the choice of bullet is solicited from
3537 user. If it's a character, then that character is offered as the
3538 default, otherwise the one suited to the context (according to
3539 distinction or depth) is offered. (This overrides other options,
3540 including, eg, a distinctive PRIOR-BULLET.) If non-nil, then the
3541 context-specific bullet is used.
3543 Fifth arg, NUMBER-CONTROL, matters only if `allout-numbered-bullet'
3544 is non-nil *and* soliciting was not explicitly invoked. Then
3545 NUMBER-CONTROL non-nil forces prefix to either numbered or
3546 denumbered format, depending on the value of the sixth arg, INDEX.
3548 \(Note that NUMBER-CONTROL does *not* apply to level 1 topics. Sorry...)
3550 If NUMBER-CONTROL is non-nil and sixth arg INDEX is non-nil then
3551 the prefix of the topic is forced to be numbered. Non-nil
3552 NUMBER-CONTROL and nil INDEX forces non-numbered format on the
3553 bullet. Non-nil NUMBER-CONTROL and non-nil, non-number INDEX means
3554 that the index for the numbered prefix will be derived, by counting
3555 siblings back to start of level. If INDEX is a number, then that
3556 number is used as the index for the numbered prefix (allowing, eg,
3557 sequential renumbering to not require this function counting back the
3558 index for each successive sibling)."
3560 ;; The options are ordered in likely frequence of use, most common
3561 ;; highest, least lowest. Ie, more likely to be doing prefix
3562 ;; adjustments than soliciting, and yet more than numbering.
3563 ;; Current prefix is least dominant, but most likely to be commonly
3569 (depth (or depth (allout-depth)))
3570 (header-lead allout-header-prefix)
3573 ;; Getting value for bullet char is practically the whole job:
3576 ; Simplest situation -- level 1:
3577 ((<= depth 1) (setq header-lead "") allout-primary-bullet)
3578 ; Simple, too: all asterisks:
3579 (allout-old-style-prefixes
3580 ;; Cheat -- make body the whole thing, null out header-lead and
3582 (setq body (make-string depth
3583 (string-to-char allout-primary-bullet)))
3584 (setq header-lead "")
3587 ;; (Neither level 1 nor old-style, so we're space padding.
3588 ;; Sneak it in the condition of the next case, whatever it is.)
3590 ;; Solicitation overrides numbering and other cases:
3591 ((progn (setq body (make-string (- depth 2) ?\ ))
3592 ;; The actual condition:
3594 (let* ((got (allout-solicit-alternate-bullet depth solicit)))
3595 ;; Gotta check whether we're numbering and got a numbered bullet:
3596 (setq numbering (and allout-numbered-bullet
3597 (not (and number-control (not index)))
3598 (string= got allout-numbered-bullet)))
3599 ;; Now return what we got, regardless:
3602 ;; Numbering invoked through args:
3603 ((and allout-numbered-bullet number-control)
3604 (if (setq numbering (not (setq denumbering (not index))))
3605 allout-numbered-bullet
3606 (if (and prior-bullet
3607 (not (string= allout-numbered-bullet
3610 (allout-bullet-for-depth depth))))
3612 ;;; Neither soliciting nor controlled numbering ;;;
3613 ;;; (may be controlled denumbering, tho) ;;;
3615 ;; Check wrt previous sibling:
3616 ((and new ; only check for new prefixes
3617 (<= depth (allout-depth))
3618 allout-numbered-bullet ; ... & numbering enabled
3620 (let ((sibling-bullet
3622 ;; Locate correct sibling:
3623 (or (>= depth (allout-depth))
3624 (allout-ascend-to-depth depth))
3625 (allout-get-bullet))))
3626 (if (and sibling-bullet
3627 (string= allout-numbered-bullet sibling-bullet))
3628 (setq numbering sibling-bullet)))))
3630 ;; Distinctive prior bullet?
3632 (allout-distinctive-bullet prior-bullet)
3633 ;; Either non-numbered:
3634 (or (not (and allout-numbered-bullet
3635 (string= prior-bullet allout-numbered-bullet)))
3636 ;; or numbered, and not denumbering:
3637 (setq numbering (not denumbering)))
3641 ;; Else, standard bullet per depth:
3642 ((allout-bullet-for-depth depth)))))
3648 (format "%d" (cond ((and index (numberp index)) index)
3649 (new (1+ (allout-sibling-index depth)))
3650 ((allout-sibling-index))))))
3653 ;;;_ > allout-open-topic (relative-depth &optional before offer-recent-bullet)
3654 (defun allout-open-topic (relative-depth &optional before offer-recent-bullet)
3655 "Open a new topic at depth DEPTH.
3657 New topic is situated after current one, unless optional flag BEFORE
3658 is non-nil, or unless current line is completely empty -- lacking even
3659 whitespace -- in which case open is done on the current line.
3661 When adding an offspring, it will be added immediately after the parent if
3662 the other offspring are exposed, or after the last child if the offspring
3663 are hidden. (The intervening offspring will be exposed in the latter
3666 If OFFER-RECENT-BULLET is true, offer to use the bullet of the prior sibling.
3670 - Creation of new topics is with respect to the visible topic
3671 containing the cursor, regardless of intervening concealed ones.
3673 - New headers are generally created after/before the body of a
3674 topic. However, they are created right at cursor location if the
3675 cursor is on a blank line, even if that breaks the current topic
3676 body. This is intentional, to provide a simple means for
3677 deliberately dividing topic bodies.
3679 - Double spacing of topic lists is preserved. Also, the first
3680 level two topic is created double-spaced (and so would be
3681 subsequent siblings, if that's left intact). Otherwise,
3682 single-spacing is used.
3684 - Creation of sibling or nested topics is with respect to the topic
3685 you're starting from, even when creating backwards. This way you
3686 can easily create a sibling in front of the current topic without
3687 having to go to its preceding sibling, and then open forward
3690 (allout-beginning-of-current-line)
3692 (let* ((inhibit-field-text-motion t)
3693 (depth (+ (allout-current-depth) relative-depth))
3694 (opening-on-blank (if (looking-at "^\$")
3695 (not (setq before nil))))
3696 ;; bunch o vars set while computing ref-topic
3700 (ref-topic (save-excursion
3701 (cond ((< relative-depth 0)
3702 (allout-ascend-to-depth depth))
3703 ((>= relative-depth 1) nil)
3704 (t (allout-back-to-current-heading)))
3705 (setq ref-depth allout-recent-depth)
3707 (if (> allout-recent-prefix-end 1)
3708 (allout-recent-bullet)
3710 (setq opening-numbered
3712 (and allout-numbered-bullet
3713 (or (<= relative-depth 0)
3714 (allout-descend-to-depth depth))
3715 (if (allout-numbered-type-prefix)
3716 allout-numbered-bullet))))
3722 (if (not opening-on-blank)
3723 ; Positioning and vertical
3724 ; padding -- only if not
3727 (goto-char ref-topic)
3728 (setq dbl-space ; Determine double space action:
3729 (or (and (<= relative-depth 0) ; not descending;
3731 ;; at b-o-b or preceded by a blank line?
3732 (or (> 0 (forward-line -1))
3733 (looking-at "^\\s-*$")
3736 ;; succeeded by a blank line?
3737 (allout-end-of-current-subtree)
3738 (looking-at "\n\n")))
3739 (and (= ref-depth 1)
3743 ;; Don't already have following
3744 ;; vertical padding:
3745 (not (allout-pre-next-prefix)))))))
3747 ;; Position to prior heading, if inserting backwards, and not
3749 (if (and before (>= relative-depth 0))
3750 (progn (allout-back-to-current-heading)
3751 (setq doing-beginning (bobp))
3753 (allout-previous-heading)))
3754 (if (and before (bobp))
3757 (if (<= relative-depth 0)
3758 ;; Not going inwards, don't snug up:
3764 (progn (end-of-line)
3765 (allout-pre-next-prefix)
3766 (while (and (= ?\n (following-char))
3771 (if (not (looking-at "^$"))
3773 (allout-end-of-current-subtree)
3774 (if (looking-at "\n\n") (forward-char 1))))
3775 ;; Going inwards -- double-space if first offspring is
3776 ;; double-spaced, otherwise snug up.
3777 (allout-end-of-entry)
3781 (allout-beginning-of-current-line)
3784 ;; Blank lines between current header body and next
3785 ;; header -- get to last substantive (non-white-space)
3787 (progn (setq dbl-space t)
3788 (re-search-backward "[^ \t\n]" nil t)))
3789 (if (looking-at "\n\n")
3792 (allout-next-heading)
3793 (when (> allout-recent-depth ref-depth)
3794 ;; This is an offspring.
3796 (looking-at "^\\s-*$")))
3797 (progn (forward-line 1)
3800 (allout-end-of-current-line))
3802 ;;(if doing-beginning (goto-char doing-beginning))
3804 ;; We insert a newline char rather than using open-line to
3805 ;; avoid rear-stickiness inheritence of read-only property.
3806 (progn (if (and (not (> depth ref-depth))
3809 (if (and (not dbl-space) (> depth ref-depth))
3815 (if (and dbl-space (not (> relative-depth 0)))
3817 (if (and (not (eobp))
3820 ;; bolp doesnt detect concealed
3821 ;; trailing newlines, compensate:
3824 (allout-hidden-p)))))
3827 (setq start (point))
3828 (insert (concat (allout-make-topic-prefix opening-numbered t depth)
3830 (setq end (1+ (point)))
3832 (allout-rebullet-heading (and offer-recent-bullet ref-bullet)
3834 (if (> relative-depth 0)
3835 (save-excursion (goto-char ref-topic)
3836 (allout-show-children)))
3839 (run-hook-with-args 'allout-structure-added-hook start end)
3843 ;;;_ > allout-open-subtopic (arg)
3844 (defun allout-open-subtopic (arg)
3845 "Open new topic header at deeper level than the current one.
3847 Negative universal arg means to open deeper, but place the new topic
3848 prior to the current one."
3850 (allout-open-topic 1 (> 0 arg) (< 1 arg)))
3851 ;;;_ > allout-open-sibtopic (arg)
3852 (defun allout-open-sibtopic (arg)
3853 "Open new topic header at same level as the current one.
3855 Positive universal arg means to use the bullet of the prior sibling.
3857 Negative universal arg means to place the new topic prior to the current
3860 (allout-open-topic 0 (> 0 arg) (not (= 1 arg))))
3861 ;;;_ > allout-open-supertopic (arg)
3862 (defun allout-open-supertopic (arg)
3863 "Open new topic header at shallower level than the current one.
3865 Negative universal arg means to open shallower, but place the new
3866 topic prior to the current one."
3869 (allout-open-topic -1 (> 0 arg) (< 1 arg)))
3871 ;;;_ - Outline Alteration
3872 ;;;_ : Topic Modification
3873 ;;;_ = allout-former-auto-filler
3874 (defvar allout-former-auto-filler nil
3875 "Name of modal fill function being wrapped by `allout-auto-fill'.")
3876 ;;;_ > allout-auto-fill ()
3877 (defun allout-auto-fill ()
3878 "`allout-mode' autofill function.
3880 Maintains outline hanging topic indentation if
3881 `allout-use-hanging-indents' is set."
3883 (when (not allout-inhibit-auto-fill)
3884 (let ((fill-prefix (if allout-use-hanging-indents
3885 ;; Check for topic header indentation:
3889 (if (looking-at allout-regexp)
3890 ;; ... construct indentation to account for
3891 ;; length of topic prefix:
3892 (make-string (progn (allout-end-of-prefix)
3895 (use-auto-fill-function
3896 (if (and (eq allout-outside-normal-auto-fill-function
3898 (eq auto-fill-function 'allout-auto-fill))
3900 (or allout-outside-normal-auto-fill-function
3901 auto-fill-function))))
3902 (if (or allout-former-auto-filler allout-use-hanging-indents)
3903 (funcall use-auto-fill-function)))))
3904 ;;;_ > allout-reindent-body (old-depth new-depth &optional number)
3905 (defun allout-reindent-body (old-depth new-depth &optional number)
3906 "Reindent body lines which were indented at OLD-DEPTH to NEW-DEPTH.
3908 Optional arg NUMBER indicates numbering is being added, and it must
3911 Note that refill of indented paragraphs is not done."
3914 (allout-end-of-prefix)
3915 (let* ((new-margin (current-column))
3916 excess old-indent-begin old-indent-end
3917 ;; We want the column where the header-prefix text started
3918 ;; *before* the prefix was changed, so we infer it relative
3919 ;; to the new margin and the shift in depth:
3920 (old-margin (+ old-depth (- new-margin new-depth))))
3922 ;; Process lines up to (but excluding) next topic header:
3926 (and (re-search-forward "\n\\(\\s-*\\)"
3929 ;; Register the indent data, before we reset the
3930 ;; match data with a subsequent `looking-at':
3931 (setq old-indent-begin (match-beginning 1)
3932 old-indent-end (match-end 1))
3933 (not (looking-at allout-regexp)))
3934 (if (> 0 (setq excess (- (- old-indent-end old-indent-begin)
3936 ;; Text starts left of old margin -- don't adjust:
3938 ;; Text was hanging at or right of old left margin --
3939 ;; reindent it, preserving its existing indentation
3940 ;; beyond the old margin:
3941 (delete-region old-indent-begin old-indent-end)
3942 (indent-to (+ new-margin excess (current-column))))))))))
3943 ;;;_ > allout-rebullet-current-heading (arg)
3944 (defun allout-rebullet-current-heading (arg)
3945 "Solicit new bullet for current visible heading."
3947 (let ((initial-col (current-column))
3948 (on-bullet (eq (point)(allout-current-bullet-pos)))
3950 (backwards (if (< arg 0)
3951 (setq arg (* arg -1)))))
3953 (save-excursion (allout-back-to-current-heading)
3954 (allout-end-of-prefix)
3955 (setq from allout-recent-prefix-beginning
3956 to allout-recent-prefix-end)
3957 (allout-rebullet-heading t ;;; solicit
3959 nil ;;; number-control
3961 t) ;;; do-successors
3962 (run-hook-with-args 'allout-exposure-change-hook
3967 (setq initial-col nil) ; Override positioning back to init col
3969 (allout-next-visible-heading 1)
3970 (allout-goto-prefix-doublechecked)
3971 (allout-next-visible-heading -1))))
3973 (cond (on-bullet (goto-char (allout-current-bullet-pos)))
3974 (initial-col (move-to-column initial-col)))))
3975 ;;;_ > allout-rebullet-heading (&optional solicit ...)
3976 (defun allout-rebullet-heading (&optional solicit
3982 "Adjust bullet of current topic prefix.
3984 All args are optional.
3986 If SOLICIT is non-nil, then the choice of bullet is solicited from
3987 user. If it's a character, then that character is offered as the
3988 default, otherwise the one suited to the context (according to
3989 distinction or depth) is offered. If non-nil, then the
3990 context-specific bullet is just used.
3992 Second arg DEPTH forces the topic prefix to that depth, regardless
3993 of the topic's current depth.
3995 Third arg NUMBER-CONTROL can force the prefix to or away from
3996 numbered form. It has effect only if `allout-numbered-bullet' is
3997 non-nil and soliciting was not explicitly invoked (via first arg).
3998 Its effect, numbering or denumbering, then depends on the setting
3999 of the fourth arg, INDEX.
4001 If NUMBER-CONTROL is non-nil and fourth arg INDEX is nil, then the
4002 prefix of the topic is forced to be non-numbered. Null index and
4003 non-nil NUMBER-CONTROL forces denumbering. Non-nil INDEX (and
4004 non-nil NUMBER-CONTROL) forces a numbered-prefix form. If non-nil
4005 INDEX is a number, then that number is used for the numbered
4006 prefix. Non-nil and non-number means that the index for the
4007 numbered prefix will be derived by allout-make-topic-prefix.
4009 Fifth arg DO-SUCCESSORS t means re-resolve count on succeeding
4012 Cf vars `allout-stylish-prefixes', `allout-old-style-prefixes',
4013 and `allout-numbered-bullet', which all affect the behavior of
4016 (let* ((current-depth (allout-depth))
4017 (new-depth (or new-depth current-depth))
4018 (mb allout-recent-prefix-beginning)
4019 (me allout-recent-prefix-end)
4020 (current-bullet (buffer-substring-no-properties (- me 1) me))
4021 (has-annotation (get-text-property mb 'allout-was-hidden))
4022 (new-prefix (allout-make-topic-prefix current-bullet
4029 ;; Is new one is identical to old?
4030 (if (and (= current-depth new-depth)
4031 (string= current-bullet
4032 (substring new-prefix (1- (length new-prefix)))))
4036 ;; New prefix probably different from old:
4037 ; get rid of old one:
4038 (allout-unprotected (delete-region mb me))
4040 ; Dispense with number if
4041 ; numbered-bullet prefix:
4043 (if (and allout-numbered-bullet
4044 (string= allout-numbered-bullet current-bullet)
4045 (looking-at "[0-9]+"))
4047 (delete-region (match-beginning 0)(match-end 0)))))
4049 ;; convey 'allout-was-hidden annotation, if original had it:
4051 (put-text-property 0 (length new-prefix) 'allout-was-hidden t
4054 ; Put in new prefix:
4055 (allout-unprotected (insert new-prefix))
4057 ;; Reindent the body if elected, margin changed, and not encrypted body:
4058 (if (and allout-reindent-bodies
4059 (not (= new-depth current-depth))
4060 (not (allout-encrypted-topic-p)))
4061 (allout-reindent-body current-depth new-depth))
4063 ;; Recursively rectify successive siblings of orig topic if
4064 ;; caller elected for it:
4067 (while (allout-next-sibling new-depth nil)
4069 (cond ((numberp index) (1+ index))
4070 ((not number-control) (allout-sibling-index))))
4071 (if (allout-numbered-type-prefix)
4072 (allout-rebullet-heading nil ;;; solicit
4073 new-depth ;;; new-depth
4074 number-control;;; number-control
4076 nil))))) ;;;(dont!)do-successors
4077 ) ; (if (and (= current-depth new-depth)...))
4078 ) ; let* ((current-depth (allout-depth))...)
4080 ;;;_ > allout-rebullet-topic (arg)
4081 (defun allout-rebullet-topic (arg &optional sans-offspring)
4082 "Rebullet the visible topic containing point and all contained subtopics.
4084 Descends into invisible as well as visible topics, however.
4086 When optional SANS-OFFSPRING is non-nil, subtopics are not
4087 shifted. (Shifting a topic outwards without shifting its
4088 offspring is disallowed, since this would create a \"containment
4089 discontinuity\", where the depth difference between a topic and
4090 its immediate offspring is greater than one.)
4092 With repeat count, shift topic depth by that amount."
4094 (let ((start-col (current-column)))
4097 (cond ((null arg) (setq arg 0))
4098 ((listp arg) (setq arg (car arg))))
4099 ;; Fill the user in, in case we're shifting a big topic:
4100 (if (not (zerop arg)) (message "Shifting..."))
4101 (allout-back-to-current-heading)
4102 (if (<= (+ allout-recent-depth arg) 0)
4103 (error "Attempt to shift topic below level 1"))
4104 (allout-rebullet-topic-grunt arg nil nil nil nil sans-offspring)
4105 (if (not (zerop arg)) (message "Shifting... done.")))
4106 (move-to-column (max 0 (+ start-col arg)))))
4107 ;;;_ > allout-rebullet-topic-grunt (&optional relative-depth ...)
4108 (defun allout-rebullet-topic-grunt (&optional relative-depth
4114 "Like `allout-rebullet-topic', but on nearest containing topic
4117 See `allout-rebullet-heading' for rebulleting behavior.
4119 All arguments are optional.
4121 First arg RELATIVE-DEPTH means to shift the depth of the entire
4124 Several subsequent args are for internal recursive use by the function
4125 itself: STARTING-DEPTH, STARTING-POINT, and INDEX.
4127 Finally, if optional SANS-OFFSPRING is non-nil then the offspring
4128 are not shifted. (Shifting a topic outwards without shifting
4129 its offspring is disallowed, since this would create a
4130 \"containment discontinuity\", where the depth difference between
4131 a topic and its immediate offspring is greater than one.)"
4133 ;; XXX the recursion here is peculiar, and in general the routine may
4134 ;; need simplification with refactoring.
4136 (if (and sans-offspring
4138 (< relative-depth 0))
4139 (error (concat "Attempt to shift topic outwards without offspring,"
4140 " would cause containment discontinuity.")))
4142 (let* ((relative-depth (or relative-depth 0))
4143 (new-depth (allout-depth))
4144 (starting-depth (or starting-depth new-depth))
4145 (on-starting-call (null starting-point))
4147 ;; Leave index null on starting call, so rebullet-heading
4148 ;; calculates it at what might be new depth:
4149 (and (or (zerop relative-depth)
4150 (not on-starting-call))
4151 (allout-sibling-index))))
4152 (starting-index index)
4153 (moving-outwards (< 0 relative-depth))
4154 (starting-point (or starting-point (point)))
4155 (local-point (point)))
4157 ;; Sanity check for excessive promotion done only on starting call:
4158 (and on-starting-call
4160 (> 0 (+ starting-depth relative-depth))
4161 (error "Attempt to shift topic out beyond level 1"))
4163 (cond ((= starting-depth new-depth)
4164 ;; We're at depth to work on this one.
4166 ;; When shifting out we work on the children before working on
4167 ;; the parent to avoid interim `allout-aberrant-container-p'
4168 ;; aberrancy, and vice-versa when shifting in:
4169 (if (>= relative-depth 0)
4170 (allout-rebullet-heading nil
4171 (+ starting-depth relative-depth)
4174 nil)) ;;; do-successors
4175 (when (not sans-offspring)
4176 ;; ... and work on subsequent ones which are at greater depth:
4178 (allout-next-heading)
4179 (while (and (not (eobp))
4180 (< starting-depth (allout-depth)))
4181 (setq index (1+ index))
4182 (allout-rebullet-topic-grunt relative-depth
4186 (when (< relative-depth 0)
4188 (goto-char local-point)
4189 (allout-rebullet-heading nil ;;; solicit
4190 (+ starting-depth relative-depth)
4193 nil)))) ;;; do-successors
4195 ((< starting-depth new-depth)
4196 ;; Rare case -- subtopic more than one level deeper than parent.
4197 ;; Treat this one at an even deeper level:
4198 (allout-rebullet-topic-grunt relative-depth
4204 (if on-starting-call
4206 ;; Rectify numbering of former siblings of the adjusted topic,
4207 ;; if topic has changed depth
4208 (if (or do-successors
4209 (and (not (zerop relative-depth))
4210 (or (= allout-recent-depth starting-depth)
4211 (= allout-recent-depth (+ starting-depth
4213 (allout-rebullet-heading nil nil nil nil t))
4214 ;; Now rectify numbering of new siblings of the adjusted topic,
4215 ;; if depth has been changed:
4216 (progn (goto-char starting-point)
4217 (if (not (zerop relative-depth))
4218 (allout-rebullet-heading nil nil nil nil t)))))
4221 ;;;_ > allout-renumber-to-depth (&optional depth)
4222 (defun allout-renumber-to-depth (&optional depth)
4223 "Renumber siblings at current depth.
4225 Affects superior topics if optional arg DEPTH is less than current depth.
4227 Returns final depth."
4229 ;; Proceed by level, processing subsequent siblings on each,
4230 ;; ascending until we get shallower than the start depth:
4232 (let ((ascender (allout-depth))
4234 (while (and (not (eobp))
4236 (>= allout-recent-depth depth)
4237 (>= ascender depth))
4238 ; Skip over all topics at
4239 ; lesser depths, which can not
4240 ; have been disturbed:
4241 (while (and (not (setq was-eobp (eobp)))
4242 (> allout-recent-depth ascender))
4243 (allout-next-heading))
4244 ; Prime ascender for ascension:
4245 (setq ascender (1- allout-recent-depth))
4246 (if (>= allout-recent-depth depth)
4247 (allout-rebullet-heading nil ;;; solicit
4249 nil ;;; number-control
4251 t)) ;;; do-successors
4252 (if was-eobp (goto-char (point-max)))))
4253 allout-recent-depth)
4254 ;;;_ > allout-number-siblings (&optional denumber)
4255 (defun allout-number-siblings (&optional denumber)
4256 "Assign numbered topic prefix to this topic and its siblings.
4258 With universal argument, denumber -- assign default bullet to this
4259 topic and its siblings.
4261 With repeated universal argument (`^U^U'), solicit bullet for each
4262 rebulleting each topic at this level."
4267 (allout-back-to-current-heading)
4268 (allout-beginning-of-level)
4269 (let ((depth allout-recent-depth)
4270 (index (if (not denumber) 1))
4271 (use-bullet (equal '(16) denumber))
4274 (allout-rebullet-heading use-bullet ;;; solicit
4276 t ;;; number-control
4278 nil) ;;; do-successors
4279 (if index (setq index (1+ index)))
4280 (setq more (allout-next-sibling depth nil))))))
4281 ;;;_ > allout-shift-in (arg)
4282 (defun allout-shift-in (arg)
4283 "Increase depth of current heading and any items collapsed within it.
4285 With a negative argument, the item is shifted out using
4286 `allout-shift-out', instead.
4288 With an argument greater than one, shift-in the item but not its
4289 offspring, making the item into a sibling of its former children,
4290 and a child of sibling that formerly preceeded it.
4292 You are not allowed to shift the first offspring of a topic
4293 inwards, because that would yield a \"containment
4294 discontinuity\", where the depth difference between a topic and
4295 its immediate offspring is greater than one. The first topic in
4296 the file can be adjusted to any positive depth, however."
4300 (allout-shift-out (* arg -1))
4301 ;; refuse to create a containment discontinuity:
4303 (allout-back-to-current-heading)
4305 (let* ((current-depth allout-recent-depth)
4306 (start-point (point))
4307 (predecessor-depth (progn
4309 (allout-goto-prefix-doublechecked)
4310 (if (< (point) start-point)
4313 (if (and (> predecessor-depth 0)
4314 (> (1+ current-depth)
4315 (1+ predecessor-depth)))
4316 (error (concat "Disallowed shift deeper than"
4317 " containing topic's children."))
4318 (allout-back-to-current-heading)
4319 (if (< allout-recent-depth (1+ current-depth))
4320 (allout-show-children))))))
4321 (let ((where (point)))
4322 (allout-rebullet-topic 1 (and (> arg 1) 'sans-offspring))
4323 (run-hook-with-args 'allout-structure-shifted-hook arg where))))
4324 ;;;_ > allout-shift-out (arg)
4325 (defun allout-shift-out (arg)
4326 "Decrease depth of current heading and any topics collapsed within it.
4327 This will make the item a sibling of its former container.
4329 With a negative argument, the item is shifted in using
4330 `allout-shift-in', instead.
4332 With an argument greater than one, shift-out the item's offspring
4333 but not the item itself, making the former children siblings of
4336 With an argument greater than 1, the item's offspring are shifted
4337 out without shifting the item. This will make the immediate
4338 subtopics into siblings of the item."
4341 (allout-shift-in (* arg -1))
4342 ;; Get proper exposure in this area:
4343 (save-excursion (if (allout-ascend)
4344 (allout-show-children)))
4345 ;; Show collapsed children if there's a successor which will become
4347 (if (and (allout-current-topic-collapsed-p)
4348 (save-excursion (allout-next-sibling)))
4349 (allout-show-children))
4350 (let ((where (and (allout-depth) allout-recent-prefix-beginning)))
4353 ;; Shift the offspring but not the topic:
4354 (let ((children-chart (allout-chart-subtree 1)))
4355 (if (listp (car children-chart))
4357 (setq children-chart (allout-flatten children-chart)))
4359 (dolist (child-point children-chart)
4360 (goto-char child-point)
4361 (allout-shift-out 1))))
4362 (allout-rebullet-topic (* arg -1))))
4363 (run-hook-with-args 'allout-structure-shifted-hook (* arg -1) where))))
4364 ;;;_ : Surgery (kill-ring) functions with special provisions for outlines:
4365 ;;;_ > allout-kill-line (&optional arg)
4366 (defun allout-kill-line (&optional arg)
4367 "Kill line, adjusting subsequent lines suitably for outline mode."
4371 (if (or (not (allout-mode-p))
4373 (not (save-match-data (looking-at allout-regexp))))
4374 ;; Just do a regular kill:
4376 ;; Ah, have to watch out for adjustments:
4377 (let* ((beg (point))
4379 (beg-hidden (allout-hidden-p))
4380 (end-hidden (save-excursion (allout-end-of-current-line)
4383 (depth (allout-depth)))
4385 (allout-annotate-hidden beg end)
4386 (if (and (not beg-hidden) (not end-hidden))
4387 (allout-unprotected (kill-line arg))
4389 (allout-deannotate-hidden beg end)
4391 (if allout-numbered-bullet
4392 (save-excursion ; Renumber subsequent topics if needed:
4393 (if (not (save-match-data (looking-at allout-regexp)))
4394 (allout-next-heading))
4395 (allout-renumber-to-depth depth)))
4396 (run-hook-with-args 'allout-structure-deleted-hook depth (point)))))
4397 ;;;_ > allout-copy-line-as-kill ()
4398 (defun allout-copy-line-as-kill ()
4399 "Like allout-kill-topic, but save to kill ring instead of deleting."
4401 (let ((buffer-read-only t))
4404 (buffer-read-only nil))))
4405 ;;;_ > allout-kill-topic ()
4406 (defun allout-kill-topic ()
4407 "Kill topic together with subtopics.
4409 Trailing whitespace is killed with a topic if that whitespace:
4411 - would separate the topic from a subsequent sibling
4412 - would separate the topic from the end of buffer
4413 - would not be added to whitespace already separating the topic from the
4416 Topic exposure is marked with text-properties, to be used by
4417 `allout-yank-processing' for exposure recovery."
4420 (let* ((inhibit-field-text-motion t)
4421 (beg (prog1 (allout-back-to-current-heading) (beginning-of-line)))
4423 (depth allout-recent-depth))
4424 (allout-end-of-current-subtree)
4425 (if (and (/= (current-column) 0) (not (eobp)))
4428 (if (and (save-match-data (looking-at "\n"))
4430 (or (not (allout-next-heading))
4431 (= depth allout-recent-depth)))
4432 (and (> (- beg (point-min)) 3)
4433 (string= (buffer-substring (- beg 2) beg) "\n\n"))))
4436 (allout-annotate-hidden beg (setq end (point)))
4438 (allout-unprotected (kill-region beg end))
4439 (if buffer-read-only
4440 ;; eg, during copy-as-kill.
4441 (allout-deannotate-hidden beg end)))
4444 (allout-renumber-to-depth depth))
4445 (run-hook-with-args 'allout-structure-deleted-hook depth (point))))
4446 ;;;_ > allout-copy-topic-as-kill ()
4447 (defun allout-copy-topic-as-kill ()
4448 "Like `allout-kill-topic', but save to kill ring instead of deleting."
4450 (let ((buffer-read-only t))
4453 (buffer-read-only (message "Topic copied...")))))
4454 ;;;_ > allout-annotate-hidden (begin end)
4455 (defun allout-annotate-hidden (begin end)
4456 "Qualify text with properties to indicate exposure status."
4458 (let ((was-modified (buffer-modified-p))
4459 (buffer-read-only nil))
4460 (allout-deannotate-hidden begin end)
4463 (let (done next prev overlay)
4465 ;; at or advance to start of next hidden region:
4466 (if (not (allout-hidden-p))
4469 (allout-next-single-char-property-change (point)
4472 (if (or (not next) (eq prev next))
4473 ;; still not at start of hidden area -- must not be any left.
4477 (if (not (allout-hidden-p))
4478 ;; still not at start of hidden area.
4480 (setq overlay (allout-get-invisibility-overlay))
4481 (setq next (overlay-end overlay)
4483 ;; advance to end of this hidden area:
4487 (let ((buffer-undo-list t))
4488 (put-text-property (overlay-start overlay) next
4489 'allout-was-hidden t)))))))))
4490 (set-buffer-modified-p was-modified)))
4491 ;;;_ > allout-deannotate-hidden (begin end)
4492 (defun allout-deannotate-hidden (begin end)
4493 "Remove allout hidden-text annotation between BEGIN and END."
4496 (let ((inhibit-read-only t)
4497 (buffer-undo-list t))
4498 ;(remove-text-properties begin end '(allout-was-hidden t))
4500 ;;;_ > allout-hide-by-annotation (begin end)
4501 (defun allout-hide-by-annotation (begin end)
4502 "Translate text properties indicating exposure status into actual exposure."
4505 (let ((was-modified (buffer-modified-p))
4508 ;; at or advance to start of next annotation:
4509 (if (not (get-text-property (point) 'allout-was-hidden))
4510 (setq next (allout-next-single-char-property-change
4511 (point) 'allout-was-hidden nil end)))
4512 (if (or (not next) (eq prev next))
4513 ;; no more or not advancing -- must not be any left.
4517 (if (not (get-text-property (point) 'allout-was-hidden))
4518 ;; still not at start of annotation.
4520 ;; advance to just after end of this annotation:
4521 (setq next (allout-next-single-char-property-change
4522 (point) 'allout-was-hidden nil end))
4523 (overlay-put (make-overlay prev next nil 'front-advance)
4524 'category 'allout-exposure-category)
4525 (allout-deannotate-hidden prev next)
4527 (if next (goto-char next)))))
4528 (set-buffer-modified-p was-modified))))
4529 ;;;_ > allout-yank-processing ()
4530 (defun allout-yank-processing (&optional arg)
4532 "Incidental allout-specific business to be done just after text yanks.
4534 Does depth adjustment of yanked topics, when:
4536 1 the stuff being yanked starts with a valid outline header prefix, and
4537 2 it is being yanked at the end of a line which consists of only a valid
4540 Also, adjusts numbering of subsequent siblings when appropriate.
4542 Depth adjustment alters the depth of all the topics being yanked
4543 the amount it takes to make the first topic have the depth of the
4544 header into which it's being yanked.
4546 The point is left in front of yanked, adjusted topics, rather than
4547 at the end (and vice-versa with the mark). Non-adjusted yanks,
4548 however, are left exactly like normal, non-allout-specific yanks."
4551 ; Get to beginning, leaving
4552 ; region around subject:
4553 (if (< (allout-mark-marker t) (point))
4554 (exchange-point-and-mark))
4556 (let* ((subj-beg (point))
4558 (subj-end (allout-mark-marker t))
4559 ;; 'resituate' if yanking an entire topic into topic header:
4560 (resituate (and (let ((allout-inhibit-aberrance-doublecheck t))
4561 (allout-e-o-prefix-p))
4562 (looking-at allout-regexp)
4563 (allout-prefix-data)))
4564 ;; `rectify-numbering' if resituating (where several topics may
4565 ;; be resituating) or yanking a topic into a topic slot (bol):
4566 (rectify-numbering (or resituate
4567 (and into-bol (looking-at allout-regexp)))))
4569 ;; Yanking a topic into the start of a topic -- reconcile to fit:
4570 (let* ((inhibit-field-text-motion t)
4571 (prefix-len (if (not (match-end 1))
4573 (- (match-end 1) subj-beg)))
4574 (subj-depth allout-recent-depth)
4575 (prefix-bullet (allout-recent-bullet))
4577 ;; Nil if adjustment unnecessary, otherwise depth to which
4578 ;; adjustment should be made:
4580 (and (goto-char subj-end)
4582 (goto-char subj-beg)
4583 (and (looking-at allout-regexp)
4586 (not (= (point) subj-beg)))
4587 (looking-at allout-regexp)
4588 (allout-prefix-data))
4589 allout-recent-depth)))
4591 (setq rectify-numbering allout-numbered-bullet)
4593 ; Do the adjustment:
4596 (narrow-to-region subj-beg subj-end)
4597 ; Trim off excessive blank
4598 ; line at end, if any:
4599 (goto-char (point-max))
4600 (if (looking-at "^$")
4601 (allout-unprotected (delete-char -1)))
4602 ; Work backwards, with each
4604 ; successively excluding the
4605 ; last processed topic from
4606 ; the narrow region:
4608 (allout-back-to-current-heading)
4609 ; go as high as we can in each bunch:
4610 (while (allout-ascend t))
4613 (allout-rebullet-topic-grunt (- adjust-to-depth
4616 (if (setq more (not (bobp)))
4619 (narrow-to-region subj-beg (point))))))
4620 ;; Preserve new bullet if it's a distinctive one, otherwise
4622 (if (string-match (regexp-quote prefix-bullet)
4623 allout-distinctive-bullets-string)
4624 ; Delete from bullet of old to
4625 ; before bullet of new:
4629 (delete-region (point) subj-beg))
4630 (set-marker (allout-mark-marker t) subj-end)
4631 (goto-char subj-beg)
4632 (allout-end-of-prefix))
4633 ; Delete base subj prefix,
4637 (delete-region (point) (+ (point)
4641 ; and delete residual subj
4642 ; prefix digits and space:
4643 (while (looking-at "[0-9]") (delete-char 1))
4644 (if (looking-at " ")
4645 (delete-char 1))))))
4646 (exchange-point-and-mark))))
4647 (if rectify-numbering
4650 ; Give some preliminary feedback:
4651 (message "... reconciling numbers")
4652 ; ... and renumber, in case necessary:
4653 (goto-char subj-beg)
4654 (if (allout-goto-prefix-doublechecked)
4656 (allout-rebullet-heading nil ;;; solicit
4657 (allout-depth) ;;; depth
4658 nil ;;; number-control
4662 (if (or into-bol resituate)
4663 (allout-hide-by-annotation (point) (allout-mark-marker t))
4664 (allout-deannotate-hidden (allout-mark-marker t) (point)))
4666 (exchange-point-and-mark))
4667 (run-hook-with-args 'allout-structure-added-hook subj-beg subj-end))))
4668 ;;;_ > allout-yank (&optional arg)
4669 (defun allout-yank (&optional arg)
4670 "`allout-mode' yank, with depth and numbering adjustment of yanked topics.
4672 Non-topic yanks work no differently than normal yanks.
4674 If a topic is being yanked into a bare topic prefix, the depth of the
4675 yanked topic is adjusted to the depth of the topic prefix.
4677 1 we're yanking in an `allout-mode' buffer
4678 2 the stuff being yanked starts with a valid outline header prefix, and
4679 3 it is being yanked at the end of a line which consists of only a valid
4682 If these conditions hold then the depth of the yanked topics are all
4683 adjusted the amount it takes to make the first one at the depth of the
4684 header into which it's being yanked.
4686 The point is left in front of yanked, adjusted topics, rather than
4687 at the end (and vice-versa with the mark). Non-adjusted yanks,
4688 however, (ones that don't qualify for adjustment) are handled
4689 exactly like normal yanks.
4691 Numbering of yanked topics, and the successive siblings at the depth
4692 into which they're being yanked, is adjusted.
4694 `allout-yank-pop' works with `allout-yank' just like normal `yank-pop'
4695 works with normal `yank' in non-outline buffers."
4698 (setq this-command 'yank)
4702 (allout-yank-processing)))
4703 ;;;_ > allout-yank-pop (&optional arg)
4704 (defun allout-yank-pop (&optional arg)
4705 "Yank-pop like `allout-yank' when popping to bare outline prefixes.
4707 Adapts level of popped topics to level of fresh prefix.
4709 Note -- prefix changes to distinctive bullets will stick, if followed
4710 by pops to non-distinctive yanks. Bug..."
4713 (setq this-command 'yank)
4716 (allout-yank-processing)))
4718 ;;;_ - Specialty bullet functions
4719 ;;;_ : File Cross references
4720 ;;;_ > allout-resolve-xref ()
4721 (defun allout-resolve-xref ()
4722 "Pop to file associated with current heading, if it has an xref bullet.
4724 \(Works according to setting of `allout-file-xref-bullet')."
4726 (if (not allout-file-xref-bullet)
4728 "Outline cross references disabled -- no `allout-file-xref-bullet'")
4729 (if (not (string= (allout-current-bullet) allout-file-xref-bullet))
4730 (error "Current heading lacks cross-reference bullet `%s'"
4731 allout-file-xref-bullet)
4732 (let ((inhibit-field-text-motion t)
4736 (let* ((text-start allout-recent-prefix-end)
4737 (heading-end (point-at-eol)))
4738 (goto-char text-start)
4740 (if (re-search-forward "\\s-\\(\\S-*\\)" heading-end t)
4741 (buffer-substring (match-beginning 1)
4743 (setq file-name (expand-file-name file-name))
4744 (if (or (file-exists-p file-name)
4745 (if (file-writable-p file-name)
4746 (y-or-n-p (format "%s not there, create one? "
4748 (error "%s not found and can't be created" file-name)))
4749 (condition-case failure
4750 (find-file-other-window file-name)
4752 (error "%s not found" file-name))
4758 ;;;_ #6 Exposure Control
4761 ;;;_ > allout-flag-region (from to flag)
4762 (defun allout-flag-region (from to flag)
4763 "Conceal text between FROM and TO if FLAG is non-nil, else reveal it.
4765 Exposure-change hook `allout-exposure-change-hook' is run with the same
4766 arguments as this function, after the exposure changes are made."
4768 ;; We use outline invisibility spec.
4769 (remove-overlays from to 'category 'allout-exposure-category)
4771 (let ((o (make-overlay from to nil 'front-advance)))
4772 (overlay-put o 'category 'allout-exposure-category)
4773 (when (featurep 'xemacs)
4774 (let ((props (symbol-plist 'allout-exposure-category)))
4777 ;; as of 2008-02-27, xemacs lacks modification-hooks
4778 (overlay-put o (pop props) (pop props))
4780 (run-hook-with-args 'allout-exposure-change-hook from to flag))
4781 ;;;_ > allout-flag-current-subtree (flag)
4782 (defun allout-flag-current-subtree (flag)
4783 "Conceal currently-visible topic's subtree if FLAG non-nil, else reveal it."
4786 (allout-back-to-current-heading)
4787 (let ((inhibit-field-text-motion t))
4789 (allout-flag-region (point)
4790 ;; Exposing must not leave trailing blanks hidden,
4791 ;; but can leave them exposed when hiding, so we
4792 ;; can use flag's inverse as the
4793 ;; include-trailing-blank cue:
4794 (allout-end-of-current-subtree (not flag))
4797 ;;;_ - Topic-specific
4798 ;;;_ > allout-show-entry ()
4799 (defun allout-show-entry ()
4800 "Like `allout-show-current-entry', but reveals entries in hidden topics.
4802 This is a way to give restricted peek at a concealed locality without the
4803 expense of exposing its context, but can leave the outline with aberrant
4804 exposure. `allout-show-offshoot' should be used after the peek to rectify
4810 (allout-goto-prefix-doublechecked)
4811 (setq beg (if (allout-hidden-p) (1- (point)) (point)))
4812 (setq end (allout-pre-next-prefix))
4813 (allout-flag-region beg end nil)
4815 ;;;_ > allout-show-children (&optional level strict)
4816 (defun allout-show-children (&optional level strict)
4818 "If point is visible, show all direct subheadings of this heading.
4820 Otherwise, do `allout-show-to-offshoot', and then show subheadings.
4822 Optional LEVEL specifies how many levels below the current level
4823 should be shown, or all levels if t. Default is 1.
4825 Optional STRICT means don't resort to -show-to-offshoot, no matter
4826 what. This is basically so -show-to-offshoot, which is called by
4827 this function, can employ the pure offspring-revealing capabilities of
4830 Returns point at end of subtree that was opened, if any. (May get a
4831 point of non-opened subtree?)"
4834 (let ((start-point (point)))
4835 (if (and (not strict)
4838 (progn (allout-show-to-offshoot) ; Point's concealed, open to
4840 ;; Then recurse, but with "strict" set so we don't
4841 ;; infinite regress:
4842 (allout-show-children level t))
4845 (allout-beginning-of-current-line)
4848 ;; translate the level spec for this routine to the ones
4849 ;; used by -chart-subtree and -chart-to-reveal:
4850 (chart-level (cond ((not level) 1)
4853 (chart (allout-chart-subtree chart-level))
4854 (to-reveal (or (allout-chart-to-reveal chart chart-level)
4855 ;; interactive, show discontinuous children:
4857 (allout-called-interactively-p)
4859 (allout-back-to-current-heading)
4860 (setq depth (allout-current-depth))
4861 (and (allout-next-heading)
4862 (> allout-recent-depth
4865 "Discontinuous offspring; use `%s %s'%s."
4866 (substitute-command-keys
4867 "\\[universal-argument]")
4868 (substitute-command-keys
4869 "\\[allout-shift-out]")
4870 " to elevate them.")
4871 (allout-chart-to-reveal
4872 chart (- allout-recent-depth depth))))))
4873 (goto-char start-point)
4874 (when (and strict (allout-hidden-p))
4875 ;; Concealed root would already have been taken care of,
4876 ;; unless strict was set.
4877 (allout-flag-region (point) (allout-snug-back) nil)
4878 (when allout-show-bodies
4879 (goto-char (car to-reveal))
4880 (allout-show-current-entry)))
4882 (goto-char (car to-reveal))
4883 (allout-flag-region (save-excursion (allout-snug-back) (point))
4884 (progn (search-forward "\n" nil t)
4887 (when allout-show-bodies
4888 (goto-char (car to-reveal))
4889 (allout-show-current-entry))
4890 (setq to-reveal (cdr to-reveal)))))))
4891 ;; Compensate for `save-excursion's maintenance of point
4892 ;; within invisible text:
4893 (goto-char start-point)))
4894 ;;;_ > allout-show-to-offshoot ()
4895 (defun allout-show-to-offshoot ()
4896 "Like `allout-show-entry', but reveals all concealed ancestors, as well.
4898 Useful for coherently exposing to a random point in a hidden region."
4901 (let ((inhibit-field-text-motion t)
4903 (orig-pref (allout-goto-prefix-doublechecked))
4906 (while (or (> bag-it 1) (allout-hidden-p))
4907 (while (allout-hidden-p)
4908 (move-beginning-of-line 1)
4909 (if (allout-hidden-p) (forward-char -1)))
4910 (if (= last-at (setq last-at (point)))
4911 ;; Oops, we're not making any progress! Show the current topic
4912 ;; completely, and try one more time here, if we haven't already.
4913 (progn (beginning-of-line)
4914 (allout-show-current-subtree)
4916 (setq bag-it (1+ bag-it))
4918 (error "allout-show-to-offshoot: %s"
4919 "Stumped by aberrant nesting.")))
4920 (if (> bag-it 0) (setq bag-it 0))
4921 (allout-show-children)
4922 (goto-char orig-pref)))
4923 (goto-char orig-pt)))
4924 (if (allout-hidden-p)
4925 (allout-show-entry)))
4926 ;;;_ > allout-hide-current-entry ()
4927 (defun allout-hide-current-entry ()
4928 "Hide the body directly following this heading."
4930 (allout-back-to-current-heading)
4932 (let ((inhibit-field-text-motion t))
4934 (allout-flag-region (point)
4935 (progn (allout-end-of-entry) (point))
4937 ;;;_ > allout-show-current-entry (&optional arg)
4938 (defun allout-show-current-entry (&optional arg)
4939 "Show body following current heading, or hide entry with universal argument."
4943 (allout-hide-current-entry)
4944 (save-excursion (allout-show-to-offshoot))
4946 (allout-flag-region (point)
4947 (progn (allout-end-of-entry t) (point))
4950 ;;;_ > allout-show-current-subtree (&optional arg)
4951 (defun allout-show-current-subtree (&optional arg)
4952 "Show everything within the current topic.
4953 With a repeat-count, expose this topic and its siblings."
4956 (if (<= (allout-current-depth) 0)
4957 ;; Outside any topics -- try to get to the first:
4958 (if (not (allout-next-heading))
4960 ;; got to first, outermost topic -- set to expose it and siblings:
4961 (message "Above outermost topic -- exposing all.")
4962 (allout-flag-region (point-min)(point-max) nil))
4963 (allout-beginning-of-current-line)
4965 (allout-flag-current-subtree nil)
4966 (allout-beginning-of-level)
4967 (allout-expose-topic '(* :))))))
4968 ;;;_ > allout-current-topic-collapsed-p (&optional include-single-liners)
4969 (defun allout-current-topic-collapsed-p (&optional include-single-liners)
4970 "True if the currently visible containing topic is already collapsed.
4972 Single line topics intrinsically can be considered as being both
4973 collapsed and uncollapsed. If optional INCLUDE-SINGLE-LINERS is
4974 true, then single-line topics are considered to be collapsed. By
4975 default, they are treated as being uncollapsed."
4979 ;; Is the topic all on one line (allowing for trailing blank line)?
4980 (>= (progn (allout-back-to-current-heading)
4981 (let ((inhibit-field-text-motion t))
4982 (move-end-of-line 1))
4984 (allout-end-of-current-subtree (not (looking-at "\n\n"))))
4986 (or include-single-liners
4987 (progn (backward-char 1) (allout-hidden-p)))))))
4988 ;;;_ > allout-hide-current-subtree (&optional just-close)
4989 (defun allout-hide-current-subtree (&optional just-close)
4990 "Close the current topic, or containing topic if this one is already closed.
4992 If this topic is closed and it's a top level topic, close this topic
4995 If optional arg JUST-CLOSE is non-nil, do not close the parent or
4996 siblings, even if the target topic is already closed."
4999 (let* ((from (point))
5000 (sibs-msg "Top-level topic already closed -- closing siblings...")
5001 (current-exposed (not (allout-current-topic-collapsed-p t))))
5002 (cond (current-exposed (allout-flag-current-subtree t))
5004 ((allout-ascend) (allout-hide-current-subtree))
5007 (allout-goto-prefix-doublechecked)
5008 (allout-expose-topic '(0 :))
5009 (message (concat sibs-msg " Done."))))
5011 ;;;_ > allout-toggle-current-subtree-exposure
5012 (defun allout-toggle-current-subtree-exposure ()
5013 "Show or hide the current subtree depending on its current state."
5014 ;; thanks to tassilo for suggesting this.
5017 (allout-back-to-heading)
5018 (if (allout-hidden-p (point-at-eol))
5019 (allout-show-current-subtree)
5020 (allout-hide-current-subtree))))
5021 ;;;_ > allout-show-current-branches ()
5022 (defun allout-show-current-branches ()
5023 "Show all subheadings of this heading, but not their bodies."
5025 (let ((inhibit-field-text-motion t))
5026 (beginning-of-line))
5027 (allout-show-children t))
5028 ;;;_ > allout-hide-current-leaves ()
5029 (defun allout-hide-current-leaves ()
5030 "Hide the bodies of the current topic and all its offspring."
5032 (allout-back-to-current-heading)
5033 (allout-hide-region-body (point) (progn (allout-end-of-current-subtree)
5036 ;;;_ - Region and beyond
5037 ;;;_ > allout-show-all ()
5038 (defun allout-show-all ()
5039 "Show all of the text in the buffer."
5041 (message "Exposing entire buffer...")
5042 (allout-flag-region (point-min) (point-max) nil)
5043 (message "Exposing entire buffer... Done."))
5044 ;;;_ > allout-hide-bodies ()
5045 (defun allout-hide-bodies ()
5046 "Hide all of buffer except headings."
5048 (allout-hide-region-body (point-min) (point-max)))
5049 ;;;_ > allout-hide-region-body (start end)
5050 (defun allout-hide-region-body (start end)
5051 "Hide all body lines in the region, but not headings."
5055 (narrow-to-region start end)
5056 (goto-char (point-min))
5057 (let ((inhibit-field-text-motion t))
5060 (allout-flag-region (point) (allout-end-of-entry) t)
5063 (if (looking-at "\n\n")
5066 ;;;_ > allout-expose-topic (spec)
5067 (defun allout-expose-topic (spec)
5068 "Apply exposure specs to successive outline topic items.
5070 Use the more convenient frontend, `allout-new-exposure', if you don't
5071 need evaluation of the arguments, or even better, the `allout-layout'
5072 variable-keyed mode-activation/auto-exposure feature of allout outline
5073 mode. See the respective documentation strings for more details.
5075 Cursor is left at start position.
5077 SPEC is either a number or a list.
5079 Successive specs on a list are applied to successive sibling topics.
5081 A simple spec (either a number, one of a few symbols, or the null
5082 list) dictates the exposure for the corresponding topic.
5084 Non-null lists recursively designate exposure specs for respective
5085 subtopics of the current topic.
5087 The `:' repeat spec is used to specify exposure for any number of
5088 successive siblings, up to the trailing ones for which there are
5089 explicit specs following the `:'.
5091 Simple (numeric and null-list) specs are interpreted as follows:
5093 Numbers indicate the relative depth to open the corresponding topic.
5094 - negative numbers force the topic to be closed before opening to the
5095 absolute value of the number, so all siblings are open only to
5097 - positive numbers open to the relative depth indicated by the
5098 number, but do not force already opened subtopics to be closed.
5099 - 0 means to close topic -- hide all offspring.
5101 apply prior element to all siblings at current level, *up to*
5102 those siblings that would be covered by specs following the `:'
5103 on the list. Ie, apply to all topics at level but the last
5104 ones. (Only first of multiple colons at same level is
5105 respected -- subsequent ones are discarded.)
5106 * - completely opens the topic, including bodies.
5107 + - shows all the sub headers, but not the bodies
5108 - - exposes the body of the corresponding topic.
5111 \(allout-expose-topic '(-1 : 0))
5112 Close this and all following topics at current level, exposing
5113 only their immediate children, but close down the last topic
5114 at this current level completely.
5115 \(allout-expose-topic '(-1 () : 1 0))
5116 Close current topic so only the immediate subtopics are shown;
5117 show the children in the second to last topic, and completely
5119 \(allout-expose-topic '(-2 : -1 *))
5120 Expose children and grandchildren of all topics at current
5121 level except the last two; expose children of the second to
5122 last and completely open the last one."
5124 (interactive "xExposure spec: ")
5125 (if (not (listp spec))
5127 (let ((depth (allout-depth))
5132 (setq prev-elem curr-elem
5133 curr-elem (car spec)
5135 (cond ; Do current element:
5136 ((null curr-elem) nil)
5137 ((symbolp curr-elem)
5138 (cond ((eq curr-elem '*) (allout-show-current-subtree)
5139 (if (> allout-recent-end-of-subtree max-pos)
5140 (setq max-pos allout-recent-end-of-subtree)))
5142 (if (not (allout-hidden-p))
5143 (save-excursion (allout-hide-current-subtree t)))
5144 (allout-show-current-branches)
5145 (if (> allout-recent-end-of-subtree max-pos)
5146 (setq max-pos allout-recent-end-of-subtree)))
5147 ((eq curr-elem '-) (allout-show-current-entry))
5150 ;; Expand the `repeat' spec to an explicit version,
5151 ;; w.r.t. remaining siblings:
5152 (let ((residue ; = # of sibs not covered by remaining spec
5153 ;; Dang, could be nice to make use of the chart, sigh:
5154 (- (length (allout-chart-siblings))
5157 ;; Some residue -- cover it with prev-elem:
5158 (setq spec (append (make-list residue prev-elem)
5160 ((numberp curr-elem)
5161 (if (and (>= 0 curr-elem) (not (allout-hidden-p)))
5162 (save-excursion (allout-hide-current-subtree t)
5165 (if (> allout-recent-end-of-subtree max-pos)
5167 allout-recent-end-of-subtree)))))
5168 (if (> (abs curr-elem) 0)
5169 (progn (allout-show-children (abs curr-elem))
5170 (if (> allout-recent-end-of-subtree max-pos)
5171 (setq max-pos allout-recent-end-of-subtree)))))
5173 (if (allout-descend-to-depth (1+ depth))
5174 (let ((got (allout-expose-topic curr-elem)))
5175 (if (and got (> got max-pos)) (setq max-pos got))))))
5176 (cond (stay (setq stay nil))
5177 ((listp (car spec)) nil)
5178 ((> max-pos (point))
5179 ;; Capitalize on max-pos state to get us nearer next sibling:
5180 (progn (goto-char (min (point-max) max-pos))
5181 (allout-next-heading)))
5182 ((allout-next-sibling depth))))
5184 ;;;_ > allout-old-expose-topic (spec &rest followers)
5185 (defun allout-old-expose-topic (spec &rest followers)
5187 "Deprecated. Use `allout-expose-topic' (with different schema
5190 Dictate wholesale exposure scheme for current topic, according to SPEC.
5192 SPEC is either a number or a list. Optional successive args
5193 dictate exposure for subsequent siblings of current topic.
5195 A simple spec (either a number, a special symbol, or the null list)
5196 dictates the overall exposure for a topic. Non null lists are
5197 composite specs whose first element dictates the overall exposure for
5198 a topic, with the subsequent elements in the list interpreted as specs
5199 that dictate the exposure for the successive offspring of the topic.
5201 Simple (numeric and null-list) specs are interpreted as follows:
5203 - Numbers indicate the relative depth to open the corresponding topic:
5204 - negative numbers force the topic to be close before opening to the
5205 absolute value of the number.
5206 - positive numbers just open to the relative depth indicated by the number.
5208 - `*' completely opens the topic, including bodies.
5209 - `+' shows all the sub headers, but not the bodies
5210 - `-' exposes the body and immediate offspring of the corresponding topic.
5212 If the spec is a list, the first element must be a number, which
5213 dictates the exposure depth of the topic as a whole. Subsequent
5214 elements of the list are nested SPECs, dictating the specific exposure
5215 for the corresponding offspring of the topic.
5217 Optional FOLLOWERS arguments dictate exposure for succeeding siblings."
5219 (interactive "xExposure spec: ")
5220 (let ((inhibit-field-text-motion t)
5221 (depth (allout-current-depth))
5223 (cond ((null spec) nil)
5225 (if (eq spec '*) (allout-show-current-subtree))
5226 (if (eq spec '+) (allout-show-current-branches))
5227 (if (eq spec '-) (allout-show-current-entry)))
5230 (save-excursion (allout-hide-current-subtree t)
5232 (if (or (not max-pos)
5233 (> (point) max-pos))
5234 (setq max-pos (point)))
5236 (setq spec (* -1 spec)))))
5238 (allout-show-children spec)))
5240 ;(let ((got (allout-old-expose-topic (car spec))))
5241 ; (if (and got (or (not max-pos) (> got max-pos)))
5242 ; (setq max-pos got)))
5243 (let ((new-depth (+ (allout-current-depth) 1))
5245 (setq max-pos (allout-old-expose-topic (car spec)))
5246 (setq spec (cdr spec))
5248 (allout-descend-to-depth new-depth)
5249 (not (allout-hidden-p)))
5250 (progn (setq got (apply 'allout-old-expose-topic spec))
5251 (if (and got (or (not max-pos) (> got max-pos)))
5252 (setq max-pos got)))))))
5253 (while (and followers
5254 (progn (if (and max-pos (< (point) max-pos))
5255 (progn (goto-char max-pos)
5256 (setq max-pos nil)))
5258 (allout-next-sibling depth)))
5259 (allout-old-expose-topic (car followers))
5260 (setq followers (cdr followers)))
5262 ;;;_ > allout-new-exposure '()
5263 (defmacro allout-new-exposure (&rest spec)
5264 "Literal frontend for `allout-expose-topic', doesn't evaluate arguments.
5265 Some arguments that would need to be quoted in `allout-expose-topic'
5266 need not be quoted in `allout-new-exposure'.
5268 Cursor is left at start position.
5270 Use this instead of obsolete `allout-exposure'.
5273 \(allout-new-exposure (-1 () () () 1) 0)
5274 Close current topic at current level so only the immediate
5275 subtopics are shown, except also show the children of the
5276 third subtopic; and close the next topic at the current level.
5277 \(allout-new-exposure : -1 0)
5278 Close all topics at current level to expose only their
5279 immediate children, except for the last topic at the current
5280 level, in which even its immediate children are hidden.
5281 \(allout-new-exposure -2 : -1 *)
5282 Expose children and grandchildren of first topic at current
5283 level, and expose children of subsequent topics at current
5284 level *except* for the last, which should be opened completely."
5285 (list 'save-excursion
5286 '(if (not (or (allout-goto-prefix-doublechecked)
5287 (allout-next-heading)))
5288 (error "allout-new-exposure: Can't find any outline topics"))
5289 (list 'allout-expose-topic (list 'quote spec))))
5291 ;;;_ #7 Systematic outline presentation -- copying, printing, flattening
5293 ;;;_ - Mapping and processing of topics
5294 ;;;_ ( See also Subtree Charting, in Navigation code.)
5295 ;;;_ > allout-stringify-flat-index (flat-index)
5296 (defun allout-stringify-flat-index (flat-index &optional context)
5297 "Convert list representing section/subsection/... to document string.
5299 Optional arg CONTEXT indicates interior levels to include."
5303 (context-depth (or (and context 2) 1)))
5304 ;; Take care of the explicit context:
5305 (while (> context-depth 0)
5306 (setq numstr (int-to-string (car flat-index))
5307 flat-index (cdr flat-index)
5308 result (if flat-index
5309 (cons delim (cons numstr result))
5310 (cons numstr result))
5311 context-depth (if flat-index (1- context-depth) 0)))
5313 ;; Take care of the indentation:
5320 (1+ (truncate (if (zerop (car flat-index))
5322 (log10 (car flat-index)))))
5325 (setq flat-index (cdr flat-index)))
5326 ;; Dispose of single extra delim:
5327 (setq result (cdr result))))
5328 (apply 'concat result)))
5329 ;;;_ > allout-stringify-flat-index-plain (flat-index)
5330 (defun allout-stringify-flat-index-plain (flat-index)
5331 "Convert list representing section/subsection/... to document string."
5335 (setq result (cons (int-to-string (car flat-index))
5337 (cons delim result))))
5338 (setq flat-index (cdr flat-index)))
5339 (apply 'concat result)))
5340 ;;;_ > allout-stringify-flat-index-indented (flat-index)
5341 (defun allout-stringify-flat-index-indented (flat-index)
5342 "Convert list representing section/subsection/... to document string."
5346 ;; Take care of the explicit context:
5347 (setq numstr (int-to-string (car flat-index))
5348 flat-index (cdr flat-index)
5349 result (if flat-index
5350 (cons delim (cons numstr result))
5351 (cons numstr result)))
5353 ;; Take care of the indentation:
5360 (1+ (truncate (if (zerop (car flat-index))
5362 (log10 (car flat-index)))))
5365 (setq flat-index (cdr flat-index)))
5366 ;; Dispose of single extra delim:
5367 (setq result (cdr result))))
5368 (apply 'concat result)))
5369 ;;;_ > allout-listify-exposed (&optional start end format)
5370 (defun allout-listify-exposed (&optional start end format)
5372 "Produce a list representing exposed topics in current region.
5374 This list can then be used by `allout-process-exposed' to manipulate
5377 Optional START and END indicate bounds of region.
5379 Optional arg, FORMAT, designates an alternate presentation form for
5382 list -- Present prefix as numeric section.subsection..., starting with
5383 section indicated by the list, innermost nesting first.
5384 `indent' (symbol) -- Convert header prefixes to all white space,
5385 except for distinctive bullets.
5387 The elements of the list produced are lists that represents a topic
5388 header and body. The elements of that list are:
5390 - a number representing the depth of the topic,
5391 - a string representing the header-prefix, including trailing whitespace and
5393 - a string representing the bullet character,
5394 - and a series of strings, each containing one line of the exposed
5395 portion of the topic entry."
5400 ((inhibit-field-text-motion t)
5402 strings prefix result depth new-depth out gone-out bullet beg
5407 ;; Goto initial topic, and register preceeding stuff, if any:
5408 (if (> (allout-goto-prefix-doublechecked) start)
5409 ;; First topic follows beginning point -- register preliminary stuff:
5410 (setq result (list (list 0 "" nil
5411 (buffer-substring start (1- (point)))))))
5412 (while (and (not done)
5413 (not (eobp)) ; Loop until we've covered the region.
5414 (not (> (point) end)))
5415 (setq depth allout-recent-depth ; Current topics depth,
5416 bullet (allout-recent-bullet) ; ... bullet,
5417 prefix (allout-recent-prefix)
5418 beg (progn (allout-end-of-prefix t) (point))) ; and beginning.
5419 (setq done ; The boundary for the current topic:
5420 (not (allout-next-visible-heading 1)))
5421 (setq new-depth allout-recent-depth)
5423 out (< new-depth depth))
5428 (while (> next (point)) ; Get all the exposed text in
5430 (cons (buffer-substring
5432 ;To hidden text or end of line:
5435 (allout-back-to-visible-text)))
5437 (when (< (point) next) ; Resume from after hid text, if any.
5439 (beginning-of-line))
5441 ;; Accumulate list for this topic:
5442 (setq strings (nreverse strings))
5446 (let ((special (if (string-match
5447 (regexp-quote bullet)
5448 allout-distinctive-bullets-string)
5450 (cond ((listp format)
5452 (if allout-abbreviate-flattened-numbering
5453 (allout-stringify-flat-index format
5455 (allout-stringify-flat-index-plain
5459 ((eq format 'indent)
5462 (concat (make-string (1+ depth) ? )
5463 (substring prefix -1))
5466 (make-string depth ? )
5468 (t (error "allout-listify-exposed: %s %s"
5469 "invalid format" format))))
5470 (list depth prefix strings))
5472 ;; Reasses format, if any:
5473 (if (and format (listp format))
5474 (cond ((= new-depth depth)
5475 (setq format (cons (1+ (car format))
5477 ((> new-depth depth) ; descending -- assume by 1:
5478 (setq format (cons 1 format)))
5481 (while (< new-depth depth)
5482 (setq format (cdr format))
5483 (setq depth (1- depth)))
5484 ; And increment the current one:
5486 (cons (1+ (or (car format)
5489 ;; Put the list with first at front, to last at back:
5490 (nreverse result))))
5491 ;;;_ > allout-region-active-p ()
5492 (defmacro allout-region-active-p ()
5493 (cond ((fboundp 'use-region-p) '(use-region-p))
5494 ((fboundp 'region-active-p) '(region-active-p))
5496 ;;_ > allout-process-exposed (&optional func from to frombuf
5498 (defun allout-process-exposed (&optional func from to frombuf tobuf
5500 "Map function on exposed parts of current topic; results to another buffer.
5502 All args are options; default values itemized below.
5504 Apply FUNCTION to exposed portions FROM position TO position in buffer
5505 FROMBUF to buffer TOBUF. Sixth optional arg, FORMAT, designates an
5506 alternate presentation form:
5508 `flat' -- Present prefix as numeric section.subsection..., starting with
5509 section indicated by the START-NUM, innermost nesting first.
5510 X`flat-indented' -- Prefix is like `flat' for first topic at each
5511 X level, but subsequent topics have only leaf topic
5512 X number, padded with blanks to line up with first.
5513 `indent' (symbol) -- Convert header prefixes to all white space,
5514 except for distinctive bullets.
5517 FUNCTION: `allout-insert-listified'
5518 FROM: region start, if region active, else start of buffer
5519 TO: region end, if region active, else end of buffer
5520 FROMBUF: current buffer
5521 TOBUF: buffer name derived: \"*current-buffer-name exposed*\"
5524 ; Resolve arguments,
5525 ; defaulting if necessary:
5526 (if (not func) (setq func 'allout-insert-listified))
5527 (if (not (and from to))
5528 (if (allout-region-active-p)
5529 (setq from (region-beginning) to (region-end))
5530 (setq from (point-min) to (point-max))))
5532 (if (not (bufferp frombuf))
5533 ;; Specified but not a buffer -- get it:
5534 (let ((got (get-buffer frombuf)))
5536 (error (concat "allout-process-exposed: source buffer "
5539 (setq frombuf got))))
5540 ;; not specified -- default it:
5541 (setq frombuf (current-buffer)))
5543 (if (not (bufferp tobuf))
5544 (setq tobuf (get-buffer-create tobuf)))
5545 ;; not specified -- default it:
5546 (setq tobuf (concat "*" (buffer-name frombuf) " exposed*")))
5551 (progn (set-buffer frombuf)
5552 (allout-listify-exposed from to format))))
5554 (mapc func listified)
5555 (pop-to-buffer tobuf)))
5558 ;;;_ > allout-insert-listified (listified)
5559 (defun allout-insert-listified (listified)
5560 "Insert contents of listified outline portion in current buffer.
5562 LISTIFIED is a list representing each topic header and body:
5564 \`(depth prefix text)'
5566 or \`(depth prefix text bullet-plus)'
5568 If `bullet-plus' is specified, it is inserted just after the entire prefix."
5569 (setq listified (cdr listified))
5570 (let ((prefix (prog1
5572 (setq listified (cdr listified))))
5575 (setq listified (cdr listified))))
5576 (bullet-plus (car listified)))
5578 (if bullet-plus (insert (concat " " bullet-plus)))
5581 (if (setq text (cdr text))
5584 ;;;_ > allout-copy-exposed-to-buffer (&optional arg tobuf format)
5585 (defun allout-copy-exposed-to-buffer (&optional arg tobuf format)
5586 "Duplicate exposed portions of current outline to another buffer.
5588 Other buffer has current buffers name with \" exposed\" appended to it.
5590 With repeat count, copy the exposed parts of only the current topic.
5592 Optional second arg TOBUF is target buffer name.
5594 Optional third arg FORMAT, if non-nil, symbolically designates an
5595 alternate presentation format for the outline:
5597 `flat' - Convert topic header prefixes to numeric
5598 section.subsection... identifiers.
5599 `indent' - Convert header prefixes to all white space, except for
5600 distinctive bullets.
5601 `indent-flat' - The best of both - only the first of each level has
5602 the full path, the rest have only the section number
5603 of the leaf, preceded by the right amount of indentation."
5607 (setq tobuf (get-buffer-create (concat "*" (buffer-name) " exposed*"))))
5608 (let* ((start-pt (point))
5609 (beg (if arg (allout-back-to-current-heading) (point-min)))
5610 (end (if arg (allout-end-of-current-subtree) (point-max)))
5611 (buf (current-buffer))
5613 (if (eq format 'flat)
5614 (setq format (if arg (save-excursion
5616 (allout-topic-flat-index))
5618 (with-current-buffer tobuf (erase-buffer))
5619 (allout-process-exposed 'allout-insert-listified
5625 (goto-char (point-min))
5627 (goto-char start-pt)))
5628 ;;;_ > allout-flatten-exposed-to-buffer (&optional arg tobuf)
5629 (defun allout-flatten-exposed-to-buffer (&optional arg tobuf)
5630 "Present numeric outline of outline's exposed portions in another buffer.
5632 The resulting outline is not compatible with outline mode -- use
5633 `allout-copy-exposed-to-buffer' if you want that.
5635 Use `allout-indented-exposed-to-buffer' for indented presentation.
5637 With repeat count, copy the exposed portions of only current topic.
5639 Other buffer has current buffer's name with \" exposed\" appended to
5640 it, unless optional second arg TOBUF is specified, in which case it is
5643 (allout-copy-exposed-to-buffer arg tobuf 'flat))
5644 ;;;_ > allout-indented-exposed-to-buffer (&optional arg tobuf)
5645 (defun allout-indented-exposed-to-buffer (&optional arg tobuf)
5646 "Present indented outline of outline's exposed portions in another buffer.
5648 The resulting outline is not compatible with outline mode -- use
5649 `allout-copy-exposed-to-buffer' if you want that.
5651 Use `allout-flatten-exposed-to-buffer' for numeric sectional presentation.
5653 With repeat count, copy the exposed portions of only current topic.
5655 Other buffer has current buffer's name with \" exposed\" appended to
5656 it, unless optional second arg TOBUF is specified, in which case it is
5659 (allout-copy-exposed-to-buffer arg tobuf 'indent))
5661 ;;;_ - LaTeX formatting
5662 ;;;_ > allout-latex-verb-quote (string &optional flow)
5663 (defun allout-latex-verb-quote (string &optional flow)
5664 "Return copy of STRING for literal reproduction across LaTeX processing.
5665 Expresses the original characters (including carriage returns) of the
5666 string across LaTeX processing."
5667 (mapconcat (function
5669 (cond ((memq char '(?\\ ?$ ?% ?# ?& ?{ ?} ?_ ?^ ?- ?*))
5670 (concat "\\char" (number-to-string char) "{}"))
5671 ((= char ?\n) "\\\\")
5672 (t (char-to-string char)))))
5675 ;;;_ > allout-latex-verbatim-quote-curr-line ()
5676 (defun allout-latex-verbatim-quote-curr-line ()
5677 "Express line for exact (literal) representation across LaTeX processing.
5679 Adjust line contents so it is unaltered (from the original line)
5680 across LaTeX processing, within the context of a `verbatim'
5681 environment. Leaves point at the end of the line."
5682 (let ((inhibit-field-text-motion t))
5685 (end (point-at-eol)))
5687 (while (re-search-forward "\\\\"
5688 ;;"\\\\\\|\\{\\|\\}\\|\\_\\|\\$\\|\\\"\\|\\&\\|\\^\\|\\-\\|\\*\\|#"
5689 end ; bounded by end-of-line
5690 1) ; no matches, move to end & return nil
5691 (goto-char (match-beginning 2))
5694 (goto-char (1+ (match-end 2))))))))
5695 ;;;_ > allout-insert-latex-header (buffer)
5696 (defun allout-insert-latex-header (buffer)
5697 "Insert initial LaTeX commands at point in BUFFER."
5698 ;; Much of this is being derived from the stuff in appendix of E in
5699 ;; the TeXBook, pg 421.
5701 (let ((doc-style (format "\n\\documentstyle{%s}\n"
5703 (page-numbering (if allout-number-pages
5704 "\\pagestyle{empty}\n"
5706 (titlecmd (format "\\newcommand{\\titlecmd}[1]{{%s #1}}\n"
5707 allout-title-style))
5708 (labelcmd (format "\\newcommand{\\labelcmd}[1]{{%s #1}}\n"
5709 allout-label-style))
5710 (headlinecmd (format "\\newcommand{\\headlinecmd}[1]{{%s #1}}\n"
5711 allout-head-line-style))
5712 (bodylinecmd (format "\\newcommand{\\bodylinecmd}[1]{{%s #1}}\n"
5713 allout-body-line-style))
5714 (setlength (format "%s%s%s%s"
5715 "\\newlength{\\stepsize}\n"
5716 "\\setlength{\\stepsize}{"
5719 (oneheadline (format "%s%s%s%s%s%s%s"
5720 "\\newcommand{\\OneHeadLine}[3]{%\n"
5722 "\\hspace*{#2\\stepsize}%\n"
5723 "\\labelcmd{#1}\\hspace*{.2cm}"
5724 "\\headlinecmd{#3}\\\\["
5727 (onebodyline (format "%s%s%s%s%s%s"
5728 "\\newcommand{\\OneBodyLine}[2]{%\n"
5730 "\\hspace*{#1\\stepsize}%\n"
5731 "\\bodylinecmd{#2}\\\\["
5734 (begindoc "\\begin{document}\n\\begin{center}\n")
5735 (title (format "%s%s%s%s"
5737 (allout-latex-verb-quote (if allout-title
5740 (error "<unnamed buffer>"))
5743 "\\end{center}\n\n"))
5744 (hsize "\\hsize = 7.5 true in\n")
5745 (hoffset "\\hoffset = -1.5 true in\n")
5746 (vspace "\\vspace{.1cm}\n\n"))
5747 (insert (concat doc-style
5762 ;;;_ > allout-insert-latex-trailer (buffer)
5763 (defun allout-insert-latex-trailer (buffer)
5764 "Insert concluding LaTeX commands at point in BUFFER."
5766 (insert "\n\\end{document}\n"))
5767 ;;;_ > allout-latexify-one-item (depth prefix bullet text)
5768 (defun allout-latexify-one-item (depth prefix bullet text)
5769 "Insert LaTeX commands for formatting one outline item.
5771 Args are the topics numeric DEPTH, the header PREFIX lead string, the
5772 BULLET string, and a list of TEXT strings for the body."
5773 (let* ((head-line (if text (car text)))
5774 (body-lines (cdr text))
5778 (insert (concat "\\OneHeadLine{\\verb\1 "
5779 (allout-latex-verb-quote bullet)
5784 (allout-latex-verb-quote head-line)
5787 (if (not body-lines)
5789 ;;(insert "\\beginlines\n")
5790 (insert "\\begin{verbatim}\n")
5792 (setq curr-line (car body-lines))
5793 (if (and (not body-content)
5794 (not (string-match "^\\s-*$" curr-line)))
5795 (setq body-content t))
5796 ; Mangle any occurrences of
5797 ; "\end{verbatim}" in text,
5799 (if (and body-content
5800 (setq bop (string-match "\\end{verbatim}" curr-line)))
5801 (setq curr-line (concat (substring curr-line 0 bop)
5803 (substring curr-line bop))))
5804 ;;(insert "|" (car body-lines) "|")
5806 (allout-latex-verbatim-quote-curr-line)
5808 (setq body-lines (cdr body-lines)))
5810 (setq body-content nil)
5814 ;;(insert "\\endlines\n")
5815 (insert "\\end{verbatim}\n")
5817 ;;;_ > allout-latexify-exposed (arg &optional tobuf)
5818 (defun allout-latexify-exposed (arg &optional tobuf)
5819 "Format current topics exposed portions to TOBUF for LaTeX processing.
5820 TOBUF defaults to a buffer named the same as the current buffer, but
5821 with \"*\" prepended and \" latex-formed*\" appended.
5823 With repeat count, copy the exposed portions of entire buffer."
5828 (get-buffer-create (concat "*" (buffer-name) " latexified*"))))
5829 (let* ((start-pt (point))
5830 (beg (if arg (point-min) (allout-back-to-current-heading)))
5831 (end (if arg (point-max) (allout-end-of-current-subtree)))
5832 (buf (current-buffer)))
5835 (allout-insert-latex-header tobuf)
5836 (goto-char (point-max))
5837 (allout-process-exposed 'allout-latexify-one-item
5842 (goto-char (point-max))
5843 (allout-insert-latex-trailer tobuf)
5844 (goto-char (point-min))
5846 (goto-char start-pt)))
5849 ;;;_ > allout-toggle-current-subtree-encryption (&optional keymode-cue)
5850 (defun allout-toggle-current-subtree-encryption (&optional keymode-cue)
5851 "Encrypt clear or decrypt encoded topic text.
5853 Allout uses emacs 'epg' libary to perform encryption. Symmetric
5854 and keypair encryption are supported. All encryption is ascii
5857 Entry encryption defaults to symmetric key mode unless keypair
5858 recipients are associated with the file \(see
5859 `epa-file-encrypt-to') or the function is invoked with a
5860 \(KEYMODE-CUE) universal argument greater than 1.
5862 When encrypting, KEYMODE-CUE universal argument greater than 1
5863 causes prompting for recipients for public-key keypair
5864 encryption. Selecting no recipients results in symmetric key
5867 Further, encrypting with a KEYMODE-CUE universal argument greater
5868 than 4 - eg, preceded by a doubled Ctrl-U - causes association of
5869 the specified recipients with the file, replacing those currently
5870 associated with it. This can be used to deassociate any
5871 recipients with the file, by selecting no recipients in the
5874 Encrypted topic's bullets are set to a `~' to signal that the
5875 contents of the topic (body and subtopics, but not heading) is
5876 pending encryption or encrypted. `*' asterisk immediately after
5877 the bullet signals that the body is encrypted, its absence means
5878 the topic is meant to be encrypted but is not currently. When a
5879 file with topics pending encryption is saved, topics pending
5880 encryption are encrypted. See allout-encrypt-unencrypted-on-saves
5881 for auto-encryption specifics.
5883 \*NOTE WELL* that automatic encryption that happens during saves will
5884 default to symmetric encryption -- you must deliberately (re)encrypt key-pair
5885 encrypted topics if you want them to continue to use the key-pair cipher.
5887 Level-one topics, with prefix consisting solely of an `*' asterisk, cannot be
5888 encrypted. If you want to encrypt the contents of a top-level topic, use
5889 \\[allout-shift-in] to increase its depth."
5892 (allout-back-to-current-heading)
5893 (allout-toggle-subtree-encryption keymode-cue)))
5894 ;;;_ > allout-toggle-subtree-encryption (&optional keymode-cue)
5895 (defun allout-toggle-subtree-encryption (&optional keymode-cue)
5896 "Encrypt clear text or decrypt encoded topic contents (body and subtopics.)
5898 Entry encryption defaults to symmetric key mode unless keypair
5899 recipients are associated with the file \(see
5900 `epa-file-encrypt-to') or the function is invoked with a
5901 \(KEYMODE-CUE) universal argument greater than 1.
5903 When encrypting, KEYMODE-CUE universal argument greater than 1
5904 causes prompting for recipients for public-key keypair
5905 encryption. Selecting no recipients results in symmetric key
5908 Further, encrypting with a KEYMODE-CUE universal argument greater
5909 than 4 - eg, preceded by a doubled Ctrl-U - causes association of
5910 the specified recipients with the file, replacing those currently
5911 associated with it. This can be used to deassociate any
5912 recipients with the file, by selecting no recipients in the
5915 Encryption and decryption uses the emacs epg library.
5917 Encrypted text will be ascii-armored.
5919 See `allout-toggle-current-subtree-encryption' for more details."
5923 (allout-end-of-prefix t)
5925 (if (= allout-recent-depth 1)
5926 (error (concat "Cannot encrypt or decrypt level 1 topics -"
5927 " shift it in to make it encryptable")))
5929 (let* ((allout-buffer (current-buffer))
5931 (bullet-pos allout-recent-prefix-beginning)
5932 (after-bullet-pos (point))
5934 (progn (if (= (point-max) after-bullet-pos)
5935 (error "no body to encrypt"))
5936 (allout-encrypted-topic-p)))
5937 (was-collapsed (if (not (search-forward "\n" nil t))
5941 (subtree-beg (1+ (point)))
5942 (subtree-end (allout-end-of-subtree))
5943 (subject-text (buffer-substring-no-properties subtree-beg
5945 (subtree-end-char (char-after (1- subtree-end)))
5946 (subtree-trailing-char (char-after subtree-end))
5947 ;; kluge -- result-text needs to be nil, but we also want to
5948 ;; check for the error condition
5949 (result-text (if (or (string= "" subject-text)
5950 (string= "\n" subject-text))
5951 (error "No topic contents to %scrypt"
5952 (if was-encrypted "de" "en"))
5954 ;; Assess key parameters:
5955 (was-coding-system buffer-file-coding-system))
5957 (when (not was-encrypted)
5958 ;; ensure that non-ascii chars pending encryption are noticed before
5959 ;; they're encrypted, so the coding system is set to accommodate
5961 (setq buffer-file-coding-system
5962 (allout-select-safe-coding-system subtree-beg subtree-end))
5963 ;; if the coding system for the text being encrypted is different
5964 ;; than that prevailing, then there a real risk that the coding
5965 ;; system can't be noticed by emacs when the file is visited. to
5966 ;; mitigate that, offer to preserve the coding system using a file
5968 (if (and (not (equal buffer-file-coding-system
5971 (format (concat "Register coding system %s as file local"
5972 " var? Necessary when only encrypted text"
5973 " is in that coding system. ")
5974 buffer-file-coding-system)))
5975 (allout-adjust-file-variable "buffer-file-coding-system"
5976 buffer-file-coding-system)))
5979 (allout-encrypt-string subject-text was-encrypted
5980 (current-buffer) keymode-cue))
5982 ;; Replace the subtree with the processed product.
5985 (set-buffer allout-buffer)
5986 (delete-region subtree-beg subtree-end)
5987 (insert result-text)
5989 (allout-flag-region (1- subtree-beg) (point) t))
5990 ;; adjust trailing-blank-lines to preserve topic spacing:
5991 (if (not was-encrypted)
5992 (if (and (= subtree-end-char ?\n)
5993 (= subtree-trailing-char ?\n))
5994 (insert subtree-trailing-char)))
5995 ;; Ensure that the item has an encrypted-entry bullet:
5996 (if (not (string= (buffer-substring-no-properties
5997 (1- after-bullet-pos) after-bullet-pos)
5998 allout-topic-encryption-bullet))
5999 (progn (goto-char (1- after-bullet-pos))
6001 (insert allout-topic-encryption-bullet)))
6003 ;; Remove the is-encrypted bullet qualifier:
6004 (progn (goto-char after-bullet-pos)
6006 ;; Add the is-encrypted bullet qualifier:
6007 (goto-char after-bullet-pos)
6009 (run-hook-with-args 'allout-structure-added-hook
6010 bullet-pos subtree-end))))
6011 ;;;_ > allout-encrypt-string (text decrypt allout-buffer keymode-cue
6012 ;;; &optional rejected)
6013 (defun allout-encrypt-string (text decrypt allout-buffer keymode-cue
6015 "Encrypt or decrypt message TEXT.
6017 Returns the resulting string, or nil if the transformation fails.
6019 If DECRYPT is true (default false), then decrypt instead of encrypt.
6021 ALLOUT-BUFFER identifies the buffer containing the text.
6023 Entry encryption defaults to symmetric key mode unless keypair
6024 recipients are associated with the file \(see
6025 `epa-file-encrypt-to') or the function is invoked with a
6026 \(KEYMODE-CUE) universal argument greater than 1.
6028 When encrypting, KEYMODE-CUE universal argument greater than 1
6029 causes prompting for recipients for public-key keypair
6030 encryption. Selecting no recipients results in symmetric key
6033 Further, encrypting with a KEYMODE-CUE universal argument greater
6034 than 4 - eg, preceded by a doubled Ctrl-U - causes association of
6035 the specified recipients with the file, replacing those currently
6036 associated with it. This can be used to deassociate any
6037 recipients with the file, by selecting no recipients in the
6040 Optional REJECTED is for internal use, to convey the number of
6041 rejections due to matches against
6042 `allout-encryption-ciphertext-rejection-regexps', as limited by
6043 `allout-encryption-ciphertext-rejection-ceiling'.
6045 NOTE: A few GnuPG v2 versions improperly preserve incorrect
6046 symmetric decryption keys, preventing entry of the correct key on
6047 subsequent decryption attempts until the cache times-out. That
6048 can take several minutes. \(Decryption of other entries is not
6049 affected.) Upgrade your EasyPG version, if you can, and you can
6050 deliberately clear your gpg-agent's cache by sending it a '-HUP'
6056 (let* ((epg-context (let* ((context (epg-make-context nil t)))
6057 (epg-context-set-passphrase-callback
6058 context #'epa-passphrase-callback-function)
6060 (encoding (with-current-buffer allout-buffer
6061 buffer-file-coding-system))
6062 (multibyte (with-current-buffer allout-buffer
6063 enable-multibyte-characters))
6064 ;; "sanitization" avoids encryption results that are outline structure.
6065 (sani-regexps 'allout-encryption-plaintext-sanitization-regexps)
6066 (strip-plaintext-regexps (if (not decrypt)
6067 (allout-get-configvar-values
6069 (rejection-regexps 'allout-encryption-ciphertext-rejection-regexps)
6070 (reject-ciphertext-regexps (if (not decrypt)
6071 (allout-get-configvar-values
6072 rejection-regexps)))
6073 (rejected (or rejected 0))
6074 (rejections-left (- allout-encryption-ciphertext-rejection-ceiling
6076 (keypair-mode (cond (decrypt 'decrypting)
6077 ((<= (prefix-numeric-value keymode-cue) 1)
6079 ((<= (prefix-numeric-value keymode-cue) 4)
6081 ((> (prefix-numeric-value keymode-cue) 4)
6083 (keypair-message (concat "Select encryption recipients.\n"
6084 "Symmetric encryption is done if no"
6085 " recipients are selected. "))
6086 (encrypt-to (and (boundp 'epa-file-encrypt-to) epa-file-encrypt-to))
6092 ;; Massage the subject text for encoding and filtering.
6095 ;; convey the text characteristics of the original buffer:
6096 (allout-set-buffer-multibyte multibyte)
6098 (set-buffer-file-coding-system encoding)
6100 (encode-coding-region (point-min) (point-max) encoding)))
6102 ;; remove sanitization regexps matches before encrypting:
6103 (when (and strip-plaintext-regexps (not decrypt))
6104 (dolist (re strip-plaintext-regexps)
6105 (let ((re (if (listp re) (car re) re))
6106 (replacement (if (listp re) (cadr re) "")))
6107 (goto-char (point-min))
6109 (while (re-search-forward re nil t)
6110 (replace-match replacement nil nil))))))
6111 (setq massaged-text (buffer-substring-no-properties (point-min)
6113 ;; determine key mode and, if keypair, recipients:
6119 (default (if encrypt-to (epg-list-keys epg-context encrypt-to)))
6121 ((prompt prompt-save)
6122 (save-window-excursion
6123 (epa-select-keys epg-context keypair-message)))))
6127 (epg-decrypt-string epg-context
6128 (encode-coding-string massaged-text
6129 (or encoding 'utf-8)))
6130 (replace-regexp-in-string "\n$" ""
6131 (epg-encrypt-string epg-context
6132 (encode-coding-string massaged-text
6133 (or encoding 'utf-8))
6136 ;; validate result -- non-empty
6137 (if (not result-text)
6138 (error "%scryption failed." (if decrypt "De" "En")))
6141 (when (eq keypair-mode 'prompt-save)
6142 ;; set epa-file-encrypt-to in the buffer:
6143 (setq epa-file-encrypt-to (mapcar (lambda (key)
6145 (car (epg-key-user-id-list key))))
6147 ;; change the file variable:
6148 (allout-adjust-file-variable "epa-file-encrypt-to" epa-file-encrypt-to))
6151 ;; Retry (within limit) if ciphertext contains rejections:
6153 ;; Check for disqualification of this ciphertext:
6154 (let ((regexps reject-ciphertext-regexps)
6156 (while (and regexps (not reject-it))
6157 (setq reject-it (string-match (car regexps) result-text))
6160 (setq rejections-left (1- rejections-left))
6161 (if (<= rejections-left 0)
6162 (error (concat "Ciphertext rejected too many times"
6164 allout-encryption-ciphertext-rejection-ceiling
6165 'allout-encryption-ciphertext-rejection-regexps)
6166 ;; try again (gpg-agent may have the key cached):
6167 (allout-encrypt-string text decrypt allout-buffer keypair-mode
6170 ;; Barf if encryption yields extraordinary control chars:
6172 (string-match "[\C-a\C-k\C-o-\C-z\C-@]"
6174 (error (concat "Encryption produced non-armored text, which"
6175 "conflicts with allout mode -- reconfigure!")))
6178 ;;;_ > allout-encrypted-topic-p ()
6179 (defun allout-encrypted-topic-p ()
6180 "True if the current topic is encryptable and encrypted."
6182 (allout-end-of-prefix t)
6183 (and (string= (buffer-substring-no-properties (1- (point)) (point))
6184 allout-topic-encryption-bullet)
6185 (save-match-data (looking-at "\\*")))
6188 ;;;_ > allout-next-topic-pending-encryption (&optional except-mark)
6189 (defun allout-next-topic-pending-encryption (&optional except-mark)
6190 "Return the point of the next topic pending encryption, or nil if none.
6192 EXCEPT-MARK identifies a point whose containing topics should be excluded
6193 from encryption. This supports 'except-current mode of
6194 `allout-encrypt-unencrypted-on-saves'.
6196 Such a topic has the `allout-topic-encryption-bullet' without an
6197 immediately following '*' that would mark the topic as being encrypted. It
6198 must also have content."
6199 (let (done got content-beg)
6203 (if (not (re-search-forward
6204 (format "\\(\\`\\|\n\\)%s *%s[^*]"
6205 (regexp-quote allout-header-prefix)
6206 (regexp-quote allout-topic-encryption-bullet))
6210 (goto-char (setq got (match-beginning 0)))
6211 (if (save-match-data (looking-at "\n"))
6218 ((not (search-forward "\n"))
6227 (setq content-beg (point))
6229 (allout-end-of-subtree)
6230 (if (or (<= (point) content-beg)
6232 (<= content-beg except-mark)
6233 (>= (point) except-mark)))
6245 ;;;_ > allout-encrypt-decrypted (&optional except-mark)
6246 (defun allout-encrypt-decrypted (&optional except-mark)
6247 "Encrypt topics pending encryption except those containing exemption point.
6249 EXCEPT-MARK identifies a point whose containing topics should be excluded
6250 from encryption. This supports the `except-current' mode of
6251 `allout-encrypt-unencrypted-on-saves'.
6253 If a topic that is currently being edited was encrypted, we return a list
6254 containing the location of the topic and the location of the cursor just
6255 before the topic was encrypted. This can be used, eg, to decrypt the topic
6256 and exactly resituate the cursor if this is being done as part of a file
6257 save. See `allout-encrypt-unencrypted-on-saves' for more info."
6262 (let* ((current-mark (point-marker))
6263 (current-mark-position (marker-position current-mark))
6266 editing-topic editing-point)
6267 (goto-char (point-min))
6268 (while (allout-next-topic-pending-encryption except-mark)
6269 (setq was-modified (buffer-modified-p))
6270 (when (save-excursion
6271 (and (boundp 'allout-encrypt-unencrypted-on-saves)
6272 allout-encrypt-unencrypted-on-saves
6273 (setq bo-subtree (re-search-forward "$"))
6274 (not (allout-hidden-p))
6275 (>= current-mark (point))
6276 (allout-end-of-current-subtree)
6277 (<= current-mark (point))))
6278 (setq editing-topic (point)
6279 ;; we had to wait for this 'til now so prior topics are
6280 ;; encrypted, any relevant text shifts are in place:
6281 editing-point (- current-mark-position
6282 (count-trailing-whitespace-region
6283 bo-subtree current-mark-position))))
6284 (allout-toggle-subtree-encryption)
6285 (if (not was-modified)
6286 (set-buffer-modified-p nil))
6288 (if (not was-modified)
6289 (set-buffer-modified-p nil))
6290 (if editing-topic (list editing-topic editing-point))
6296 ;;;_ #9 miscellaneous
6298 ;;;_ > outlineify-sticky ()
6299 ;; outlinify-sticky is correct spelling; provide this alias for sticklers:
6301 (defalias 'outlinify-sticky 'outlineify-sticky)
6303 (defun outlineify-sticky (&optional arg)
6304 "Activate outline mode and establish file var so it is started subsequently.
6306 See doc-string for `allout-layout' and `allout-init' for details on
6307 setup for auto-startup."
6311 (if (allout-mode-p) (allout-mode)) ; deactivate so we can re-activate...
6315 (goto-char (point-min))
6316 (if (allout-goto-prefix)
6318 (allout-open-topic 2)
6319 (insert (concat "Dummy outline topic header -- see"
6320 "`allout-mode' docstring: `^Hm'."))
6321 (allout-adjust-file-variable
6322 "allout-layout" (or allout-layout '(-1 : 0))))))
6323 ;;;_ > allout-file-vars-section-data ()
6324 (defun allout-file-vars-section-data ()
6325 "Return data identifying the file-vars section, or nil if none.
6327 Returns a list of the form (BEGINNING-POINT PREFIX-STRING SUFFIX-STRING)."
6328 ;; minimally gleaned from emacs 21.4 files.el hack-local-variables function.
6329 (let (beg prefix suffix)
6331 (goto-char (point-max))
6332 (search-backward "\n\^L" (max (- (point-max) 3000) (point-min)) 'move)
6333 (if (let ((case-fold-search t))
6334 (not (search-forward "Local Variables:" nil t)))
6336 (setq beg (- (point) 16))
6337 (setq suffix (buffer-substring-no-properties
6339 (progn (if (search-forward "\n" nil t)
6342 (setq prefix (buffer-substring-no-properties
6343 (progn (if (search-backward "\n" nil t)
6347 (list beg prefix suffix))
6351 ;;;_ > allout-adjust-file-variable (varname value)
6352 (defun allout-adjust-file-variable (varname value)
6353 "Adjust the setting of an Emacs file variable named VARNAME to VALUE.
6355 This activity is inhibited if either `enable-local-variables'
6356 `allout-enable-file-variable-adjustment' are nil.
6358 When enabled, an entry for the variable is created if not already present,
6359 or changed if established with a different value. The section for the file
6360 variables, itself, is created if not already present. When created, the
6361 section lines (including the section line) exist as second-level topics in
6362 a top-level topic at the end of the file.
6364 `enable-local-variables' must be true for any of this to happen."
6365 (if (not (and enable-local-variables
6366 allout-enable-file-variable-adjustment))
6369 (let ((inhibit-field-text-motion t)
6370 (section-data (allout-file-vars-section-data))
6373 (setq beg (car section-data)
6374 prefix (cadr section-data)
6375 suffix (car (cddr section-data)))
6376 ;; create the section
6377 (goto-char (point-max))
6379 (allout-open-topic 0)
6381 (insert "Local emacs vars.\n")
6382 (allout-open-topic 1)
6385 prefix (buffer-substring-no-properties (progn
6390 (insert "Local variables:\n")
6391 (allout-open-topic 0)
6394 ;; look for existing entry or create one, leaving point for insertion
6397 (allout-show-to-offshoot)
6398 (if (search-forward (concat "\n" prefix varname ":") nil t)
6399 (let* ((value-beg (point))
6400 (line-end (progn (if (search-forward "\n" nil t)
6403 (value-end (- line-end (length suffix))))
6404 (if (> value-end value-beg)
6405 (delete-region value-beg value-end)))
6409 (insert (concat prefix varname ":")))
6410 (insert (format " %S%s" value suffix))
6415 ;;;_ > allout-get-configvar-values (varname)
6416 (defun allout-get-configvar-values (configvar-name)
6417 "Return a list of values of the symbols in list bound to CONFIGVAR-NAME.
6419 The user is prompted for removal of symbols that are unbound, and they
6420 otherwise are ignored.
6422 CONFIGVAR-NAME should be the name of the configuration variable,
6425 (let ((configvar-value (symbol-value configvar-name))
6427 (dolist (sym configvar-value)
6428 (if (not (boundp sym))
6429 (if (yes-or-no-p (format "%s entry `%s' is unbound -- remove it? "
6430 configvar-name sym))
6431 (delq sym (symbol-value configvar-name)))
6432 (push (symbol-value sym) got)))
6435 ;;;_ > allout-mark-topic ()
6436 (defun allout-mark-topic ()
6437 "Put the region around topic currently containing point."
6439 (let ((inhibit-field-text-motion t))
6440 (beginning-of-line))
6441 (allout-goto-prefix-doublechecked)
6443 (allout-end-of-current-subtree)
6444 (exchange-point-and-mark))
6446 ;;;_ > solicit-char-in-string (prompt string &optional do-defaulting)
6447 (defun solicit-char-in-string (prompt string &optional do-defaulting)
6448 "Solicit (with first arg PROMPT) choice of a character from string STRING.
6450 Optional arg DO-DEFAULTING indicates to accept empty input (CR)."
6452 (let ((new-prompt prompt)
6456 (message "%s" new-prompt)
6458 ;; We do our own reading here, so we can circumvent, eg, special
6459 ;; treatment for `?' character. (Oughta use minibuffer keymap instead.)
6461 (char-to-string (let ((cursor-in-echo-area nil)) (read-char))))
6464 (cond ((string-match (regexp-quote got) string) got)
6465 ((and do-defaulting (string= got "\r"))
6466 ;; Return empty string to default:
6468 ((string= got "\C-g") (signal 'quit nil))
6470 (setq new-prompt (concat prompt
6476 ;; got something out of loop -- return it:
6480 ;;;_ > regexp-sans-escapes (string)
6481 (defun regexp-sans-escapes (regexp &optional successive-backslashes)
6482 "Return a copy of REGEXP with all character escapes stripped out.
6484 Representations of actual backslashes -- '\\\\\\\\' -- are left as a
6487 Optional arg SUCCESSIVE-BACKSLASHES is used internally for recursion."
6489 (if (string= regexp "")
6491 ;; Set successive-backslashes to number if current char is
6492 ;; backslash, or else to nil:
6493 (setq successive-backslashes
6494 (if (= (aref regexp 0) ?\\)
6495 (if successive-backslashes (1+ successive-backslashes) 1)
6497 (if (or (not successive-backslashes) (= 2 successive-backslashes))
6498 ;; Include first char:
6499 (concat (substring regexp 0 1)
6500 (regexp-sans-escapes (substring regexp 1)))
6501 ;; Exclude first char, but maintain count:
6502 (regexp-sans-escapes (substring regexp 1) successive-backslashes))))
6503 ;;;_ > count-trailing-whitespace-region (beg end)
6504 (defun count-trailing-whitespace-region (beg end)
6505 "Return number of trailing whitespace chars between BEG and END.
6507 If BEG is bigger than END we return 0."
6514 (while (re-search-forward "[ ][ ]*$" end t)
6515 (goto-char (1+ (match-beginning 2)))
6516 (setq count (1+ count)))
6518 ;;;_ > allout-format-quote (string)
6519 (defun allout-format-quote (string)
6520 "Return a copy of string with all \"%\" characters doubled."
6522 (mapcar (lambda (char) (if (= char ?%) "%%" (char-to-string char)))
6525 ;;;_ > allout-flatten (list)
6526 (defun allout-flatten (list)
6527 "Return a list of all atoms in list."
6529 (cond ((null list) nil)
6530 ((atom (car list)) (cons (car list) (allout-flatten (cdr list))))
6531 (t (append (allout-flatten (car list)) (allout-flatten (cdr list))))))
6532 ;;;_ : Compatibility:
6533 ;;;_ : xemacs undo-in-progress provision:
6534 (unless (boundp 'undo-in-progress)
6535 (defvar undo-in-progress nil
6536 "Placeholder defvar for XEmacs compatibility from allout.el.")
6537 (defadvice undo-more (around allout activate)
6538 ;; This defadvice used only in emacs that lack undo-in-progress, eg xemacs.
6539 (let ((undo-in-progress t)) ad-do-it)))
6541 ;;;_ > allout-mark-marker to accommodate divergent emacsen:
6542 (defun allout-mark-marker (&optional force buffer)
6543 "Accommodate the different signature for `mark-marker' across Emacsen.
6545 XEmacs takes two optional args, while mainline GNU Emacs does not,
6546 so pass them along when appropriate."
6547 (if (featurep 'xemacs)
6548 (apply 'mark-marker force buffer)
6550 ;;;_ > subst-char-in-string if necessary
6551 (if (not (fboundp 'subst-char-in-string))
6552 (defun subst-char-in-string (fromchar tochar string &optional inplace)
6553 "Replace FROMCHAR with TOCHAR in STRING each time it occurs.
6554 Unless optional argument INPLACE is non-nil, return a new string."
6555 (let ((i (length string))
6556 (newstr (if inplace string (copy-sequence string))))
6559 (if (eq (aref newstr i) fromchar)
6560 (aset newstr i tochar)))
6562 ;;;_ > wholenump if necessary
6563 (if (not (fboundp 'wholenump))
6564 (defalias 'wholenump 'natnump))
6565 ;;;_ > remove-overlays if necessary
6566 (if (not (fboundp 'remove-overlays))
6567 (defun remove-overlays (&optional beg end name val)
6568 "Clear BEG and END of overlays whose property NAME has value VAL.
6569 Overlays might be moved and/or split.
6570 BEG and END default respectively to the beginning and end of buffer."
6571 (unless beg (setq beg (point-min)))
6572 (unless end (setq end (point-max)))
6574 (setq beg (prog1 end (setq end beg))))
6576 (dolist (o (overlays-in beg end))
6577 (when (eq (overlay-get o name) val)
6578 ;; Either push this overlay outside beg...end
6579 ;; or split it to exclude beg...end
6580 ;; or delete it entirely (if it is contained in beg...end).
6581 (if (< (overlay-start o) beg)
6582 (if (> (overlay-end o) end)
6584 (move-overlay (copy-overlay o)
6585 (overlay-start o) beg)
6586 (move-overlay o end (overlay-end o)))
6587 (move-overlay o (overlay-start o) beg))
6588 (if (> (overlay-end o) end)
6589 (move-overlay o end (overlay-end o))
6590 (delete-overlay o)))))))
6592 ;;;_ > copy-overlay if necessary -- xemacs ~ 21.4
6593 (if (not (fboundp 'copy-overlay))
6594 (defun copy-overlay (o)
6595 "Return a copy of overlay O."
6596 (let ((o1 (make-overlay (overlay-start o) (overlay-end o)
6597 ;; FIXME: there's no easy way to find the
6598 ;; insertion-type of the two markers.
6599 (overlay-buffer o)))
6600 (props (overlay-properties o)))
6602 (overlay-put o1 (pop props) (pop props)))
6604 ;;;_ > add-to-invisibility-spec if necessary -- xemacs ~ 21.4
6605 (if (not (fboundp 'add-to-invisibility-spec))
6606 (defun add-to-invisibility-spec (element)
6607 "Add ELEMENT to `buffer-invisibility-spec'.
6608 See documentation for `buffer-invisibility-spec' for the kind of elements
6610 (if (eq buffer-invisibility-spec t)
6611 (setq buffer-invisibility-spec (list t)))
6612 (setq buffer-invisibility-spec
6613 (cons element buffer-invisibility-spec))))
6614 ;;;_ > remove-from-invisibility-spec if necessary -- xemacs ~ 21.4
6615 (if (not (fboundp 'remove-from-invisibility-spec))
6616 (defun remove-from-invisibility-spec (element)
6617 "Remove ELEMENT from `buffer-invisibility-spec'."
6618 (if (consp buffer-invisibility-spec)
6619 (setq buffer-invisibility-spec (delete element
6620 buffer-invisibility-spec)))))
6621 ;;;_ > move-beginning-of-line if necessary -- older emacs, xemacs
6622 (if (not (fboundp 'move-beginning-of-line))
6623 (defun move-beginning-of-line (arg)
6624 "Move point to beginning of current line as displayed.
6625 \(This disregards invisible newlines such as those
6626 which are part of the text that an image rests on.)
6628 With argument ARG not nil or 1, move forward ARG - 1 lines first.
6629 If point reaches the beginning or end of buffer, it stops there.
6630 To ignore intangibility, bind `inhibit-point-motion-hooks' to t."
6632 (or arg (setq arg 1))
6634 (condition-case nil (line-move (1- arg)) (error nil)))
6636 ;; Move to beginning-of-line, ignoring fields and invisibles.
6637 (skip-chars-backward "^\n")
6638 (while (and (not (bobp))
6640 (get-char-property (1- (point)) 'invisible)))
6641 (if (eq buffer-invisibility-spec t)
6643 (or (memq prop buffer-invisibility-spec)
6644 (assq prop buffer-invisibility-spec)))))
6645 (goto-char (if (featurep 'xemacs)
6646 (previous-property-change (point))
6647 (previous-char-property-change (point))))
6648 (skip-chars-backward "^\n"))
6649 (vertical-motion 0))
6651 ;;;_ > move-end-of-line if necessary -- Emacs < 22.1, xemacs
6652 (if (not (fboundp 'move-end-of-line))
6653 (defun move-end-of-line (arg)
6654 "Move point to end of current line as displayed.
6655 \(This disregards invisible newlines such as those
6656 which are part of the text that an image rests on.)
6658 With argument ARG not nil or 1, move forward ARG - 1 lines first.
6659 If point reaches the beginning or end of buffer, it stops there.
6660 To ignore intangibility, bind `inhibit-point-motion-hooks' to t."
6662 (or arg (setq arg 1))
6667 (let ((goal-column 0))
6668 (and (condition-case nil
6669 (or (line-move arg) t)
6677 (get-char-property (1- (point))
6679 (if (eq buffer-invisibility-spec t)
6682 buffer-invisibility-spec)
6684 buffer-invisibility-spec)))))
6686 (previous-char-property-change (point))))
6690 (if (and (> (point) newpos)
6691 (eq (preceding-char) ?\n))
6693 (if (and (> (point) newpos) (not (eobp))
6694 (not (eq (following-char) ?\n)))
6695 ;; If we skipped something intangible
6696 ;; and now we're not really at eol,
6701 ;;;_ > allout-next-single-char-property-change -- alias unless lacking
6702 (defalias 'allout-next-single-char-property-change
6703 (if (fboundp 'next-single-char-property-change)
6704 'next-single-char-property-change
6705 'next-single-property-change)
6706 ;; No docstring because xemacs defalias doesn't support it.
6708 ;;;_ > allout-previous-single-char-property-change -- alias unless lacking
6709 (defalias 'allout-previous-single-char-property-change
6710 (if (fboundp 'previous-single-char-property-change)
6711 'previous-single-char-property-change
6712 'previous-single-property-change)
6713 ;; No docstring because xemacs defalias doesn't support it.
6715 ;;;_ > allout-set-buffer-multibyte
6716 (if (fboundp 'set-buffer-multibyte)
6717 (defalias 'allout-set-buffer-multibyte 'set-buffer-multibyte)
6719 ;; this definition is used only in older or alternative emacs, where
6720 ;; the setting is our only recourse.
6721 (defun allout-set-buffer-multibyte (is-multibyte)
6722 (set enable-multibyte-characters is-multibyte))))
6723 ;;;_ > allout-select-safe-coding-system
6724 (defalias 'allout-select-safe-coding-system
6725 (if (fboundp 'select-safe-coding-system)
6726 'select-safe-coding-system
6727 'detect-coding-region)
6729 ;;;_ > allout-substring-no-properties
6730 ;; define as alias first, so byte compiler is happy.
6731 (defalias 'allout-substring-no-properties 'substring-no-properties)
6732 ;; then supplant with definition if underlying alias absent.
6733 (if (not (fboundp 'substring-no-properties))
6734 (defun allout-substring-no-properties (string &optional start end)
6735 (substring string (or start 0) end))
6739 ;;;_ > allout-bullet-isearch (&optional bullet)
6740 (defun allout-bullet-isearch (&optional bullet)
6741 "Isearch (regexp) for topic with bullet BULLET."
6744 (setq bullet (solicit-char-in-string
6745 "ISearch for topic with bullet: "
6746 (regexp-sans-escapes allout-bullets-string))))
6748 (let ((isearch-regexp t)
6749 (isearch-string (concat "^"
6750 allout-header-prefix
6753 (isearch-repeat 'forward)
6756 ;;;_ #11 Unit tests -- this should be last item before "Provide"
6757 ;;;_ > allout-run-unit-tests ()
6758 (defun allout-run-unit-tests ()
6759 "Run the various allout unit tests."
6760 (message "Running allout tests...")
6761 (allout-test-resumptions)
6762 (message "Running allout tests... Done.")
6764 ;;;_ : test resumptions:
6765 ;;;_ > allout-tests-obliterate-variable (name)
6766 (defun allout-tests-obliterate-variable (name)
6767 "Completely unbind variable with NAME."
6768 (if (local-variable-p name (current-buffer)) (kill-local-variable name))
6769 (while (boundp name) (makunbound name)))
6770 ;;;_ > allout-test-resumptions ()
6771 (defvar allout-tests-globally-unbound nil
6772 "Fodder for allout resumptions tests -- defvar just for byte compiler.")
6773 (defvar allout-tests-globally-true nil
6774 "Fodder for allout resumptions tests -- defvar just for byte compiler.")
6775 (defvar allout-tests-locally-true nil
6776 "Fodder for allout resumptions tests -- defvar just for byte compiler.")
6777 (defun allout-test-resumptions ()
6778 "Exercise allout resumptions."
6779 ;; for each resumption case, we also test that the right local/global
6780 ;; scopes are affected during resumption effects:
6782 ;; ensure that previously unbound variables return to the unbound state.
6784 (allout-tests-obliterate-variable 'allout-tests-globally-unbound)
6785 (allout-add-resumptions '(allout-tests-globally-unbound t))
6786 (assert (not (default-boundp 'allout-tests-globally-unbound)))
6787 (assert (local-variable-p 'allout-tests-globally-unbound (current-buffer)))
6788 (assert (boundp 'allout-tests-globally-unbound))
6789 (assert (equal allout-tests-globally-unbound t))
6790 (allout-do-resumptions)
6791 (assert (not (local-variable-p 'allout-tests-globally-unbound
6793 (assert (not (boundp 'allout-tests-globally-unbound))))
6795 ;; ensure that variable with prior global value is resumed
6797 (allout-tests-obliterate-variable 'allout-tests-globally-true)
6798 (setq allout-tests-globally-true t)
6799 (allout-add-resumptions '(allout-tests-globally-true nil))
6800 (assert (equal (default-value 'allout-tests-globally-true) t))
6801 (assert (local-variable-p 'allout-tests-globally-true (current-buffer)))
6802 (assert (equal allout-tests-globally-true nil))
6803 (allout-do-resumptions)
6804 (assert (not (local-variable-p 'allout-tests-globally-true
6806 (assert (boundp 'allout-tests-globally-true))
6807 (assert (equal allout-tests-globally-true t)))
6809 ;; ensure that prior local value is resumed
6811 (allout-tests-obliterate-variable 'allout-tests-locally-true)
6812 (set (make-local-variable 'allout-tests-locally-true) t)
6813 (assert (not (default-boundp 'allout-tests-locally-true))
6814 nil (concat "Test setup mistake -- variable supposed to"
6815 " not have global binding, but it does."))
6816 (assert (local-variable-p 'allout-tests-locally-true (current-buffer))
6817 nil (concat "Test setup mistake -- variable supposed to have"
6818 " local binding, but it lacks one."))
6819 (allout-add-resumptions '(allout-tests-locally-true nil))
6820 (assert (not (default-boundp 'allout-tests-locally-true)))
6821 (assert (local-variable-p 'allout-tests-locally-true (current-buffer)))
6822 (assert (equal allout-tests-locally-true nil))
6823 (allout-do-resumptions)
6824 (assert (boundp 'allout-tests-locally-true))
6825 (assert (local-variable-p 'allout-tests-locally-true (current-buffer)))
6826 (assert (equal allout-tests-locally-true t))
6827 (assert (not (default-boundp 'allout-tests-locally-true))))
6829 ;; ensure that last of multiple resumptions holds, for various scopes.
6831 (allout-tests-obliterate-variable 'allout-tests-globally-unbound)
6832 (allout-tests-obliterate-variable 'allout-tests-globally-true)
6833 (setq allout-tests-globally-true t)
6834 (allout-tests-obliterate-variable 'allout-tests-locally-true)
6835 (set (make-local-variable 'allout-tests-locally-true) t)
6836 (allout-add-resumptions '(allout-tests-globally-unbound t)
6837 '(allout-tests-globally-true nil)
6838 '(allout-tests-locally-true nil))
6839 (allout-add-resumptions '(allout-tests-globally-unbound 2)
6840 '(allout-tests-globally-true 3)
6841 '(allout-tests-locally-true 4))
6842 ;; reestablish many of the basic conditions are maintained after re-add:
6843 (assert (not (default-boundp 'allout-tests-globally-unbound)))
6844 (assert (local-variable-p 'allout-tests-globally-unbound (current-buffer)))
6845 (assert (equal allout-tests-globally-unbound 2))
6846 (assert (default-boundp 'allout-tests-globally-true))
6847 (assert (local-variable-p 'allout-tests-globally-true (current-buffer)))
6848 (assert (equal allout-tests-globally-true 3))
6849 (assert (not (default-boundp 'allout-tests-locally-true)))
6850 (assert (local-variable-p 'allout-tests-locally-true (current-buffer)))
6851 (assert (equal allout-tests-locally-true 4))
6852 (allout-do-resumptions)
6853 (assert (not (local-variable-p 'allout-tests-globally-unbound
6855 (assert (not (boundp 'allout-tests-globally-unbound)))
6856 (assert (not (local-variable-p 'allout-tests-globally-true
6858 (assert (boundp 'allout-tests-globally-true))
6859 (assert (equal allout-tests-globally-true t))
6860 (assert (boundp 'allout-tests-locally-true))
6861 (assert (local-variable-p 'allout-tests-locally-true (current-buffer)))
6862 (assert (equal allout-tests-locally-true t))
6863 (assert (not (default-boundp 'allout-tests-locally-true))))
6865 ;; ensure that deliberately unbinding registered variables doesn't foul things
6867 (allout-tests-obliterate-variable 'allout-tests-globally-unbound)
6868 (allout-tests-obliterate-variable 'allout-tests-globally-true)
6869 (setq allout-tests-globally-true t)
6870 (allout-tests-obliterate-variable 'allout-tests-locally-true)
6871 (set (make-local-variable 'allout-tests-locally-true) t)
6872 (allout-add-resumptions '(allout-tests-globally-unbound t)
6873 '(allout-tests-globally-true nil)
6874 '(allout-tests-locally-true nil))
6875 (allout-tests-obliterate-variable 'allout-tests-globally-unbound)
6876 (allout-tests-obliterate-variable 'allout-tests-globally-true)
6877 (allout-tests-obliterate-variable 'allout-tests-locally-true)
6878 (allout-do-resumptions))
6880 ;;;_ % Run unit tests if `allout-run-unit-tests-after-load' is true:
6881 (when allout-run-unit-tests-on-load
6882 (allout-run-unit-tests))
6887 ;;;_* Local emacs vars.
6888 ;; The following `allout-layout' local variable setting:
6889 ;; - closes all topics from the first topic to just before the third-to-last,
6890 ;; - shows the children of the third to last (config vars)
6891 ;; - and the second to last (code section),
6892 ;; - and closes the last topic (this local-variables section).
6894 ;;allout-layout: (0 : -1 -1 0)
6897 ;;; allout.el ends here