1 ;;; allout.el --- extensive outline mode for use alone and with other modes
3 ;; Copyright (C) 1992-1994, 2001-2011 Free Software Foundation, Inc.
5 ;; Author: Ken Manheimer <ken dot manheimer at gmail dot com>
6 ;; Maintainer: Ken Manheimer <ken dot manheimer at gmail dot com>
7 ;; Created: Dec 1991 -- first release to usenet
9 ;; Keywords: outlines wp languages
10 ;; Website: http://myriadicity.net/Sundry/EmacsAllout
12 ;; This file is part of GNU Emacs.
14 ;; GNU Emacs is free software: you can redistribute it and/or modify
15 ;; it under the terms of the GNU General Public License as published by
16 ;; the Free Software Foundation, either version 3 of the License, or
17 ;; (at your option) any later version.
19 ;; GNU Emacs is distributed in the hope that it will be useful,
20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 ;; GNU General Public License for more details.
24 ;; You should have received a copy of the GNU General Public License
25 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
29 ;; Allout outline minor mode provides extensive outline formatting and
30 ;; and manipulation beyond standard emacs outline mode. Some features:
32 ;; - Classic outline-mode topic-oriented navigation and exposure adjustment
33 ;; - Topic-oriented editing including coherent topic and subtopic
34 ;; creation, promotion, demotion, cut/paste across depths, etc.
35 ;; - Incremental search with dynamic exposure and reconcealment of text
36 ;; - Customizable bullet format -- enables programming-language specific
37 ;; outlining, for code-folding editing. (Allout code itself is to try it;
38 ;; formatted as an outline -- do ESC-x eval-buffer in allout.el; but
39 ;; emacs local file variables need to be enabled when the
40 ;; file was visited -- see `enable-local-variables'.)
41 ;; - Configurable per-file initial exposure settings
42 ;; - Symmetric-key and key-pair topic encryption, plus symmetric passphrase
43 ;; mnemonic support, with verification against an established passphrase
44 ;; (using a stashed encrypted dummy string) and user-supplied hint
45 ;; maintenance. Encryption is via the Emacs 'epg' library. See
46 ;; allout-toggle-current-subtree-encryption docstring.
47 ;; - Automatic topic-number maintenance
48 ;; - "Hot-spot" operation, for single-keystroke maneuvering and
49 ;; exposure control (see the allout-mode docstring)
50 ;; - Easy rendering of exposed portions into numbered, latex, indented, etc
52 ;; - Careful attention to whitespace -- enabling blank lines between items
53 ;; and maintenance of hanging indentation (in paragraph auto-fill and
54 ;; across topic promotion and demotion) of topic bodies consistent with
55 ;; indentation of their topic header.
59 ;; See the `allout-mode' function's docstring for an introduction to the
62 ;; The latest development version and helpful notes are available at
63 ;; http://myriadicity.net/Sundry/EmacsAllout .
65 ;; The outline menubar additions provide quick reference to many of
66 ;; the features, and see the docstring of the variable `allout-init'
67 ;; for instructions on priming your Emacs session for automatic
68 ;; activation of allout-mode.
70 ;; See the docstring of the variables `allout-layout' and
71 ;; `allout-auto-activation' for details on automatic activation of
72 ;; `allout-mode' as a minor mode. (It has changed since allout
73 ;; 3.x, for those of you that depend on the old method.)
75 ;; Note -- the lines beginning with `;;;_' are outline topic headers.
76 ;; Just `ESC-x eval-buffer' to give it a whirl.
78 ;; ken manheimer (ken dot manheimer at gmail dot com)
82 ;;;_* Dependency autoloads
85 ;; Most of the requires here are for stuff covered by autoloads, which
86 ;; byte-compiling doesn't trigger.
90 ;; `cl' is required for `assert'. `assert' is not covered by a standard
91 ;; autoload, but it is a macro, so that eval-when-compile is sufficient
92 ;; to byte-compile it in, or to do the require when the buffer evalled.
96 ;;;_* USER CUSTOMIZATION VARIABLES:
98 ;;;_ > defgroup allout, allout-keybindings
100 "Extensive outline mode for use alone and with other modes."
103 (defgroup allout-keybindings nil
104 "Allout outline mode keyboard bindings configuration."
107 ;;;_ + Layout, Mode, and Topic Header Configuration
109 (defvar allout-command-prefix
) ; defined below
111 ;;;_ > allout-keybindings incidentals:
112 ;;;_ : internal key binding stuff - in this section for load-order.
113 ;;;_ = allout-mode-map
114 (defvar allout-mode-map
'allout-mode-map
115 "Keybindings place-holder for (allout) outline minor mode.
117 Do NOT set the value of this variable. Instead, customize
118 `allout-command-prefix', `allout-prefixed-keybindings', and
119 `allout-unprefixed-keybindings'.")
120 ;;;_ = allout-mode-map-value
121 (defvar allout-mode-map-value nil
122 "Keymap for allout outline minor mode.
124 Do NOT set the value of this variable. Instead, customize
125 `allout-command-prefix', `allout-prefixed-keybindings', and
126 `allout-unprefixed-keybindings'.")
127 ;;;_ = make allout-mode-map-value an alias for allout-mode-map:
128 ;; this needs to be revised when the value is changed, sigh.
129 (defalias 'allout-mode-map allout-mode-map-value
)
130 ;;;_ > allout-compose-and-institute-keymap (&optional varname value)
131 (defun allout-compose-and-institute-keymap (&optional varname value
)
132 "Create the allout keymap according to the keybinding specs, and set it.
134 Useful standalone or to effect customizations of the
135 respective allout-mode keybinding variables, `allout-command-prefix',
136 `allout-prefixed-keybindings', and `allout-unprefixed-keybindings'"
137 ;; Set the customization variable, if any:
139 (set-default varname value
))
140 (let ((map (make-sparse-keymap)))
141 (when (boundp 'allout-prefixed-keybindings
)
142 ;; tolerate first definitions of the variables:
143 (dolist (entry allout-prefixed-keybindings
)
145 ;; XXX vector vs non-vector key descriptions?
146 (vconcat allout-command-prefix
147 (car (read-from-string (car entry
))))
149 (when (boundp 'allout-unprefixed-keybindings
)
150 (dolist (entry allout-unprefixed-keybindings
)
151 (define-key map
(car (read-from-string (car entry
))) (cadr entry
))))
152 (substitute-key-definition 'beginning-of-line
'allout-beginning-of-line
154 (substitute-key-definition 'move-beginning-of-line
'allout-beginning-of-line
156 (substitute-key-definition 'end-of-line
'allout-end-of-line
158 (substitute-key-definition 'move-end-of-line
'allout-end-of-line
160 (allout-institute-keymap map
)))
161 ;;;_ > allout-institute-keymap (map)
162 (defun allout-institute-keymap (map)
163 "Associate allout-mode bindings with allout as a minor mode."
165 ;; allout-mode-map var is a keymap by virtue of being a defalias for
166 ;; allout-mode-map-value, which has the actual keymap value.
167 ;; allout-mode-map's symbol value is just 'allout-mode-map, so it can be
168 ;; used in minor-mode-map-alist to indirect to the actual
169 ;; allout-mode-map-var value, which can be adjusted and reassigned.
171 ;; allout-mode-map-value for keymap reference in various places:
172 (setq allout-mode-map-value map
)
173 ;; the function value keymap of allout-mode-map is used in
174 ;; minor-mode-map-alist - update it:
175 (fset allout-mode-map allout-mode-map-value
))
176 ;;;_ * intialize the mode map:
177 ;; ensure that allout-mode-map has some setting even if allout-mode hasn't
179 (allout-compose-and-institute-keymap)
180 ;;;_ = allout-command-prefix
181 (defcustom allout-command-prefix
"\C-c "
182 "Key sequence to be used as prefix for outline mode command key bindings.
184 Default is '\C-c<space>'; just '\C-c' is more short-and-sweet, if you're
185 willing to let allout use a bunch of \C-c keybindings."
187 :group
'allout-keybindings
188 :set
'allout-compose-and-institute-keymap
)
189 ;;;_ = allout-keybindings-binding
190 (define-widget 'allout-keybindings-binding
'lazy
191 "Structure of allout keybindings customization items."
193 (list (string :tag
"Key" :value
"[(meta control shift ?f)]")
194 (function :tag
"Function name"
195 :value allout-forward-current-level
))))
196 ;;;_ = allout-prefixed-keybindings
197 (defcustom allout-prefixed-keybindings
198 '(("[(control ?n)]" allout-next-visible-heading
)
199 ("[(control ?p)]" allout-previous-visible-heading
)
200 ("[(control ?u)]" allout-up-current-level
)
201 ("[(control ?f)]" allout-forward-current-level
)
202 ("[(control ?b)]" allout-backward-current-level
)
203 ("[(control ?a)]" allout-beginning-of-current-entry
)
204 ("[(control ?e)]" allout-end-of-entry
)
205 ("[(control ?i)]" allout-show-children
)
206 ("[(control ?s)]" allout-show-current-subtree
)
207 ("[(control ?t)]" allout-toggle-current-subtree-exposure
)
208 ;; Let user customize if they want to preempt describe-prefix-bindings ^h use.
209 ;; ("[(control ?h)]" allout-hide-current-subtree)
210 ("[?h]" allout-hide-current-subtree
)
211 ("[(control ?o)]" allout-show-current-entry
)
212 ("[?!]" allout-show-all
)
213 ("[?x]" allout-toggle-current-subtree-encryption
)
214 ("[? ]" allout-open-sibtopic
)
215 ("[?.]" allout-open-subtopic
)
216 ("[?,]" allout-open-supertopic
)
217 ("[?']" allout-shift-in
)
218 ("[?>]" allout-shift-in
)
219 ("[?<]" allout-shift-out
)
220 ("[(control ?m)]" allout-rebullet-topic
)
221 ("[?*]" allout-rebullet-current-heading
)
222 ("[?#]" allout-number-siblings
)
223 ("[(control ?k)]" allout-kill-topic
)
224 ("[(meta ?k)]" allout-copy-topic-as-kill
)
225 ("[?@]" allout-resolve-xref
)
226 ("[?=?c]" allout-copy-exposed-to-buffer
)
227 ("[?=?i]" allout-indented-exposed-to-buffer
)
228 ("[?=?t]" allout-latexify-exposed
)
229 ("[?=?p]" allout-flatten-exposed-to-buffer
)
231 "Allout-mode key bindings that are prefixed with `allout-command-prefix'.
233 See `allout-unprefixed-keybindings' for the list of keybindings
234 that are not prefixed.
236 Use vector format for the keys:
237 - put literal keys after a '?' question mark, eg: '?a', '?.'
238 - enclose control, shift, or meta-modified keys as sequences within
239 parentheses, with the literal key, as above, preceded by the name(s)
240 of the modifers, eg: [(control ?a)]
241 See the existing keys for examples.
243 Functions can be bound to multiple keys, but binding keys to
244 multiple functions will not work - the last binding for a key
246 :type
'allout-keybindings-binding
247 :group
'allout-keybindings
248 :set
'allout-compose-and-institute-keymap
250 ;;;_ = allout-unprefixed-keybindings
251 (defcustom allout-unprefixed-keybindings
252 '(("[(control ?k)]" allout-kill-line
)
253 ("[(meta ?k)]" allout-copy-line-as-kill
)
254 ("[(control ?y)]" allout-yank
)
255 ("[(meta ?y)]" allout-yank-pop
)
257 "Allout-mode functions bound to keys without any added prefix.
259 This is in contrast to the majority of allout-mode bindings on
260 `allout-prefixed-bindings', whose bindings are created with a
261 preceeding command key.
263 Use vector format for the keys:
264 - put literal keys after a '?' question mark, eg: '?a', '?.'
265 - enclose control, shift, or meta-modified keys as sequences within
266 parentheses, with the literal key, as above, preceded by the name(s)
267 of the modifers, eg: [(control ?a)]
268 See the existing keys for examples."
269 :type
'allout-keybindings-binding
270 :group
'allout-keybindings
271 :set
'allout-compose-and-institute-keymap
274 ;;;_ = allout-auto-activation
275 (defcustom allout-auto-activation nil
276 "Regulates auto-activation modality of allout outlines -- see `allout-init'.
278 Setq-default by `allout-init' to regulate whether or not allout
279 outline mode is automatically activated when the buffer-specific
280 variable `allout-layout' is non-nil, and whether or not the layout
281 dictated by `allout-layout' should be imposed on mode activation.
283 With value t, auto-mode-activation and auto-layout are enabled.
284 \(This also depends on `allout-find-file-hook' being installed in
285 `find-file-hook', which is also done by `allout-init'.)
287 With value `ask', auto-mode-activation is enabled, and endorsement for
288 performing auto-layout is asked of the user each time.
290 With value `activate', only auto-mode-activation is enabled,
293 With value nil, neither auto-mode-activation nor auto-layout are
296 See the docstring for `allout-init' for the proper interface to
298 :type
'(choice (const :tag
"On" t
)
299 (const :tag
"Ask about layout" "ask")
300 (const :tag
"Mode only" "activate")
301 (const :tag
"Off" nil
))
303 ;;;_ = allout-default-layout
304 (defcustom allout-default-layout
'(-2 : 0)
305 "Default allout outline layout specification.
307 This setting specifies the outline exposure to use when
308 `allout-layout' has the local value `t'. This docstring describes the
309 layout specifications.
311 A list value specifies a default layout for the current buffer,
312 to be applied upon activation of `allout-mode'. Any non-nil
313 value will automatically trigger `allout-mode', provided
314 `allout-init' has been called to enable this behavior.
316 The types of elements in the layout specification are:
318 INTEGER -- dictate the relative depth to open the corresponding topic(s),
320 -- negative numbers force the topic to be closed before opening
321 to the absolute value of the number, so all siblings are open
323 -- positive numbers open to the relative depth indicated by the
324 number, but do not force already opened subtopics to be closed.
325 -- 0 means to close topic -- hide all subitems.
326 : -- repeat spec -- apply the preceeding element to all siblings at
327 current level, *up to* those siblings that would be covered by specs
328 following the `:' on the list. Ie, apply to all topics at level but
329 trailing ones accounted for by trailing specs. (Only the first of
330 multiple colons at the same level is honored -- later ones are ignored.)
331 * -- completely exposes the topic, including bodies
332 + -- exposes all subtopics, but not the bodies
333 - -- exposes the body of the corresponding topic, but not subtopics
334 LIST -- a nested layout spec, to be applied intricately to its
335 corresponding item(s)
339 Collapse the top-level topics to show their children and
340 grandchildren, but completely collapse the final top-level topic.
342 Close the first topic so only the immediate subtopics are shown,
343 leave the subsequent topics exposed as they are until the second
344 second to last topic, which is exposed at least one level, and
345 completely close the last topic.
347 Expose children and grandchildren of all topics at current
348 level except the last two; expose children of the second to
349 last and completely expose the last one, including its subtopics.
351 See `allout-expose-topic' for more about the exposure process.
353 Also, allout's mode-specific provisions will make topic prefixes default
354 to the comment-start string, if any, of the language of the file. This
355 is modulo the setting of `allout-use-mode-specific-leader', which see."
356 :type
'allout-layout-type
358 ;;;_ : allout-layout-type
359 (define-widget 'allout-layout-type
'lazy
360 "Allout layout format customization basic building blocks."
362 (choice (integer :tag
"integer (<= zero is strict)")
363 (const :tag
": (repeat prior)" :)
364 (const :tag
"* (completely expose)" *)
365 (const :tag
"+ (expose all offspring, headlines only)" +)
366 (const :tag
"- (expose topic body but not offspring)" -
)
367 (allout-layout-type :tag
"<Nested layout>"))))
369 ;;;_ = allout-inhibit-auto-fill
370 (defcustom allout-inhibit-auto-fill nil
371 "If non-nil, auto-fill will be inhibited in the allout buffers.
373 You can customize this setting to set it for all allout buffers, or set it
374 in individual buffers if you want to inhibit auto-fill only in particular
375 buffers. (You could use a function on `allout-mode-hook' to inhibit
376 auto-fill according, eg, to the major mode.)
378 If you don't set this and auto-fill-mode is enabled, allout will use the
379 value that `normal-auto-fill-function', if any, when allout mode starts, or
380 else allout's special hanging-indent maintaining auto-fill function,
384 (make-variable-buffer-local 'allout-inhibit-auto-fill
)
385 ;;;_ = allout-use-hanging-indents
386 (defcustom allout-use-hanging-indents t
387 "If non-nil, topic body text auto-indent defaults to indent of the header.
388 Ie, it is indented to be just past the header prefix. This is
389 relevant mostly for use with `indented-text-mode', or other situations
390 where auto-fill occurs."
393 (make-variable-buffer-local 'allout-use-hanging-indents
)
395 (put 'allout-use-hanging-indents
'safe-local-variable
396 (if (fboundp 'booleanp
) 'booleanp
'(lambda (x) (member x
'(t nil
)))))
397 ;;;_ = allout-reindent-bodies
398 (defcustom allout-reindent-bodies
(if allout-use-hanging-indents
400 "Non-nil enables auto-adjust of topic body hanging indent with depth shifts.
402 When active, topic body lines that are indented even with or beyond
403 their topic header are reindented to correspond with depth shifts of
406 A value of t enables reindent in non-programming-code buffers, ie
407 those that do not have the variable `comment-start' set. A value of
408 `force' enables reindent whether or not `comment-start' is set."
409 :type
'(choice (const nil
) (const t
) (const text
) (const force
))
412 (make-variable-buffer-local 'allout-reindent-bodies
)
414 (put 'allout-reindent-bodies
'safe-local-variable
415 '(lambda (x) (memq x
'(nil t text force
))))
417 ;;;_ = allout-show-bodies
418 (defcustom allout-show-bodies nil
419 "If non-nil, show entire body when exposing a topic, rather than
423 (make-variable-buffer-local 'allout-show-bodies
)
425 (put 'allout-show-bodies
'safe-local-variable
426 (if (fboundp 'booleanp
) 'booleanp
'(lambda (x) (member x
'(t nil
)))))
428 ;;;_ = allout-beginning-of-line-cycles
429 (defcustom allout-beginning-of-line-cycles t
430 "If non-nil, \\[allout-beginning-of-line] will cycle through smart-placement options.
432 Cycling only happens on when the command is repeated, not when it
433 follows a different command.
435 Smart-placement means that repeated calls to this function will
438 - if the cursor is on a non-headline body line and not on the first column:
439 then it goes to the first column
440 - if the cursor is on the first column of a non-headline body line:
441 then it goes to the start of the headline within the item body
442 - if the cursor is on the headline and not the start of the headline:
443 then it goes to the start of the headline
444 - if the cursor is on the start of the headline:
445 then it goes to the bullet character (for hotspot navigation)
446 - if the cursor is on the bullet character:
447 then it goes to the first column of that line (the headline)
448 - if the cursor is on the first column of the headline:
449 then it goes to the start of the headline within the item body.
451 In this fashion, you can use the beginning-of-line command to do
452 its normal job and then, when repeated, advance through the
453 entry, cycling back to start.
455 If this configuration variable is nil, then the cursor is just
456 advanced to the beginning of the line and remains there on
458 :type
'boolean
:group
'allout
)
459 ;;;_ = allout-end-of-line-cycles
460 (defcustom allout-end-of-line-cycles t
461 "If non-nil, \\[allout-end-of-line] will cycle through smart-placement options.
463 Cycling only happens on when the command is repeated, not when it
464 follows a different command.
466 Smart placement means that repeated calls to this function will
469 - if the cursor is not on the end-of-line,
470 then it goes to the end-of-line
471 - if the cursor is on the end-of-line but not the end-of-entry,
472 then it goes to the end-of-entry, exposing it if necessary
473 - if the cursor is on the end-of-entry,
474 then it goes to the end of the head line
476 In this fashion, you can use the end-of-line command to do its
477 normal job and then, when repeated, advance through the entry,
478 cycling back to start.
480 If this configuration variable is nil, then the cursor is just
481 advanced to the end of the line and remains there on repeated
483 :type
'boolean
:group
'allout
)
485 ;;;_ = allout-header-prefix
486 (defcustom allout-header-prefix
"."
487 ;; this string is treated as literal match. it will be `regexp-quote'd, so
488 ;; one cannot use regular expressions to match varying header prefixes.
489 "Leading string which helps distinguish topic headers.
491 Outline topic header lines are identified by a leading topic
492 header prefix, which mostly have the value of this var at their front.
493 Level 1 topics are exceptions. They consist of only a single
494 character, which is typically set to the `allout-primary-bullet'."
497 (make-variable-buffer-local 'allout-header-prefix
)
499 (put 'allout-header-prefix
'safe-local-variable
'stringp
)
500 ;;;_ = allout-primary-bullet
501 (defcustom allout-primary-bullet
"*"
502 "Bullet used for top-level outline topics.
504 Outline topic header lines are identified by a leading topic header
505 prefix, which is concluded by bullets that includes the value of this
506 var and the respective allout-*-bullets-string vars.
508 The value of an asterisk (`*') provides for backwards compatibility
509 with the original Emacs outline mode. See `allout-plain-bullets-string'
510 and `allout-distinctive-bullets-string' for the range of available
514 (make-variable-buffer-local 'allout-primary-bullet
)
516 (put 'allout-primary-bullet
'safe-local-variable
'stringp
)
517 ;;;_ = allout-plain-bullets-string
518 (defcustom allout-plain-bullets-string
".,"
519 "The bullets normally used in outline topic prefixes.
521 See `allout-distinctive-bullets-string' for the other kind of
524 DO NOT include the close-square-bracket, `]', as a bullet.
526 Outline mode has to be reactivated in order for changes to the value
527 of this var to take effect."
530 (make-variable-buffer-local 'allout-plain-bullets-string
)
532 (put 'allout-plain-bullets-string
'safe-local-variable
'stringp
)
533 ;;;_ = allout-distinctive-bullets-string
534 (defcustom allout-distinctive-bullets-string
"*+-=>()[{}&!?#%\"X@$~_\\:;^"
535 "Persistent outline header bullets used to distinguish special topics.
537 These bullets are distinguish topics with particular character.
538 They are not used by default in the topic creation routines, but
539 are offered as options when you modify topic creation with a
540 universal argument \(\\[universal-argument]), or during rebulleting \(\\[allout-rebullet-current-heading]).
542 Distinctive bullets are not cycled when topics are shifted or
543 otherwise automatically rebulleted, so their marking is
544 persistent until deliberately changed. Their significance is
545 purely by convention, however. Some conventions suggest
548 `(' - open paren -- an aside or incidental point
549 `?' - question mark -- uncertain or outright question
550 `!' - exclamation point/bang -- emphatic
551 `[' - open square bracket -- meta-note, about item instead of item's subject
552 `\"' - double quote -- a quotation or other citation
553 `=' - equal sign -- an assignment, some kind of definition
554 `^' - carat -- relates to something above
556 Some are more elusive, but their rationale may be recognizable:
558 `+' - plus -- pending consideration, completion
559 `_' - underscore -- done, completed
560 `&' - ampersand -- addendum, furthermore
562 \(Some other non-plain bullets have special meaning to the
563 software. By default:
565 `~' marks encryptable topics -- see `allout-topic-encryption-bullet'
566 `#' marks auto-numbered bullets -- see `allout-numbered-bullet'.)
568 See `allout-plain-bullets-string' for the standard, alternating
571 You must run `set-allout-regexp' in order for outline mode to
572 adopt changes of this value.
574 DO NOT include the close-square-bracket, `]', on either of the bullet
578 (make-variable-buffer-local 'allout-distinctive-bullets-string
)
580 (put 'allout-distinctive-bullets-string
'safe-local-variable
'stringp
)
582 ;;;_ = allout-use-mode-specific-leader
583 (defcustom allout-use-mode-specific-leader t
584 "When non-nil, use mode-specific topic-header prefixes.
586 Allout outline mode will use the mode-specific `allout-mode-leaders' or
587 comment-start string, if any, to lead the topic prefix string, so topic
588 headers look like comments in the programming language. It will also use
589 the comment-start string, with an '_' appended, for `allout-primary-bullet'.
591 String values are used as literals, not regular expressions, so
592 do not escape any regulare-expression characters.
594 Value t means to first check for assoc value in `allout-mode-leaders'
595 alist, then use comment-start string, if any, then use default (`.').
596 \(See note about use of comment-start strings, below.)
598 Set to the symbol for either of `allout-mode-leaders' or
599 `comment-start' to use only one of them, respectively.
601 Value nil means to always use the default (`.') and leave
602 `allout-primary-bullet' unaltered.
604 comment-start strings that do not end in spaces are tripled in
605 the header-prefix, and an `_' underscore is tacked on the end, to
606 distinguish them from regular comment strings. comment-start
607 strings that do end in spaces are not tripled, but an underscore
608 is substituted for the space. [This presumes that the space is
609 for appearance, not comment syntax. You can use
610 `allout-mode-leaders' to override this behavior, when
612 :type
'(choice (const t
) (const nil
) string
613 (const allout-mode-leaders
)
614 (const comment-start
))
617 (put 'allout-use-mode-specific-leader
'safe-local-variable
618 '(lambda (x) (or (memq x
'(t nil allout-mode-leaders comment-start
))
620 ;;;_ = allout-mode-leaders
621 (defvar allout-mode-leaders
'()
622 "Specific allout-prefix leading strings per major modes.
624 Use this if the mode's comment-start string isn't what you
625 prefer, or if the mode lacks a comment-start string. See
626 `allout-use-mode-specific-leader' for more details.
628 If you're constructing a string that will comment-out outline
629 structuring so it can be included in program code, append an extra
630 character, like an \"_\" underscore, to distinguish the lead string
631 from regular comments that start at the beginning-of-line.")
633 ;;;_ = allout-old-style-prefixes
634 (defcustom allout-old-style-prefixes nil
635 "When non-nil, use only old-and-crusty `outline-mode' `*' topic prefixes.
637 Non-nil restricts the topic creation and modification
638 functions to asterix-padded prefixes, so they look exactly
639 like the original Emacs-outline style prefixes.
641 Whatever the setting of this variable, both old and new style prefixes
642 are always respected by the topic maneuvering functions."
645 (make-variable-buffer-local 'allout-old-style-prefixes
)
647 (put 'allout-old-style-prefixes
'safe-local-variable
648 (if (fboundp 'booleanp
) 'booleanp
'(lambda (x) (member x
'(t nil
)))))
649 ;;;_ = allout-stylish-prefixes -- alternating bullets
650 (defcustom allout-stylish-prefixes t
651 "Do fancy stuff with topic prefix bullets according to level, etc.
653 Non-nil enables topic creation, modification, and repositioning
654 functions to vary the topic bullet char (the char that marks the topic
655 depth) just preceding the start of the topic text) according to level.
656 Otherwise, only asterisks (`*') and distinctive bullets are used.
658 This is how an outline can look (but sans indentation) with stylish
663 . + One level 3 subtopic
664 . . One level 4 subtopic
665 . . A second 4 subtopic
666 . + Another level 3 subtopic
667 . #1 A numbered level 4 subtopic
669 . ! Another level 4 subtopic with a different distinctive bullet
670 . #4 And another numbered level 4 subtopic
672 This would be an outline with stylish prefixes inhibited (but the
673 numbered and other distinctive bullets retained):
677 . * One level 3 subtopic
678 . * One level 4 subtopic
679 . * A second 4 subtopic
680 . * Another level 3 subtopic
681 . #1 A numbered level 4 subtopic
683 . ! Another level 4 subtopic with a different distinctive bullet
684 . #4 And another numbered level 4 subtopic
686 Stylish and constant prefixes (as well as old-style prefixes) are
687 always respected by the topic maneuvering functions, regardless of
688 this variable setting.
690 The setting of this var is not relevant when `allout-old-style-prefixes'
694 (make-variable-buffer-local 'allout-stylish-prefixes
)
696 (put 'allout-stylish-prefixes
'safe-local-variable
697 (if (fboundp 'booleanp
) 'booleanp
'(lambda (x) (member x
'(t nil
)))))
699 ;;;_ = allout-numbered-bullet
700 (defcustom allout-numbered-bullet
"#"
701 "String designating bullet of topics that have auto-numbering; nil for none.
703 Topics having this bullet have automatic maintenance of a sibling
704 sequence-number tacked on, just after the bullet. Conventionally set
705 to \"#\", you can set it to a bullet of your choice. A nil value
706 disables numbering maintenance."
707 :type
'(choice (const nil
) string
)
709 (make-variable-buffer-local 'allout-numbered-bullet
)
711 (put 'allout-numbered-bullet
'safe-local-variable
712 (if (fboundp 'string-or-null-p
)
714 '(lambda (x) (or (stringp x
) (null x
)))))
715 ;;;_ = allout-file-xref-bullet
716 (defcustom allout-file-xref-bullet
"@"
717 "Bullet signifying file cross-references, for `allout-resolve-xref'.
719 Set this var to the bullet you want to use for file cross-references."
720 :type
'(choice (const nil
) string
)
723 (put 'allout-file-xref-bullet
'safe-local-variable
724 (if (fboundp 'string-or-null-p
)
726 '(lambda (x) (or (stringp x
) (null x
)))))
727 ;;;_ = allout-presentation-padding
728 (defcustom allout-presentation-padding
2
729 "Presentation-format white-space padding factor, for greater indent."
733 (make-variable-buffer-local 'allout-presentation-padding
)
735 (put 'allout-presentation-padding
'safe-local-variable
'integerp
)
737 ;;;_ = allout-abbreviate-flattened-numbering
738 (defcustom allout-abbreviate-flattened-numbering nil
739 "If non-nil, `allout-flatten-exposed-to-buffer' abbreviates topic
740 numbers to minimal amount with some context. Otherwise, entire
741 numbers are always used."
745 ;;;_ + LaTeX formatting
746 ;;;_ - allout-number-pages
747 (defcustom allout-number-pages nil
748 "Non-nil turns on page numbering for LaTeX formatting of an outline."
751 ;;;_ - allout-label-style
752 (defcustom allout-label-style
"\\large\\bf"
753 "Font and size of labels for LaTeX formatting of an outline."
756 ;;;_ - allout-head-line-style
757 (defcustom allout-head-line-style
"\\large\\sl "
758 "Font and size of entries for LaTeX formatting of an outline."
761 ;;;_ - allout-body-line-style
762 (defcustom allout-body-line-style
" "
763 "Font and size of entries for LaTeX formatting of an outline."
766 ;;;_ - allout-title-style
767 (defcustom allout-title-style
"\\Large\\bf"
768 "Font and size of titles for LaTeX formatting of an outline."
772 (defcustom allout-title
'(or buffer-file-name
(buffer-name))
773 "Expression to be evaluated to determine the title for LaTeX
777 ;;;_ - allout-line-skip
778 (defcustom allout-line-skip
".05cm"
779 "Space between lines for LaTeX formatting of an outline."
783 (defcustom allout-indent
".3cm"
784 "LaTeX formatted depth-indent spacing."
788 ;;;_ + Topic encryption
789 ;;;_ = allout-encryption group
790 (defgroup allout-encryption nil
791 "Settings for topic encryption features of allout outliner."
793 ;;;_ = allout-topic-encryption-bullet
794 (defcustom allout-topic-encryption-bullet
"~"
795 "Bullet signifying encryption of the entry's body."
796 :type
'(choice (const nil
) string
)
798 :group
'allout-encryption
)
799 ;;;_ = allout-encrypt-unencrypted-on-saves
800 (defcustom allout-encrypt-unencrypted-on-saves t
801 "When saving, should topics pending encryption be encrypted?
803 The idea is to prevent file-system exposure of any un-encrypted stuff, and
804 mostly covers both deliberate file writes and auto-saves.
806 - Yes: encrypt all topics pending encryption, even if it's the one
807 currently being edited. (In that case, the currently edited topic
808 will be automatically decrypted before any user interaction, so they
809 can continue editing but the copy on the file system will be
811 Auto-saves will use the \"All except current topic\" mode if this
812 one is selected, to avoid practical difficulties -- see below.
813 - All except current topic: skip the topic currently being edited, even if
814 it's pending encryption. This may expose the current topic on the
815 file sytem, but avoids the nuisance of prompts for the encryption
816 passphrase in the middle of editing for, eg, autosaves.
817 This mode is used for auto-saves for both this option and \"Yes\".
818 - No: leave it to the user to encrypt any unencrypted topics.
820 For practical reasons, auto-saves always use the 'except-current policy
821 when auto-encryption is enabled. (Otherwise, spurious passphrase prompts
822 and unavoidable timing collisions are too disruptive.) If security for a
823 file requires that even the current topic is never auto-saved in the clear,
824 disable auto-saves for that file."
826 :type
'(choice (const :tag
"Yes" t
)
827 (const :tag
"All except current topic" except-current
)
828 (const :tag
"No" nil
))
830 :group
'allout-encryption
)
831 (make-variable-buffer-local 'allout-encrypt-unencrypted-on-saves
)
834 ;;;_ = allout-developer group
835 (defgroup allout-developer nil
836 "Allout settings developers care about, including topic encryption and more."
838 ;;;_ = allout-run-unit-tests-on-load
839 (defcustom allout-run-unit-tests-on-load nil
840 "When non-nil, unit tests will be run at end of loading the allout module.
842 Generally, allout code developers are the only ones who'll want to set this.
844 \(If set, this makes it an even better practice to exercise changes by
845 doing byte-compilation with a repeat count, so the file is loaded after
848 See `allout-run-unit-tests' to see what's run."
850 :group
'allout-developer
)
852 ;;;_ + Miscellaneous customization
854 ;;;_ = allout-enable-file-variable-adjustment
855 (defcustom allout-enable-file-variable-adjustment t
856 "If non-nil, some allout outline actions edit Emacs local file var text.
858 This can range from changes to existing entries, addition of new ones,
859 and creation of a new local variables section when necessary.
861 Emacs file variables adjustments are also inhibited if `enable-local-variables'
864 Operations potentially causing edits include allout encryption routines.
865 For details, see `allout-toggle-current-subtree-encryption's docstring."
868 (make-variable-buffer-local 'allout-enable-file-variable-adjustment
)
870 ;;;_* CODE -- no user customizations below.
872 ;;;_ #1 Internal Outline Formatting and Configuration
874 ;;;_ = allout-version
875 (defvar allout-version
"2.3"
876 "Version of currently loaded outline package. (allout.el)")
877 ;;;_ > allout-version
878 (defun allout-version (&optional here
)
879 "Return string describing the loaded outline version."
881 (let ((msg (concat "Allout Outline Mode v " allout-version
)))
882 (if here
(insert msg
))
885 ;;;_ : Mode activation (defined here because it's referenced early)
887 (defvar allout-mode nil
"Allout outline mode minor-mode flag.")
888 (make-variable-buffer-local 'allout-mode
)
889 ;;;_ = allout-layout nil
890 (defvar allout-layout nil
; LEAVE GLOBAL VALUE NIL -- see docstring.
891 "Buffer-specific setting for allout layout.
893 In buffers where this is non-nil (and if `allout-init' has been run, to
894 enable this behavior), `allout-mode' will be automatically activated. The
895 layout dictated by the value will be used to set the initial exposure when
896 `allout-mode' is activated.
898 \*You should not setq-default this variable non-nil unless you want every
899 visited file to be treated as an allout file.*
901 The value would typically be set by a file local variable. For
902 example, the following lines at the bottom of an Emacs Lisp file:
905 ;;;allout-layout: (0 : -1 -1 0)
908 dictate activation of `allout-mode' mode when the file is visited
909 \(presuming allout-init was already run), followed by the
910 equivalent of `(allout-expose-topic 0 : -1 -1 0)'. (This is
911 the layout used for the allout.el source file.)
913 `allout-default-layout' describes the specification format.
914 `allout-layout' can additionally have the value `t', in which
915 case the value of `allout-default-layout' is used.")
916 (make-variable-buffer-local 'allout-layout
)
918 (put 'allout-layout
'safe-local-variable
919 '(lambda (x) (or (numberp x
) (listp x
) (memq x
'(: * + -
)))))
921 ;;;_ : Topic header format
923 (defvar allout-regexp
""
924 "*Regular expression to match the beginning of a heading line.
926 Any line whose beginning matches this regexp is considered a
927 heading. This var is set according to the user configuration vars
928 by `set-allout-regexp'.")
929 (make-variable-buffer-local 'allout-regexp
)
930 ;;;_ = allout-bullets-string
931 (defvar allout-bullets-string
""
932 "A string dictating the valid set of outline topic bullets.
934 This var should *not* be set by the user -- it is set by `set-allout-regexp',
935 and is produced from the elements of `allout-plain-bullets-string'
936 and `allout-distinctive-bullets-string'.")
937 (make-variable-buffer-local 'allout-bullets-string
)
938 ;;;_ = allout-bullets-string-len
939 (defvar allout-bullets-string-len
0
940 "Length of current buffers' `allout-plain-bullets-string'.")
941 (make-variable-buffer-local 'allout-bullets-string-len
)
942 ;;;_ = allout-depth-specific-regexp
943 (defvar allout-depth-specific-regexp
""
944 "*Regular expression to match a heading line prefix for a particular depth.
946 This expression is used to search for depth-specific topic
947 headers at depth 2 and greater. Use `allout-depth-one-regexp'
948 for to seek topics at depth one.
950 This var is set according to the user configuration vars by
951 `set-allout-regexp'. It is prepared with format strings for two
952 decimal numbers, which should each be one less than the depth of the
953 topic prefix to be matched.")
954 (make-variable-buffer-local 'allout-depth-specific-regexp
)
955 ;;;_ = allout-depth-one-regexp
956 (defvar allout-depth-one-regexp
""
957 "*Regular expression to match a heading line prefix for depth one.
959 This var is set according to the user configuration vars by
960 `set-allout-regexp'. It is prepared with format strings for two
961 decimal numbers, which should each be one less than the depth of the
962 topic prefix to be matched.")
963 (make-variable-buffer-local 'allout-depth-one-regexp
)
964 ;;;_ = allout-line-boundary-regexp
965 (defvar allout-line-boundary-regexp
()
966 "`allout-regexp' prepended with a newline for the search target.
968 This is properly set by `set-allout-regexp'.")
969 (make-variable-buffer-local 'allout-line-boundary-regexp
)
970 ;;;_ = allout-bob-regexp
971 (defvar allout-bob-regexp
()
972 "Like `allout-line-boundary-regexp', for headers at beginning of buffer.")
973 (make-variable-buffer-local 'allout-bob-regexp
)
974 ;;;_ = allout-header-subtraction
975 (defvar allout-header-subtraction
(1- (length allout-header-prefix
))
976 "Allout-header prefix length to subtract when computing topic depth.")
977 (make-variable-buffer-local 'allout-header-subtraction
)
978 ;;;_ = allout-plain-bullets-string-len
979 (defvar allout-plain-bullets-string-len
(length allout-plain-bullets-string
)
980 "Length of `allout-plain-bullets-string', updated by `set-allout-regexp'.")
981 (make-variable-buffer-local 'allout-plain-bullets-string-len
)
983 ;;;_ = allout-doublecheck-at-and-shallower
984 (defconst allout-doublecheck-at-and-shallower
3
985 "Validate apparent topics of this depth and shallower as being non-aberrant.
987 Verified with `allout-aberrant-container-p'. The usefulness of
988 this check is limited to shallow depths, because the
989 determination of aberrance is according to the mistaken item
990 being followed by a legitimate item of excessively greater depth.
992 The classic example of a mistaken item, for a standard allout
993 outline configuration, is a body line that begins with an '...'
994 ellipsis. This happens to contain a legitimate depth-2 header
995 prefix, constituted by two '..' dots at the beginning of the
996 line. The only thing that can distinguish it *in principle* from
997 a legitimate one is if the following real header is at a depth
998 that is discontinuous from the depth of 2 implied by the
999 ellipsis, ie depth 4 or more. As the depth being tested gets
1000 greater, the likelihood of this kind of disqualification is
1001 lower, and the usefulness of this test is lower.
1003 Extending the depth of the doublecheck increases the amount it is
1004 applied, increasing the cost of the test - on casual estimation,
1005 for outlines with many deep topics, geometrically (O(n)?).
1006 Taken together with decreasing likelihood that the test will be
1007 useful at greater depths, more modest doublecheck limits are more
1008 suitably economical.")
1009 ;;;_ X allout-reset-header-lead (header-lead)
1010 (defun allout-reset-header-lead (header-lead)
1011 "Reset the leading string used to identify topic headers."
1012 (interactive "sNew lead string: ")
1013 (setq allout-header-prefix header-lead
)
1014 (setq allout-header-subtraction
(1- (length allout-header-prefix
)))
1015 (set-allout-regexp))
1016 ;;;_ X allout-lead-with-comment-string (header-lead)
1017 (defun allout-lead-with-comment-string (&optional header-lead
)
1018 "Set the topic-header leading string to specified string.
1020 Useful when for encapsulating outline structure in programming
1021 language comments. Returns the leading string."
1024 (if (not (stringp header-lead
))
1025 (setq header-lead
(read-string
1026 "String prefix for topic headers: ")))
1027 (setq allout-reindent-bodies nil
)
1028 (allout-reset-header-lead header-lead
)
1030 ;;;_ > allout-infer-header-lead-and-primary-bullet ()
1031 (defun allout-infer-header-lead-and-primary-bullet ()
1032 "Determine appropriate `allout-header-prefix' and `allout-primary-bullet'.
1034 Works according to settings of:
1037 `allout-header-prefix' (default)
1038 `allout-use-mode-specific-leader'
1039 and `allout-mode-leaders'.
1041 Apply this via (re)activation of `allout-mode', rather than
1042 invoking it directly."
1043 (let* ((use-leader (and (boundp 'allout-use-mode-specific-leader
)
1044 (if (or (stringp allout-use-mode-specific-leader
)
1045 (memq allout-use-mode-specific-leader
1046 '(allout-mode-leaders
1049 allout-use-mode-specific-leader
1050 ;; Oops -- garbled value, equate with effect of t:
1054 ((not use-leader
) nil
)
1055 ;; Use the explicitly designated leader:
1056 ((stringp use-leader
) use-leader
)
1057 (t (or (and (memq use-leader
'(t allout-mode-leaders
))
1058 ;; Get it from outline mode leaders?
1059 (cdr (assq major-mode allout-mode-leaders
)))
1060 ;; ... didn't get from allout-mode-leaders...
1061 (and (memq use-leader
'(t comment-start
))
1063 ;; Use comment-start, maybe tripled, and with
1067 (substring comment-start
1068 (1- (length comment-start
))))
1069 ;; Use comment-start, sans trailing space:
1070 (substring comment-start
0 -
1)
1071 (concat comment-start comment-start comment-start
))
1072 ;; ... and append underscore, whichever:
1076 (setq allout-header-prefix leader
)
1077 (if (not allout-old-style-prefixes
)
1078 ;; setting allout-primary-bullet makes the top level topics use --
1079 ;; actually, be -- the special prefix:
1080 (setq allout-primary-bullet leader
))
1081 allout-header-prefix
)))
1082 (defalias 'allout-infer-header-lead
1083 'allout-infer-header-lead-and-primary-bullet
)
1084 ;;;_ > allout-infer-body-reindent ()
1085 (defun allout-infer-body-reindent ()
1086 "Determine proper setting for `allout-reindent-bodies'.
1088 Depends on default setting of `allout-reindent-bodies' (which see)
1089 and presence of setting for `comment-start', to tell whether the
1090 file is programming code."
1091 (if (and allout-reindent-bodies
1093 (not (eq 'force allout-reindent-bodies
)))
1094 (setq allout-reindent-bodies nil
)))
1095 ;;;_ > set-allout-regexp ()
1096 (defun set-allout-regexp ()
1097 "Generate proper topic-header regexp form for outline functions.
1099 Works with respect to `allout-plain-bullets-string' and
1100 `allout-distinctive-bullets-string'.
1102 Also refresh various data structures that hinge on the regexp."
1105 ;; Derive allout-bullets-string from user configured components:
1106 (setq allout-bullets-string
"")
1107 (let ((strings (list 'allout-plain-bullets-string
1108 'allout-distinctive-bullets-string
1109 'allout-primary-bullet
))
1116 (setq cur-len
(length (setq cur-string
(symbol-value (car strings
)))))
1117 (while (< index cur-len
)
1118 (setq cur-char
(aref cur-string index
))
1119 (setq allout-bullets-string
1120 (concat allout-bullets-string
1122 ; Single dash would denote a
1123 ; sequence, repeated denotes
1125 ((eq cur-char ?-
) "--")
1126 ; literal close-square-bracket
1127 ; doesn't work right in the
1129 ((eq cur-char ?\
]) "")
1130 (t (regexp-quote (char-to-string cur-char
))))))
1131 (setq index
(1+ index
)))
1132 (setq strings
(cdr strings
)))
1134 ;; Derive next for repeated use in allout-pending-bullet:
1135 (setq allout-plain-bullets-string-len
(length allout-plain-bullets-string
))
1136 (setq allout-header-subtraction
(1- (length allout-header-prefix
)))
1138 (let (new-part old-part formfeed-part
)
1139 (setq new-part
(concat "\\("
1140 (regexp-quote allout-header-prefix
)
1142 ;; already regexp-quoted in a custom way:
1143 "[" allout-bullets-string
"]"
1145 old-part
(concat "\\("
1146 (regexp-quote allout-primary-bullet
)
1148 (regexp-quote allout-header-prefix
)
1151 " ?[^" allout-primary-bullet
"]")
1152 formfeed-part
"\\(\^L\\)"
1154 allout-regexp
(concat new-part
1160 allout-line-boundary-regexp
(concat "\n" new-part
1166 allout-bob-regexp
(concat "\\`" new-part
1173 (setq allout-depth-specific-regexp
1174 (concat "\\(^\\|\\`\\)"
1177 ;; new-style spacers-then-bullet string:
1179 (allout-format-quote (regexp-quote allout-header-prefix
))
1181 "[" (allout-format-quote allout-bullets-string
) "]"
1184 ;; old-style all-bullets string, if primary not multi-char:
1185 (if (< 0 allout-header-subtraction
)
1188 (allout-format-quote
1189 (regexp-quote allout-primary-bullet
))
1190 (allout-format-quote
1191 (regexp-quote allout-primary-bullet
))
1192 (allout-format-quote
1193 (regexp-quote allout-primary-bullet
))
1195 ;; disqualify greater depths:
1197 (allout-format-quote allout-primary-bullet
)
1202 (setq allout-depth-one-regexp
1203 (concat "\\(^\\|\\`\\)"
1207 (regexp-quote allout-header-prefix
)
1208 ;; disqualify any bullet char following any amount of
1209 ;; intervening whitespace:
1211 (concat "[^ " allout-bullets-string
"]")
1213 (if (< 0 allout-header-subtraction
)
1214 ;; Need not support anything like the old
1215 ;; bullet style if the prefix is multi-char.
1218 (regexp-quote allout-primary-bullet
)
1219 ;; disqualify deeper primary-bullet sequences:
1220 "[^" allout-primary-bullet
"]"))
1224 (defvar allout-mode-exposure-menu
)
1225 (defvar allout-mode-editing-menu
)
1226 (defvar allout-mode-navigation-menu
)
1227 (defvar allout-mode-misc-menu
)
1228 (defun produce-allout-mode-menubar-entries ()
1230 (easy-menu-define allout-mode-exposure-menu
1231 allout-mode-map-value
1232 "Allout outline exposure menu."
1234 ["Show Entry" allout-show-current-entry t
]
1235 ["Show Children" allout-show-children t
]
1236 ["Show Subtree" allout-show-current-subtree t
]
1237 ["Hide Subtree" allout-hide-current-subtree t
]
1238 ["Hide Leaves" allout-hide-current-leaves t
]
1240 ["Show All" allout-show-all t
]))
1241 (easy-menu-define allout-mode-editing-menu
1242 allout-mode-map-value
1243 "Allout outline editing menu."
1245 ["Open Sibling" allout-open-sibtopic t
]
1246 ["Open Subtopic" allout-open-subtopic t
]
1247 ["Open Supertopic" allout-open-supertopic t
]
1249 ["Shift Topic In" allout-shift-in t
]
1250 ["Shift Topic Out" allout-shift-out t
]
1251 ["Rebullet Topic" allout-rebullet-topic t
]
1252 ["Rebullet Heading" allout-rebullet-current-heading t
]
1253 ["Number Siblings" allout-number-siblings t
]
1255 ["Toggle Topic Encryption"
1256 allout-toggle-current-subtree-encryption
1257 (> (allout-current-depth) 1)]))
1258 (easy-menu-define allout-mode-navigation-menu
1259 allout-mode-map-value
1260 "Allout outline navigation menu."
1262 ["Next Visible Heading" allout-next-visible-heading t
]
1263 ["Previous Visible Heading"
1264 allout-previous-visible-heading t
]
1266 ["Up Level" allout-up-current-level t
]
1267 ["Forward Current Level" allout-forward-current-level t
]
1268 ["Backward Current Level"
1269 allout-backward-current-level t
]
1271 ["Beginning of Entry"
1272 allout-beginning-of-current-entry t
]
1273 ["End of Entry" allout-end-of-entry t
]
1274 ["End of Subtree" allout-end-of-current-subtree t
]))
1275 (easy-menu-define allout-mode-misc-menu
1276 allout-mode-map-value
1277 "Allout outlines miscellaneous bindings."
1279 ["Version" allout-version t
]
1281 ["Duplicate Exposed" allout-copy-exposed-to-buffer t
]
1282 ["Duplicate Exposed, numbered"
1283 allout-flatten-exposed-to-buffer t
]
1284 ["Duplicate Exposed, indented"
1285 allout-indented-exposed-to-buffer t
]
1287 ["Set Header Lead" allout-reset-header-lead t
]
1288 ["Set New Exposure" allout-expose-topic t
])))
1289 ;;;_ : Allout Modal-Variables Utilities
1290 ;;;_ = allout-mode-prior-settings
1291 (defvar allout-mode-prior-settings nil
1292 "Internal `allout-mode' use; settings to be resumed on mode deactivation.
1294 See `allout-add-resumptions' and `allout-do-resumptions'.")
1295 (make-variable-buffer-local 'allout-mode-prior-settings
)
1296 ;;;_ > allout-add-resumptions (&rest pairs)
1297 (defun allout-add-resumptions (&rest pairs
)
1298 "Set name/value PAIRS.
1300 Old settings are preserved for later resumption using `allout-do-resumptions'.
1302 The new values are set as a buffer local. On resumption, the prior buffer
1303 scope of the variable is restored along with its value. If it was a void
1304 buffer-local value, then it is left as nil on resumption.
1306 The pairs are lists whose car is the name of the variable and car of the
1307 cdr is the new value: '(some-var some-value)'. The pairs can actually be
1308 triples, where the third element qualifies the disposition of the setting,
1309 as described further below.
1311 If the optional third element is the symbol 'extend, then the new value
1312 created by `cons'ing the second element of the pair onto the front of the
1315 If the optional third element is the symbol 'append, then the new value is
1316 extended from the existing one by `append'ing a list containing the second
1317 element of the pair onto the end of the existing value.
1319 Extension, and resumptions in general, should not be used for hook
1320 functions -- use the 'local mode of `add-hook' for that, instead.
1322 The settings are stored on `allout-mode-prior-settings'."
1324 (let* ((pair (pop pairs
))
1327 (qualifier (if (> (length pair
) 2)
1330 (if (not (symbolp name
))
1331 (error "Pair's name, %S, must be a symbol, not %s"
1332 name
(type-of name
)))
1333 (setq prior-value
(condition-case nil
1335 (void-variable nil
)))
1336 (when (not (assoc name allout-mode-prior-settings
))
1337 ;; Not already added as a resumption, create the prior setting entry.
1338 (if (local-variable-p name
(current-buffer))
1339 ;; is already local variable -- preserve the prior value:
1340 (push (list name prior-value
) allout-mode-prior-settings
)
1341 ;; wasn't local variable, indicate so for resumption by killing
1342 ;; local value, and make it local:
1343 (push (list name
) allout-mode-prior-settings
)
1344 (make-local-variable name
)))
1346 (cond ((eq qualifier
'extend
)
1347 (if (not (listp prior-value
))
1348 (error "extension of non-list prior value attempted")
1349 (set name
(cons value prior-value
))))
1350 ((eq qualifier
'append
)
1351 (if (not (listp prior-value
))
1352 (error "appending of non-list prior value attempted")
1353 (set name
(append prior-value
(list value
)))))
1354 (t (error "unrecognized setting qualifier `%s' encountered"
1356 (set name value
)))))
1357 ;;;_ > allout-do-resumptions ()
1358 (defun allout-do-resumptions ()
1359 "Resume all name/value settings registered by `allout-add-resumptions'.
1361 This is used when concluding allout-mode, to resume selected variables to
1362 their settings before allout-mode was started."
1364 (while allout-mode-prior-settings
1365 (let* ((pair (pop allout-mode-prior-settings
))
1367 (value-cell (cdr pair
)))
1368 (if (not value-cell
)
1369 ;; Prior value was global:
1370 (kill-local-variable name
)
1371 ;; Prior value was explicit:
1372 (set name
(car value-cell
))))))
1373 ;;;_ : Mode-specific incidentals
1374 ;;;_ > allout-unprotected (expr)
1375 (defmacro allout-unprotected
(expr)
1376 "Enable internal outline operations to alter invisible text."
1377 `(let ((inhibit-read-only (if (not buffer-read-only
) t
))
1378 (inhibit-field-text-motion t
))
1380 ;;;_ = allout-mode-hook
1381 (defvar allout-mode-hook nil
1382 "*Hook that's run when allout mode starts.")
1383 ;;;_ = allout-mode-deactivate-hook
1384 (defvar allout-mode-deactivate-hook nil
1385 "*Hook that's run when allout mode ends.")
1386 (define-obsolete-variable-alias 'allout-mode-deactivate-hook
1387 'allout-mode-off-hook
"future")
1388 ;;;_ = allout-exposure-category
1389 (defvar allout-exposure-category nil
1390 "Symbol for use as allout invisible-text overlay category.")
1391 ;;;_ = allout-exposure-change-hook
1392 (defvar allout-exposure-change-hook nil
1393 "*Hook that's run after allout outline subtree exposure changes.
1395 It is run at the conclusion of `allout-flag-region'.
1397 Functions on the hook must take three arguments:
1399 - FROM -- integer indicating the point at the start of the change.
1400 - TO -- integer indicating the point of the end of the change.
1401 - FLAG -- change mode: nil for exposure, otherwise concealment.
1403 This hook might be invoked multiple times by a single command.")
1404 ;;;_ = allout-structure-added-hook
1405 (defvar allout-structure-added-hook nil
1406 "*Hook that's run after addition of items to the outline.
1408 Functions on the hook should take two arguments:
1410 - NEW-START -- integer indicating position of start of the first new item.
1411 - NEW-END -- integer indicating position of end of the last new item.
1413 This hook might be invoked multiple times by a single command.")
1414 ;;;_ = allout-structure-deleted-hook
1415 (defvar allout-structure-deleted-hook nil
1416 "*Hook that's run after disciplined deletion of subtrees from the outline.
1418 Functions on the hook must take two arguments:
1420 - DEPTH -- integer indicating the depth of the subtree that was deleted.
1421 - REMOVED-FROM -- integer indicating the point where the subtree was removed.
1423 Some edits that remove or invalidate items may missed by this hook:
1424 specifically edits that native allout routines do not control.
1426 This hook might be invoked multiple times by a single command.")
1427 ;;;_ = allout-structure-shifted-hook
1428 (defvar allout-structure-shifted-hook nil
1429 "*Hook that's run after shifting of items in the outline.
1431 Functions on the hook should take two arguments:
1433 - DEPTH-CHANGE -- integer indicating depth increase, negative for decrease
1434 - START -- integer indicating the start point of the shifted parent item.
1436 Some edits that shift items can be missed by this hook: specifically edits
1437 that native allout routines do not control.
1439 This hook might be invoked multiple times by a single command.")
1440 ;;;_ = allout-after-copy-or-kill-hook
1441 (defvar allout-after-copy-or-kill-hook nil
1442 "*Hook that's run after copying outline text.
1444 Functions on the hook should take two arguments:
1446 START, END -- integers indicating the span containing the copied text.")
1447 ;;;_ = allout-outside-normal-auto-fill-function
1448 (defvar allout-outside-normal-auto-fill-function nil
1449 "Value of normal-auto-fill-function outside of allout mode.
1451 Used by allout-auto-fill to do the mandated normal-auto-fill-function
1452 wrapped within allout's automatic fill-prefix setting.")
1453 (make-variable-buffer-local 'allout-outside-normal-auto-fill-function
)
1454 ;;;_ = prevent redundant activation by desktop mode:
1455 (add-to-list 'desktop-minor-mode-handlers
'(allout-mode . nil
))
1456 ;;;_ = allout-passphrase-verifier-string
1457 (defvar allout-passphrase-verifier-string nil
1458 "Setting used to test solicited encryption passphrases against the one
1459 already associated with a file.
1461 It consists of an encrypted random string useful only to verify that a
1462 passphrase entered by the user is effective for decryption. The passphrase
1463 itself is \*not* recorded in the file anywhere, and the encrypted contents
1464 are random binary characters to avoid exposing greater susceptibility to
1467 The verifier string is retained as an Emacs file variable, as well as in
1468 the Emacs buffer state, if file variable adjustments are enabled. See
1469 `allout-enable-file-variable-adjustment' for details about that.")
1470 (make-variable-buffer-local 'allout-passphrase-verifier-string
)
1471 (make-obsolete 'allout-passphrase-verifier-string
1472 'allout-passphrase-verifier-string
"23.3")
1474 (put 'allout-passphrase-verifier-string
'safe-local-variable
'stringp
)
1475 ;;;_ = allout-passphrase-hint-string
1476 (defvar allout-passphrase-hint-string
""
1477 "Variable used to retain reminder string for file's encryption passphrase.
1479 See the description of `allout-passphrase-hint-handling' for details about how
1480 the reminder is deployed.
1482 The hint is retained as an Emacs file variable, as well as in the Emacs buffer
1483 state, if file variable adjustments are enabled. See
1484 `allout-enable-file-variable-adjustment' for details about that.")
1485 (make-variable-buffer-local 'allout-passphrase-hint-string
)
1486 (setq-default allout-passphrase-hint-string
"")
1487 (make-obsolete 'allout-passphrase-hint-string
1488 'allout-passphrase-hint-string
"23.3")
1490 (put 'allout-passphrase-hint-string
'safe-local-variable
'stringp
)
1491 ;;;_ = allout-after-save-decrypt
1492 (defvar allout-after-save-decrypt nil
1493 "Internal variable, is nil or has the value of two points:
1495 - the location of a topic to be decrypted after saving is done
1496 - where to situate the cursor after the decryption is performed
1498 This is used to decrypt the topic that was currently being edited, if it
1499 was encrypted automatically as part of a file write or autosave.")
1500 (make-variable-buffer-local 'allout-after-save-decrypt
)
1501 ;;;_ = allout-encryption-plaintext-sanitization-regexps
1502 (defvar allout-encryption-plaintext-sanitization-regexps nil
1503 "List of regexps whose matches are removed from plaintext before encryption.
1505 This is for the sake of removing artifacts, like escapes, that are added on
1506 and not actually part of the original plaintext. The removal is done just
1507 prior to encryption.
1509 Entries must be symbols that are bound to the desired values.
1511 Each value can be a regexp or a list with a regexp followed by a
1512 substitution string. If it's just a regexp, all its matches are removed
1513 before the text is encrypted. If it's a regexp and a substitution, the
1514 substition is used against the regexp matches, a la `replace-match'.")
1515 (make-variable-buffer-local 'allout-encryption-text-removal-regexps
)
1516 ;;;_ = allout-encryption-ciphertext-rejection-regexps
1517 (defvar allout-encryption-ciphertext-rejection-regexps nil
1518 "Variable for regexps matching plaintext to remove before encryption.
1520 This is used to detect strings in encryption results that would
1521 register as allout mode structural elements, for exmple, as a
1524 Entries must be symbols that are bound to the desired regexp values.
1526 Encryptions that result in matches will be retried, up to
1527 `allout-encryption-ciphertext-rejection-limit' times, after which
1528 an error is raised.")
1530 (make-variable-buffer-local 'allout-encryption-ciphertext-rejection-regexps
)
1531 ;;;_ = allout-encryption-ciphertext-rejection-ceiling
1532 (defvar allout-encryption-ciphertext-rejection-ceiling
5
1533 "Limit on number of times encryption ciphertext is rejected.
1535 See `allout-encryption-ciphertext-rejection-regexps' for rejection reasons.")
1536 (make-variable-buffer-local 'allout-encryption-ciphertext-rejection-ceiling
)
1537 ;;;_ > allout-mode-p ()
1538 ;; Must define this macro above any uses, or byte compilation will lack
1539 ;; proper def, if file isn't loaded -- eg, during emacs build!
1540 (defmacro allout-mode-p
()
1541 "Return t if `allout-mode' is active in current buffer."
1543 ;;;_ > allout-write-file-hook-handler ()
1544 (defun allout-write-file-hook-handler ()
1545 "Implement `allout-encrypt-unencrypted-on-saves' policy for file writes."
1547 (if (or (not (allout-mode-p))
1548 (not (boundp 'allout-encrypt-unencrypted-on-saves
))
1549 (not allout-encrypt-unencrypted-on-saves
))
1551 (let ((except-mark (and (equal allout-encrypt-unencrypted-on-saves
1554 (if (save-excursion (goto-char (point-min))
1555 (allout-next-topic-pending-encryption except-mark
))
1557 (message "auto-encrypting pending topics")
1559 (condition-case failure
1560 (setq allout-after-save-decrypt
1561 (allout-encrypt-decrypted except-mark
))
1563 "allout-write-file-hook-handler suppressing error %s"
1568 ;;;_ > allout-auto-save-hook-handler ()
1569 (defun allout-auto-save-hook-handler ()
1570 "Implement `allout-encrypt-unencrypted-on-saves' policy for auto save."
1572 (if (and (allout-mode-p) allout-encrypt-unencrypted-on-saves
)
1573 ;; Always implement 'except-current policy when enabled.
1574 (let ((allout-encrypt-unencrypted-on-saves 'except-current
))
1575 (allout-write-file-hook-handler))))
1576 ;;;_ > allout-after-saves-handler ()
1577 (defun allout-after-saves-handler ()
1578 "Decrypt topic encrypted for save, if it's currently being edited.
1580 Ie, if it was pending encryption and contained the point in its body before
1583 We use values stored in `allout-after-save-decrypt' to locate the topic
1584 and the place for the cursor after the decryption is done."
1585 (if (not (and (allout-mode-p)
1586 (boundp 'allout-after-save-decrypt
)
1587 allout-after-save-decrypt
))
1589 (goto-char (car allout-after-save-decrypt
))
1590 (let ((was-modified (buffer-modified-p)))
1591 (allout-toggle-subtree-encryption)
1592 (if (not was-modified
)
1593 (set-buffer-modified-p nil
)))
1594 (goto-char (cadr allout-after-save-decrypt
))
1595 (setq allout-after-save-decrypt nil
))
1597 ;;;_ > allout-called-interactively-p ()
1598 (defmacro allout-called-interactively-p
()
1599 "A version of called-interactively-p independent of emacs version."
1600 ;; ... to ease maintenance of allout without betraying deprecation.
1601 (if (equal (subr-arity (symbol-function 'called-interactively-p
))
1603 '(called-interactively-p)
1604 '(called-interactively-p 'interactive
)))
1605 ;;;_ = allout-inhibit-aberrance-doublecheck nil
1606 ;; In some exceptional moments, disparate topic depths need to be allowed
1607 ;; momentarily, eg when one topic is being yanked into another and they're
1608 ;; about to be reconciled. let-binding allout-inhibit-aberrance-doublecheck
1609 ;; prevents the aberrance doublecheck to allow, eg, the reconciliation
1610 ;; processing to happen in the presence of such discrepancies. It should
1611 ;; almost never be needed, however.
1612 (defvar allout-inhibit-aberrance-doublecheck nil
1613 "Internal state, for momentarily inhibits aberrance doublecheck.
1615 This should only be momentarily let-bound non-nil, not set
1616 non-nil in a lasting way.")
1618 ;;;_ #2 Mode environment and activation
1619 ;;;_ = allout-explicitly-deactivated
1620 (defvar allout-explicitly-deactivated nil
1621 "If t, `allout-mode's last deactivation was deliberate.
1622 So `allout-post-command-business' should not reactivate it...")
1623 (make-variable-buffer-local 'allout-explicitly-deactivated
)
1624 ;;;_ > allout-init (&optional mode)
1625 (defun allout-init (&optional mode
)
1626 "Prime `allout-mode' to enable/disable auto-activation, wrt `allout-layout'.
1628 MODE is one of the following symbols:
1630 - nil (or no argument) deactivate auto-activation/layout;
1631 - `activate', enable auto-activation only;
1632 - `ask', enable auto-activation, and enable auto-layout but with
1633 confirmation for layout operation solicited from user each time;
1634 - `report', just report and return the current auto-activation state;
1635 - anything else (eg, t) for auto-activation and auto-layout, without
1636 any confirmation check.
1638 Use this function to setup your Emacs session for automatic activation
1639 of allout outline mode, contingent to the buffer-specific setting of
1640 the `allout-layout' variable. (See `allout-layout' and
1641 `allout-expose-topic' docstrings for more details on auto layout).
1643 `allout-init' works by setting up (or removing) the `allout-mode'
1644 find-file-hook, and giving `allout-auto-activation' a suitable
1647 To prime your Emacs session for full auto-outline operation, include
1648 the following two lines in your Emacs init file:
1654 (if (allout-called-interactively-p)
1658 (concat "Select outline auto setup mode "
1659 "(empty for report, ? for options) ")
1660 '(("nil")("full")("activate")("deactivate")
1661 ("ask") ("report") (""))
1664 (if (string= mode
"")
1666 (setq mode
(intern-soft mode
)))))
1668 ;; convenience aliases, for consistent ref to respective vars:
1669 ((hook 'allout-find-file-hook
)
1670 (find-file-hook-var-name (if (boundp 'find-file-hook
)
1673 (curr-mode 'allout-auto-activation
))
1676 (set find-file-hook-var-name
1677 (delq hook
(symbol-value find-file-hook-var-name
)))
1678 (if (allout-called-interactively-p)
1679 (message "Allout outline mode auto-activation inhibited.")))
1681 (if (not (memq hook
(symbol-value find-file-hook-var-name
)))
1683 ;; Just punt and use the reports from each of the modes:
1684 (allout-init (symbol-value curr-mode
))))
1685 (t (add-hook find-file-hook-var-name hook
)
1686 (set curr-mode
; `set', not `setq'!
1687 (cond ((eq mode
'activate
)
1689 "Outline mode auto-activation enabled.")
1692 ;; Return the current mode setting:
1696 (concat "Outline mode auto-activation and "
1697 "-layout (upon confirmation) enabled."))
1700 "Outline mode auto-activation and -layout enabled.")
1702 ;;;_ > allout-setup-menubar ()
1703 (defun allout-setup-menubar ()
1704 "Populate the current buffer's menubar with `allout-mode' stuff."
1705 (let ((menus (list allout-mode-exposure-menu
1706 allout-mode-editing-menu
1707 allout-mode-navigation-menu
1708 allout-mode-misc-menu
))
1711 (setq cur
(car menus
)
1713 (easy-menu-add cur
))))
1714 ;;;_ > allout-overlay-preparations
1715 (defun allout-overlay-preparations ()
1716 "Set the properties of the allout invisible-text overlay and others."
1717 (setplist 'allout-exposure-category nil
)
1718 (put 'allout-exposure-category
'invisible
'allout
)
1719 (put 'allout-exposure-category
'evaporate t
)
1720 ;; ??? We use isearch-open-invisible *and* isearch-mode-end-hook. The
1721 ;; latter would be sufficient, but it seems that a separate behavior --
1722 ;; the _transient_ opening of invisible text during isearch -- is keyed to
1723 ;; presence of the isearch-open-invisible property -- even though this
1724 ;; property controls the isearch _arrival_ behavior. This is the case at
1725 ;; least in emacs 21, 22.1, and xemacs 21.4.
1726 (put 'allout-exposure-category
'isearch-open-invisible
1727 'allout-isearch-end-handler
)
1728 (if (featurep 'xemacs
)
1729 (put 'allout-exposure-category
'start-open t
)
1730 (put 'allout-exposure-category
'insert-in-front-hooks
1731 '(allout-overlay-insert-in-front-handler)))
1732 (put 'allout-exposure-category
'modification-hooks
1733 '(allout-overlay-interior-modification-handler)))
1734 ;;;_ > define-minor-mode allout-mode
1737 (define-minor-mode allout-mode
1739 "Toggle minor mode for controlling exposure and editing of text outlines.
1740 \\<allout-mode-map-value>
1742 Allout outline mode always runs as a minor mode.
1744 Allout outline mode provides extensive outline oriented
1745 formatting and manipulation. It enables structural editing of
1746 outlines, as well as navigation and exposure. It also is
1747 specifically aimed at accommodating syntax-sensitive text like
1748 programming languages. \(For example, see the allout code itself,
1749 which is organized as an allout outline.)
1751 In addition to typical outline navigation and exposure, allout includes:
1753 - topic-oriented authoring, including keystroke-based topic creation,
1754 repositioning, promotion/demotion, cut, and paste
1755 - incremental search with dynamic exposure and reconcealment of hidden text
1756 - adjustable format, so programming code can be developed in outline-structure
1757 - easy topic encryption and decryption, symmetric or key-pair
1758 - \"Hot-spot\" operation, for single-keystroke maneuvering and exposure control
1759 - integral outline layout, for automatic initial exposure when visiting a file
1760 - independent extensibility, using comprehensive exposure and authoring hooks
1762 and many other features.
1764 Below is a description of the key bindings, and then description
1765 of special `allout-mode' features and terminology. See also the
1766 outline menubar additions for quick reference to many of the
1767 features, and see the docstring of the function `allout-init' for
1768 instructions on priming your emacs session for automatic
1769 activation of `allout-mode'.
1771 The bindings are those listed in `allout-prefixed-keybindings'
1772 and `allout-unprefixed-keybindings'. We recommend customizing
1773 `allout-command-prefix' to use just `\\C-c' as the command
1774 prefix, if the allout bindings don't conflict with any personal
1775 bindings you have on \\C-c. In any case, outline structure
1776 navigation and authoring is simplified by positioning the cursor
1777 on an item's bullet character, the \"hot-spot\" -- then you can
1778 invoke allout commands with just the un-prefixed,
1779 un-control-shifted command letters. This is described further in
1780 the HOT-SPOT Operation section.
1784 \\[allout-hide-current-subtree] `allout-hide-current-subtree'
1785 \\[allout-show-children] `allout-show-children'
1786 \\[allout-show-current-subtree] `allout-show-current-subtree'
1787 \\[allout-show-current-entry] `allout-show-current-entry'
1788 \\[allout-show-all] `allout-show-all'
1792 \\[allout-next-visible-heading] `allout-next-visible-heading'
1793 \\[allout-previous-visible-heading] `allout-previous-visible-heading'
1794 \\[allout-up-current-level] `allout-up-current-level'
1795 \\[allout-forward-current-level] `allout-forward-current-level'
1796 \\[allout-backward-current-level] `allout-backward-current-level'
1797 \\[allout-end-of-entry] `allout-end-of-entry'
1798 \\[allout-beginning-of-current-entry] `allout-beginning-of-current-entry' (alternately, goes to hot-spot)
1799 \\[allout-beginning-of-line] `allout-beginning-of-line' -- like regular beginning-of-line, but
1800 if immediately repeated cycles to the beginning of the current item
1801 and then to the hot-spot (if `allout-beginning-of-line-cycles' is set).
1804 Topic Header Production:
1805 -----------------------
1806 \\[allout-open-sibtopic] `allout-open-sibtopic' Create a new sibling after current topic.
1807 \\[allout-open-subtopic] `allout-open-subtopic' ... an offspring of current topic.
1808 \\[allout-open-supertopic] `allout-open-supertopic' ... a sibling of the current topic's parent.
1810 Topic Level and Prefix Adjustment:
1811 ---------------------------------
1812 \\[allout-shift-in] `allout-shift-in' Shift current topic and all offspring deeper
1813 \\[allout-shift-out] `allout-shift-out' ... less deep
1814 \\[allout-rebullet-current-heading] `allout-rebullet-current-heading' Prompt for alternate bullet for
1816 \\[allout-rebullet-topic] `allout-rebullet-topic' Reconcile bullets of topic and
1817 its' offspring -- distinctive bullets are not changed, others
1818 are alternated according to nesting depth.
1819 \\[allout-number-siblings] `allout-number-siblings' Number bullets of topic and siblings --
1820 the offspring are not affected.
1821 With repeat count, revoke numbering.
1823 Topic-oriented Killing and Yanking:
1824 ----------------------------------
1825 \\[allout-kill-topic] `allout-kill-topic' Kill current topic, including offspring.
1826 \\[allout-copy-topic-as-kill] `allout-copy-topic-as-kill' Copy current topic, including offspring.
1827 \\[allout-kill-line] `allout-kill-line' kill-line, attending to outline structure.
1828 \\[allout-copy-line-as-kill] `allout-copy-line-as-kill' Copy line but don't delete it.
1829 \\[allout-yank] `allout-yank' Yank, adjusting depth of yanked topic to
1830 depth of heading if yanking into bare topic
1831 heading (ie, prefix sans text).
1832 \\[allout-yank-pop] `allout-yank-pop' Is to allout-yank as yank-pop is to yank
1834 Topic-oriented Encryption:
1835 -------------------------
1836 \\[allout-toggle-current-subtree-encryption] `allout-toggle-current-subtree-encryption'
1837 Encrypt/Decrypt topic content
1841 M-x outlineify-sticky Activate outline mode for current buffer,
1842 and establish a default file-var setting
1843 for `allout-layout'.
1844 \\[allout-mark-topic] `allout-mark-topic'
1845 \\[allout-copy-exposed-to-buffer] `allout-copy-exposed-to-buffer'
1846 Duplicate outline, sans concealed text, to
1847 buffer with name derived from derived from that
1848 of current buffer -- \"*BUFFERNAME exposed*\".
1849 \\[allout-flatten-exposed-to-buffer] `allout-flatten-exposed-to-buffer'
1850 Like above 'copy-exposed', but convert topic
1851 prefixes to section.subsection... numeric
1853 \\[eval-expression] (allout-init t) Setup Emacs session for outline mode
1858 Outline mode supports gpg encryption of topics, with support for
1859 symmetric and key-pair modes, and auto-encryption of topics
1860 pending encryption on save.
1862 Topics pending encryption are, by default, automatically
1863 encrypted during file saves, including checkpoint saves, to avoid
1864 exposing the plain text of encrypted topics in the file system.
1865 If the content of the topic containing the cursor was encrypted
1866 for a save, it is automatically decrypted for continued editing.
1868 NOTE: A few GnuPG v2 versions improperly preserve incorrect
1869 symmetric decryption keys, preventing entry of the correct key on
1870 subsequent decryption attempts until the cache times-out. That
1871 can take several minutes. \(Decryption of other entries is not
1872 affected.) Upgrade your EasyPG version, if you can, and you can
1873 deliberately clear your gpg-agent's cache by sending it a '-HUP'
1876 See `allout-toggle-current-subtree-encryption' function docstring
1877 and `allout-encrypt-unencrypted-on-saves' customization variable
1882 Hot-spot operation provides a means for easy, single-keystroke outline
1883 navigation and exposure control.
1885 When the text cursor is positioned directly on the bullet character of
1886 a topic, regular characters (a to z) invoke the commands of the
1887 corresponding allout-mode keymap control chars. For example, \"f\"
1888 would invoke the command typically bound to \"C-c<space>C-f\"
1889 \(\\[allout-forward-current-level] `allout-forward-current-level').
1891 Thus, by positioning the cursor on a topic bullet, you can
1892 execute the outline navigation and manipulation commands with a
1893 single keystroke. Regular navigation keys (eg, \\[forward-char], \\[next-line]) don't get
1894 this special translation, so you can use them to get out of the
1895 hot-spot and back to normal editing operation.
1897 In allout-mode, the normal beginning-of-line command (\\[allout-beginning-of-line]) is
1898 replaced with one that makes it easy to get to the hot-spot. If you
1899 repeat it immediately it cycles (if `allout-beginning-of-line-cycles'
1900 is set) to the beginning of the item and then, if you hit it again
1901 immediately, to the hot-spot. Similarly, `allout-beginning-of-current-entry'
1902 \(\\[allout-beginning-of-current-entry]) moves to the hot-spot when the cursor is already located
1903 at the beginning of the current entry.
1907 Allout exposure and authoring activites all have associated
1908 hooks, by which independent code can cooperate with allout
1909 without changes to the allout core. Here are key ones:
1912 `allout-mode-deactivate-hook' \(deprecated)
1913 `allout-mode-off-hook'
1914 `allout-exposure-change-hook'
1915 `allout-structure-added-hook'
1916 `allout-structure-deleted-hook'
1917 `allout-structure-shifted-hook'
1918 `allout-after-copy-or-kill-hook'
1922 Topic hierarchy constituents -- TOPICS and SUBTOPICS:
1924 ITEM: A unitary outline element, including the HEADER and ENTRY text.
1925 TOPIC: An ITEM and any ITEMs contained within it, ie having greater DEPTH
1926 and with no intervening items of lower DEPTH than the container.
1928 The visible ITEM most immediately containing the cursor.
1929 DEPTH: The degree of nesting of an ITEM; it increases with containment.
1930 The DEPTH is determined by the HEADER PREFIX. The DEPTH is also
1932 LEVEL: The same as DEPTH.
1935 Those ITEMs whose TOPICs contain an ITEM.
1936 PARENT: An ITEM's immediate ANCESTOR. It has a DEPTH one less than that
1939 The ITEMs contained within an ITEM's TOPIC.
1941 An OFFSPRING of its ANCESTOR TOPICs.
1943 An immediate SUBTOPIC of its PARENT.
1945 TOPICs having the same PARENT and DEPTH.
1947 Topic text constituents:
1949 HEADER: The first line of an ITEM, include the ITEM PREFIX and HEADER
1951 ENTRY: The text content of an ITEM, before any OFFSPRING, but including
1952 the HEADER text and distinct from the ITEM PREFIX.
1953 BODY: Same as ENTRY.
1954 PREFIX: The leading text of an ITEM which distinguishes it from normal
1955 ENTRY text. Allout recognizes the outline structure according
1956 to the strict PREFIX format. It consists of a PREFIX-LEAD string,
1957 PREFIX-PADDING, and a BULLET. The BULLET might be followed by a
1958 number, indicating the ordinal number of the topic among its
1959 siblings, or an asterisk indicating encryption, plus an optional
1960 space. After that is the ITEM HEADER text, which is not part of
1963 The relative length of the PREFIX determines the nesting DEPTH
1966 The string at the beginning of a HEADER PREFIX, by default a `.'.
1967 It can be customized by changing the setting of
1968 `allout-header-prefix' and then reinitializing `allout-mode'.
1970 When the PREFIX-LEAD is set to the comment-string of a
1971 programming language, outline structuring can be embedded in
1972 program code without interfering with processing of the text
1973 (by emacs or the language processor) as program code. This
1974 setting happens automatically when allout mode is used in
1975 programming-mode buffers. See `allout-use-mode-specific-leader'
1976 docstring for more detail.
1978 Spaces or asterisks which separate the PREFIX-LEAD and the
1979 bullet, determining the ITEM's DEPTH.
1980 BULLET: A character at the end of the ITEM PREFIX, it must be one of
1981 the characters listed on `allout-plain-bullets-string' or
1982 `allout-distinctive-bullets-string'. When creating a TOPIC,
1983 plain BULLETs are by default used, according to the DEPTH of the
1984 TOPIC. Choice among the distinctive BULLETs is offered when you
1985 provide a universal argugment \(\\[universal-argument]) to the
1986 TOPIC creation command, or when explictly rebulleting a TOPIC. The
1987 significance of the various distinctive bullets is purely by
1988 convention. See the documentation for the above bullet strings for
1991 The state of a TOPIC which determines the on-screen visibility
1992 of its OFFSPRING and contained ENTRY text.
1994 TOPICs and ENTRY text whose EXPOSURE is inhibited. Concealed
1995 text is represented by \"...\" ellipses.
1997 CONCEALED TOPICs are effectively collapsed within an ANCESTOR.
1998 CLOSED: A TOPIC whose immediate OFFSPRING and body-text is CONCEALED.
1999 OPEN: A TOPIC that is not CLOSED, though its OFFSPRING or BODY may be."
2002 :keymap
'allout-mode-map
2004 (let ((write-file-hook-var-name (cond ((boundp 'write-file-functions
)
2005 'write-file-functions
)
2006 ((boundp 'write-file-hooks
)
2008 (t 'local-write-file-hooks
)))
2009 (use-layout (if (listp allout-layout
)
2011 allout-default-layout
)))
2013 (if (not (allout-mode-p))
2017 ; Activation not explicitly
2018 ; requested, and either in
2019 ; active state or *de*activation
2020 ; specifically requested:
2021 (allout-do-resumptions)
2023 (remove-from-invisibility-spec '(allout . t
))
2024 (remove-hook 'pre-command-hook
'allout-pre-command-business t
)
2025 (remove-hook 'post-command-hook
'allout-post-command-business t
)
2026 (remove-hook 'before-change-functions
'allout-before-change-handler t
)
2027 (remove-hook 'isearch-mode-end-hook
'allout-isearch-end-handler t
)
2028 (remove-hook write-file-hook-var-name
2029 'allout-write-file-hook-handler t
)
2030 (remove-hook 'auto-save-hook
'allout-auto-save-hook-handler t
)
2032 (remove-overlays (point-min) (point-max)
2033 'category
'allout-exposure-category
))
2036 (if allout-old-style-prefixes
2037 ;; Inhibit all the fancy formatting:
2038 (allout-add-resumptions '(allout-primary-bullet "*")))
2040 (allout-overlay-preparations) ; Doesn't hurt to redo this.
2042 (allout-infer-header-lead-and-primary-bullet)
2043 (allout-infer-body-reindent)
2046 (allout-add-resumptions '(allout-encryption-ciphertext-rejection-regexps
2047 allout-line-boundary-regexp
2049 '(allout-encryption-ciphertext-rejection-regexps
2053 (allout-compose-and-institute-keymap)
2054 (produce-allout-mode-menubar-entries)
2056 (add-to-invisibility-spec '(allout . t
))
2058 (allout-add-resumptions '(line-move-ignore-invisible t
))
2059 (add-hook 'pre-command-hook
'allout-pre-command-business nil t
)
2060 (add-hook 'post-command-hook
'allout-post-command-business nil t
)
2061 (add-hook 'before-change-functions
'allout-before-change-handler nil t
)
2062 (add-hook 'isearch-mode-end-hook
'allout-isearch-end-handler nil t
)
2063 (add-hook write-file-hook-var-name
'allout-write-file-hook-handler
2065 (add-hook 'auto-save-hook
'allout-auto-save-hook-handler nil t
)
2067 ;; Stash auto-fill settings and adjust so custom allout auto-fill
2068 ;; func will be used if auto-fill is active or activated. (The
2069 ;; custom func respects topic headline, maintains hanging-indents,
2071 (allout-add-resumptions (list 'allout-former-auto-filler
2073 ;; Register allout-auto-fill to be used if
2074 ;; filling is active:
2075 (list 'allout-outside-normal-auto-fill-function
2076 normal-auto-fill-function
)
2077 '(normal-auto-fill-function allout-auto-fill
)
2078 ;; Paragraphs are broken by topic headlines.
2079 (list 'paragraph-start
2080 (concat paragraph-start
"\\|^\\("
2081 allout-regexp
"\\)"))
2082 (list 'paragraph-separate
2083 (concat paragraph-separate
"\\|^\\("
2084 allout-regexp
"\\)")))
2085 (if (and auto-fill-function
(not allout-inhibit-auto-fill
))
2086 ;; allout-auto-fill will use the stashed values and so forth.
2087 (allout-add-resumptions '(auto-fill-function allout-auto-fill
)))
2089 (allout-setup-menubar)
2091 ;; Do auto layout if warranted:
2092 (when (and allout-layout
2093 allout-auto-activation
2095 (and (not (eq allout-auto-activation
'activate
))
2096 (if (eq allout-auto-activation
'ask
)
2097 (if (y-or-n-p (format "Expose %s with layout '%s'? "
2101 (message "Skipped %s layout." (buffer-name))
2105 (message "Adjusting '%s' exposure..." (buffer-name))
2107 (allout-this-or-next-heading)
2110 (apply 'allout-expose-topic
(list use-layout
))
2111 (message "Adjusting '%s' exposure... done."
2113 ;; Problem applying exposure -- notify user, but don't
2114 ;; interrupt, eg, file visit:
2115 (error (message "%s" (car (cdr err
)))
2117 ) ; when allout-layout
2118 ) ; if (allout-mode-p)
2120 ) ; define-minor-mode
2121 ;;;_ > allout-minor-mode alias
2122 (defalias 'allout-minor-mode
'allout-mode
)
2123 ;;;_ > allout-unload-function
2124 (defun allout-unload-function ()
2125 "Unload the allout outline library."
2126 (save-current-buffer
2127 (dolist (buffer (buffer-list))
2129 (when (allout-mode-p) (allout-mode))))
2130 ;; continue standard unloading
2133 ;;;_ - Position Assessment
2134 ;;;_ > allout-hidden-p (&optional pos)
2135 (defsubst allout-hidden-p
(&optional pos
)
2136 "Non-nil if the character after point was made invisible by allout."
2137 (eq (get-char-property (or pos
(point)) 'invisible
) 'allout
))
2139 ;;;_ > allout-overlay-insert-in-front-handler (ol after beg end
2140 ;;; &optional prelen)
2141 (defun allout-overlay-insert-in-front-handler (ol after beg end
2143 "Shift the overlay so stuff inserted in front of it is excluded."
2145 ;; ??? Shouldn't moving the overlay should be unnecessary, if overlay
2146 ;; front-advance on the overlay worked as expected?
2147 (move-overlay ol
(1+ beg
) (overlay-end ol
))))
2148 ;;;_ > allout-overlay-interior-modification-handler (ol after beg end
2149 ;;; &optional prelen)
2150 (defun allout-overlay-interior-modification-handler (ol after beg end
2152 "Get confirmation before making arbitrary changes to invisible text.
2154 We expose the invisible text and ask for confirmation. Refusal or
2155 `keyboard-quit' abandons the changes, with keyboard-quit additionally
2156 reclosing the opened text.
2158 No confirmation is necessary when `inhibit-read-only' is set -- eg, allout
2159 internal functions use this feature cohesively bunch changes."
2161 (when (and (not inhibit-read-only
) (not after
))
2162 (let ((start (point))
2163 (ol-start (overlay-start ol
))
2164 (ol-end (overlay-end ol
))
2167 (while (< (point) end
)
2168 (when (allout-hidden-p)
2169 (allout-show-to-offshoot)
2170 (if (allout-hidden-p)
2171 (save-excursion (forward-char 1)
2172 (allout-show-to-offshoot)))
2174 (setq first
(point))))
2175 (goto-char (if (featurep 'xemacs
)
2176 (next-property-change (1+ (point)) nil end
)
2177 (next-char-property-change (1+ (point)) end
))))
2183 (substitute-command-keys
2184 (concat "Modify concealed text? (\"no\" just aborts,"
2185 " \\[keyboard-quit] also reconceals) "))))
2186 (progn (goto-char start
)
2187 (error "Concealed-text change refused")))
2188 (quit (allout-flag-region ol-start ol-end nil
)
2189 (allout-flag-region ol-start ol-end t
)
2190 (error "Concealed-text change abandoned, text reconcealed"))))
2191 (goto-char start
))))
2192 ;;;_ > allout-before-change-handler (beg end)
2193 (defun allout-before-change-handler (beg end
)
2194 "Protect against changes to invisible text.
2196 See `allout-overlay-interior-modification-handler' for details."
2198 (when (and (allout-mode-p) undo-in-progress
(allout-hidden-p))
2199 (allout-show-children))
2201 ;; allout-overlay-interior-modification-handler on an overlay handles
2202 ;; this in other emacs, via `allout-exposure-category's 'modification-hooks.
2203 (when (and (featurep 'xemacs
) (allout-mode-p))
2204 ;; process all of the pending overlays:
2207 (let ((overlay (allout-get-invisibility-overlay)))
2209 (allout-overlay-interior-modification-handler
2210 overlay nil beg end nil
))))))
2211 ;;;_ > allout-isearch-end-handler (&optional overlay)
2212 (defun allout-isearch-end-handler (&optional overlay
)
2213 "Reconcile allout outline exposure on arriving in hidden text after isearch.
2215 Optional OVERLAY parameter is for when this function is used by
2216 `isearch-open-invisible' overlay property. It is otherwise unused, so this
2217 function can also be used as an `isearch-mode-end-hook'."
2219 (if (and (allout-mode-p) (allout-hidden-p))
2220 (allout-show-to-offshoot)))
2222 ;;;_ #3 Internal Position State-Tracking -- "allout-recent-*" funcs
2223 ;; All the basic outline functions that directly do string matches to
2224 ;; evaluate heading prefix location set the variables
2225 ;; `allout-recent-prefix-beginning' and `allout-recent-prefix-end'
2226 ;; when successful. Functions starting with `allout-recent-' all
2227 ;; use this state, providing the means to avoid redundant searches
2228 ;; for just-established data. This optimization can provide
2229 ;; significant speed improvement, but it must be employed carefully.
2230 ;;;_ = allout-recent-prefix-beginning
2231 (defvar allout-recent-prefix-beginning
0
2232 "Buffer point of the start of the last topic prefix encountered.")
2233 (make-variable-buffer-local 'allout-recent-prefix-beginning
)
2234 ;;;_ = allout-recent-prefix-end
2235 (defvar allout-recent-prefix-end
0
2236 "Buffer point of the end of the last topic prefix encountered.")
2237 (make-variable-buffer-local 'allout-recent-prefix-end
)
2238 ;;;_ = allout-recent-depth
2239 (defvar allout-recent-depth
0
2240 "Depth of the last topic prefix encountered.")
2241 (make-variable-buffer-local 'allout-recent-depth
)
2242 ;;;_ = allout-recent-end-of-subtree
2243 (defvar allout-recent-end-of-subtree
0
2244 "Buffer point last returned by `allout-end-of-current-subtree'.")
2245 (make-variable-buffer-local 'allout-recent-end-of-subtree
)
2246 ;;;_ > allout-prefix-data ()
2247 (defsubst allout-prefix-data
()
2248 "Register allout-prefix state data.
2250 For reference by `allout-recent' funcs. Return
2251 the new value of `allout-recent-prefix-beginning'."
2252 (setq allout-recent-prefix-end
(or (match-end 1) (match-end 2) (match-end 3))
2253 allout-recent-prefix-beginning
(or (match-beginning 1)
2255 (match-beginning 3))
2256 allout-recent-depth
(max 1 (- allout-recent-prefix-end
2257 allout-recent-prefix-beginning
2258 allout-header-subtraction
)))
2259 allout-recent-prefix-beginning
)
2260 ;;;_ > nullify-allout-prefix-data ()
2261 (defsubst nullify-allout-prefix-data
()
2262 "Mark allout prefix data as being uninformative."
2263 (setq allout-recent-prefix-end
(point)
2264 allout-recent-prefix-beginning
(point)
2265 allout-recent-depth
0)
2266 allout-recent-prefix-beginning
)
2267 ;;;_ > allout-recent-depth ()
2268 (defsubst allout-recent-depth
()
2269 "Return depth of last heading encountered by an outline maneuvering function.
2271 All outline functions which directly do string matches to assess
2272 headings set the variables `allout-recent-prefix-beginning' and
2273 `allout-recent-prefix-end' if successful. This function uses those settings
2274 to return the current depth."
2276 allout-recent-depth
)
2277 ;;;_ > allout-recent-prefix ()
2278 (defsubst allout-recent-prefix
()
2279 "Like `allout-recent-depth', but returns text of last encountered prefix.
2281 All outline functions which directly do string matches to assess
2282 headings set the variables `allout-recent-prefix-beginning' and
2283 `allout-recent-prefix-end' if successful. This function uses those settings
2284 to return the current prefix."
2285 (buffer-substring-no-properties allout-recent-prefix-beginning
2286 allout-recent-prefix-end
))
2287 ;;;_ > allout-recent-bullet ()
2288 (defmacro allout-recent-bullet
()
2289 "Like allout-recent-prefix, but returns bullet of last encountered prefix.
2291 All outline functions which directly do string matches to assess
2292 headings set the variables `allout-recent-prefix-beginning' and
2293 `allout-recent-prefix-end' if successful. This function uses those settings
2294 to return the current depth of the most recently matched topic."
2295 '(buffer-substring-no-properties (1- allout-recent-prefix-end
)
2296 allout-recent-prefix-end
))
2300 ;;;_ - Position Assessment
2301 ;;;_ : Location Predicates
2302 ;;;_ > allout-do-doublecheck ()
2303 (defsubst allout-do-doublecheck
()
2304 "True if current item conditions qualify for checking on topic aberrance."
2306 ;; presume integrity of outline and yanked content during yank -- necessary
2307 ;; to allow for level disparity of yank location and yanked text:
2308 (not allout-inhibit-aberrance-doublecheck
)
2309 ;; allout-doublecheck-at-and-shallower is ceiling for doublecheck:
2310 (<= allout-recent-depth allout-doublecheck-at-and-shallower
)))
2311 ;;;_ > allout-aberrant-container-p ()
2312 (defun allout-aberrant-container-p ()
2313 "True if topic, or next sibling with children, contains them discontinuously.
2315 Discontinuous means an immediate offspring that is nested more
2316 than one level deeper than the topic.
2318 If topic has no offspring, then the next sibling with offspring will
2319 determine whether or not this one is determined to be aberrant.
2321 If true, then the allout-recent-* settings are calibrated on the
2322 offspring that qaulifies it as aberrant, ie with depth that
2323 exceeds the topic by more than one."
2325 ;; This is most clearly understood when considering standard-prefix-leader
2326 ;; low-level topics, which can all too easily match text not intended as
2327 ;; headers. For example, any line with a leading '.' or '*' and lacking a
2328 ;; following bullet qualifies without this protection. (A sequence of
2329 ;; them can occur naturally, eg a typical textual bullet list.) We
2330 ;; disqualify such low-level sequences when they are followed by a
2331 ;; discontinuously contained child, inferring that the sequences are not
2332 ;; actually connected with their prospective context.
2334 (let ((depth (allout-depth))
2335 (start-point (point))
2339 (while (and (not done
)
2340 (re-search-forward allout-line-boundary-regexp nil
0))
2341 (allout-prefix-data)
2342 (goto-char allout-recent-prefix-beginning
)
2344 ;; sibling -- continue:
2345 ((eq allout-recent-depth depth
))
2346 ;; first offspring is excessive -- aberrant:
2347 ((> allout-recent-depth
(1+ depth
))
2348 (setq done t aberrant t
))
2349 ;; next non-sibling is lower-depth -- not aberrant:
2350 (t (setq done t
))))))
2353 (goto-char start-point
)
2354 ;; recalibrate allout-recent-*
2357 ;;;_ > allout-on-current-heading-p ()
2358 (defun allout-on-current-heading-p ()
2359 "Return non-nil if point is on current visible topics' header line.
2361 Actually, returns prefix beginning point."
2363 (allout-beginning-of-current-line)
2365 (and (looking-at allout-regexp
)
2366 (allout-prefix-data)
2367 (or (not (allout-do-doublecheck))
2368 (not (allout-aberrant-container-p)))))))
2369 ;;;_ > allout-on-heading-p ()
2370 (defalias 'allout-on-heading-p
'allout-on-current-heading-p
)
2371 ;;;_ > allout-e-o-prefix-p ()
2372 (defun allout-e-o-prefix-p ()
2373 "True if point is located where current topic prefix ends, heading begins."
2374 (and (save-match-data
2375 (save-excursion (let ((inhibit-field-text-motion t
))
2376 (beginning-of-line))
2377 (looking-at allout-regexp
))
2378 (= (point) (save-excursion (allout-end-of-prefix)(point))))))
2379 ;;;_ : Location attributes
2380 ;;;_ > allout-depth ()
2381 (defun allout-depth ()
2382 "Return depth of topic most immediately containing point.
2384 Does not do doublecheck for aberrant topic header.
2386 Return zero if point is not within any topic.
2388 Like `allout-current-depth', but respects hidden as well as visible topics."
2390 (let ((start-point (point)))
2391 (if (and (allout-goto-prefix)
2392 (not (< start-point
(point))))
2395 ;; Oops, no prefix, nullify it:
2396 (nullify-allout-prefix-data)
2397 ;; ... and return 0:
2399 ;;;_ > allout-current-depth ()
2400 (defun allout-current-depth ()
2401 "Return depth of visible topic most immediately containing point.
2403 Return zero if point is not within any topic."
2405 (if (allout-back-to-current-heading)
2407 (- allout-recent-prefix-end
2408 allout-recent-prefix-beginning
2409 allout-header-subtraction
))
2411 ;;;_ > allout-get-current-prefix ()
2412 (defun allout-get-current-prefix ()
2413 "Topic prefix of the current topic."
2415 (if (allout-goto-prefix)
2416 (allout-recent-prefix))))
2417 ;;;_ > allout-get-bullet ()
2418 (defun allout-get-bullet ()
2419 "Return bullet of containing topic (visible or not)."
2421 (and (allout-goto-prefix)
2422 (allout-recent-bullet))))
2423 ;;;_ > allout-current-bullet ()
2424 (defun allout-current-bullet ()
2425 "Return bullet of current (visible) topic heading, or none if none found."
2428 (allout-back-to-current-heading)
2429 (buffer-substring-no-properties (- allout-recent-prefix-end
1)
2430 allout-recent-prefix-end
))
2431 ;; Quick and dirty provision, ostensibly for missing bullet:
2432 (args-out-of-range nil
))
2434 ;;;_ > allout-get-prefix-bullet (prefix)
2435 (defun allout-get-prefix-bullet (prefix)
2436 "Return the bullet of the header prefix string PREFIX."
2437 ;; Doesn't make sense if we're old-style prefixes, but this just
2438 ;; oughtn't be called then, so forget about it...
2439 (if (string-match allout-regexp prefix
)
2440 (substring prefix
(1- (match-end 2)) (match-end 2))))
2441 ;;;_ > allout-sibling-index (&optional depth)
2442 (defun allout-sibling-index (&optional depth
)
2443 "Item number of this prospective topic among its siblings.
2445 If optional arg DEPTH is greater than current depth, then we're
2446 opening a new level, and return 0.
2448 If less than this depth, ascend to that depth and count..."
2451 (cond ((and depth
(<= depth
0) 0))
2452 ((or (null depth
) (= depth
(allout-depth)))
2454 (while (allout-previous-sibling allout-recent-depth nil
)
2455 (setq index
(1+ index
)))
2457 ((< depth allout-recent-depth
)
2458 (allout-ascend-to-depth depth
)
2459 (allout-sibling-index))
2461 ;;;_ > allout-topic-flat-index ()
2462 (defun allout-topic-flat-index ()
2463 "Return a list indicating point's numeric section.subsect.subsubsect...
2464 Outermost is first."
2465 (let* ((depth (allout-depth))
2466 (next-index (allout-sibling-index depth
))
2468 (while (> next-index
0)
2469 (setq rev-sibls
(cons next-index rev-sibls
))
2470 (setq depth
(1- depth
))
2471 (setq next-index
(allout-sibling-index depth
)))
2475 ;;;_ - Navigation routines
2476 ;;;_ > allout-beginning-of-current-line ()
2477 (defun allout-beginning-of-current-line ()
2478 "Like beginning of line, but to visible text."
2480 ;; This combination of move-beginning-of-line and beginning-of-line is
2481 ;; deliberate, but the (beginning-of-line) may now be superfluous.
2482 (let ((inhibit-field-text-motion t
))
2483 (move-beginning-of-line 1)
2485 (while (and (not (bobp)) (or (not (bolp)) (allout-hidden-p)))
2487 (if (or (allout-hidden-p) (not (bolp)))
2488 (forward-char -
1)))))
2489 ;;;_ > allout-end-of-current-line ()
2490 (defun allout-end-of-current-line ()
2491 "Move to the end of line, past concealed text if any."
2492 ;; This is for symmetry with `allout-beginning-of-current-line' --
2493 ;; `move-end-of-line' doesn't suffer the same problem as
2494 ;; `move-beginning-of-line'.
2495 (let ((inhibit-field-text-motion t
))
2497 (while (allout-hidden-p)
2499 (if (allout-hidden-p) (forward-char 1)))))
2500 ;;;_ > allout-beginning-of-line ()
2501 (defun allout-beginning-of-line ()
2502 "Beginning-of-line with `allout-beginning-of-line-cycles' behavior, if set."
2506 (if (or (not allout-beginning-of-line-cycles
)
2507 (not (equal last-command this-command
)))
2509 (if (and (not (bolp))
2510 (allout-hidden-p (1- (point))))
2511 (goto-char (allout-previous-single-char-property-change
2512 (1- (point)) 'invisible
)))
2513 (move-beginning-of-line 1))
2515 (let ((beginning-of-body
2517 (while (and (allout-do-doublecheck)
2518 (allout-aberrant-container-p)
2519 (allout-previous-visible-heading 1)))
2520 (allout-beginning-of-current-entry)
2522 (cond ((= (current-column) 0)
2523 (goto-char beginning-of-body
))
2524 ((< (point) beginning-of-body
)
2525 (allout-beginning-of-current-line))
2526 ((= (point) beginning-of-body
)
2527 (goto-char (allout-current-bullet-pos)))
2528 (t (allout-beginning-of-current-line)
2529 (if (< (point) beginning-of-body
)
2530 ;; we were on the headline after its start:
2531 (goto-char beginning-of-body
)))))))
2532 ;;;_ > allout-end-of-line ()
2533 (defun allout-end-of-line ()
2534 "End-of-line with `allout-end-of-line-cycles' behavior, if set."
2538 (if (or (not allout-end-of-line-cycles
)
2539 (not (equal last-command this-command
)))
2540 (allout-end-of-current-line)
2541 (let ((end-of-entry (save-excursion
2542 (allout-end-of-entry)
2545 (allout-end-of-current-line))
2546 ((or (allout-hidden-p) (save-excursion
2549 (allout-back-to-current-heading)
2550 (allout-show-current-entry)
2551 (allout-show-children)
2552 (allout-end-of-entry))
2553 ((>= (point) end-of-entry
)
2554 (allout-back-to-current-heading)
2555 (allout-end-of-current-line))
2557 (if (not (allout-mark-active-p))
2559 (allout-end-of-entry))))))
2560 ;;;_ > allout-mark-active-p ()
2561 (defun allout-mark-active-p ()
2562 "True if the mark is currently or always active."
2563 ;; `(cond (boundp...))' (or `(if ...)') invokes special byte-compiler
2564 ;; provisions, at least in fsf emacs to prevent warnings about lack of,
2565 ;; eg, region-active-p.
2566 (cond ((boundp 'mark-active
)
2568 ((fboundp 'region-active-p
)
2571 ;;;_ > allout-next-heading ()
2572 (defsubst allout-next-heading
()
2573 "Move to the heading for the topic (possibly invisible) after this one.
2575 Returns the location of the heading, or nil if none found.
2577 We skip anomalous low-level topics, a la `allout-aberrant-container-p'."
2580 (if (looking-at allout-regexp
)
2583 (when (re-search-forward allout-line-boundary-regexp nil
0)
2584 (allout-prefix-data)
2585 (goto-char allout-recent-prefix-beginning
)
2588 (and (allout-do-doublecheck)
2589 ;; this will set allout-recent-* on the first non-aberrant topic,
2590 ;; whether it's the current one or one that disqualifies it:
2591 (allout-aberrant-container-p))
2592 ;; this may or may not be the same as above depending on doublecheck:
2593 (goto-char allout-recent-prefix-beginning
))))
2594 ;;;_ > allout-this-or-next-heading
2595 (defun allout-this-or-next-heading ()
2596 "Position cursor on current or next heading."
2597 ;; A throwaway non-macro that is defined after allout-next-heading
2598 ;; and usable by allout-mode.
2599 (if (not (allout-goto-prefix-doublechecked)) (allout-next-heading)))
2600 ;;;_ > allout-previous-heading ()
2601 (defun allout-previous-heading ()
2602 "Move to the prior (possibly invisible) heading line.
2604 Return the location of the beginning of the heading, or nil if not found.
2606 We skip anomalous low-level topics, a la `allout-aberrant-container-p'."
2610 (let ((start-point (point)))
2611 ;; allout-goto-prefix-doublechecked calls us, so we can't use it here.
2612 (allout-goto-prefix)
2614 (when (or (re-search-backward allout-line-boundary-regexp nil
0)
2615 (looking-at allout-bob-regexp
))
2616 (goto-char (allout-prefix-data))
2617 (if (and (allout-do-doublecheck)
2618 (allout-aberrant-container-p))
2619 (or (allout-previous-heading)
2620 (and (goto-char start-point
)
2621 ;; recalibrate allout-recent-*:
2625 ;;;_ > allout-get-invisibility-overlay ()
2626 (defun allout-get-invisibility-overlay ()
2627 "Return the overlay at point that dictates allout invisibility."
2628 (let ((overlays (overlays-at (point)))
2630 (while (and overlays
(not got
))
2631 (if (equal (overlay-get (car overlays
) 'invisible
) 'allout
)
2632 (setq got
(car overlays
))
2635 ;;;_ > allout-back-to-visible-text ()
2636 (defun allout-back-to-visible-text ()
2637 "Move to most recent prior character that is visible, and return point."
2638 (if (allout-hidden-p)
2639 (goto-char (overlay-start (allout-get-invisibility-overlay))))
2642 ;;;_ - Subtree Charting
2643 ;;;_ " These routines either produce or assess charts, which are
2644 ;;; nested lists of the locations of topics within a subtree.
2646 ;;; Charts enable efficient subtree navigation by providing a reusable basis
2647 ;;; for elaborate, compound assessment and adjustment of a subtree.
2649 ;;;_ > allout-chart-subtree (&optional levels visible orig-depth prev-depth)
2650 (defun allout-chart-subtree (&optional levels visible orig-depth prev-depth
)
2651 "Produce a location \"chart\" of subtopics of the containing topic.
2653 Optional argument LEVELS specifies a depth limit (relative to start
2654 depth) for the chart. Null LEVELS means no limit.
2656 When optional argument VISIBLE is non-nil, the chart includes
2657 only the visible subelements of the charted subjects.
2659 The remaining optional args are for internal use by the function.
2661 Point is left at the end of the subtree.
2663 Charts are used to capture outline structure, so that outline-altering
2664 routines need assess the structure only once, and then use the chart
2665 for their elaborate manipulations.
2667 The chart entries for the topics are in reverse order, so the
2668 last topic is listed first. The entry for each topic consists of
2669 an integer indicating the point at the beginning of the topic
2670 prefix. Charts for offspring consists of a list containing,
2671 recursively, the charts for the respective subtopics. The chart
2672 for a topics' offspring precedes the entry for the topic itself.
2674 The other function parameters are for internal recursion, and should
2675 not be specified by external callers. ORIG-DEPTH is depth of topic at
2676 starting point, and PREV-DEPTH is depth of prior topic."
2678 (let ((original (not orig-depth
)) ; `orig-depth' set only in recursion.
2681 (if original
; Just starting?
2682 ; Register initial settings and
2683 ; position to first offspring:
2684 (progn (setq orig-depth
(allout-depth))
2685 (or prev-depth
(setq prev-depth
(1+ orig-depth
)))
2687 (allout-next-visible-heading 1)
2688 (allout-next-heading))))
2690 ;; Loop over the current levels' siblings. Besides being more
2691 ;; efficient than tail-recursing over a level, it avoids exceeding
2692 ;; the typically quite constrained Emacs max-lisp-eval-depth.
2694 ;; Probably would speed things up to implement loop-based stack
2695 ;; operation rather than recursing for lower levels. Bah.
2697 (while (and (not (eobp))
2698 ; Still within original topic?
2699 (< orig-depth
(setq curr-depth allout-recent-depth
))
2700 (cond ((= prev-depth curr-depth
)
2701 ;; Register this one and move on:
2702 (setq chart
(cons allout-recent-prefix-beginning chart
))
2703 (if (and levels
(<= levels
1))
2704 ;; At depth limit -- skip sublevels:
2705 (or (allout-next-sibling curr-depth
)
2706 ;; or no more siblings -- proceed to
2707 ;; next heading at lesser depth:
2708 (while (and (<= curr-depth
2709 allout-recent-depth
)
2711 (allout-next-visible-heading 1)
2712 (allout-next-heading)))))
2714 (allout-next-visible-heading 1)
2715 (allout-next-heading))))
2717 ((and (< prev-depth curr-depth
)
2720 ;; Recurse on deeper level of curr topic:
2722 (cons (allout-chart-subtree (and levels
2728 ;; ... then continue with this one.
2731 ;; ... else nil if we've ascended back to prev-depth.
2735 (if original
; We're at the last sibling on
2736 ; the original level. Position
2738 (progn (and (not (eobp)) (forward-char -
1))
2739 (and (= (preceding-char) ?
\n)
2740 (= (aref (buffer-substring (max 1 (- (point) 3))
2745 (setq allout-recent-end-of-subtree
(point))))
2747 chart
; (nreverse chart) not necessary,
2748 ; and maybe not preferable.
2750 ;;;_ > allout-chart-siblings (&optional start end)
2751 (defun allout-chart-siblings (&optional start end
)
2752 "Produce a list of locations of this and succeeding sibling topics.
2753 Effectively a top-level chart of siblings. See `allout-chart-subtree'
2754 for an explanation of charts."
2756 (when (allout-goto-prefix-doublechecked)
2757 (let ((chart (list (point))))
2758 (while (allout-next-sibling)
2759 (setq chart
(cons (point) chart
)))
2760 (if chart
(setq chart
(nreverse chart
)))))))
2761 ;;;_ > allout-chart-to-reveal (chart depth)
2762 (defun allout-chart-to-reveal (chart depth
)
2764 "Return a flat list of hidden points in subtree CHART, up to DEPTH.
2766 If DEPTH is nil, include hidden points at any depth.
2768 Note that point can be left at any of the points on chart, or at the
2772 (while (and (or (null depth
) (> depth
0))
2774 (setq here
(car chart
))
2776 (let ((further (allout-chart-to-reveal here
(if (null depth
)
2779 ;; We're on the start of a subtree -- recurse with it, if there's
2780 ;; more depth to go:
2781 (if further
(setq result
(append further result
)))
2782 (setq chart
(cdr chart
)))
2784 (if (allout-hidden-p)
2785 (setq result
(cons here result
)))
2786 (setq chart
(cdr chart
))))
2788 ;;;_ X allout-chart-spec (chart spec &optional exposing)
2789 ;; (defun allout-chart-spec (chart spec &optional exposing)
2790 ;; "Not yet (if ever) implemented.
2792 ;; Produce exposure directives given topic/subtree CHART and an exposure SPEC.
2794 ;; Exposure spec indicates the locations to be exposed and the prescribed
2795 ;; exposure status. Optional arg EXPOSING is an integer, with 0
2796 ;; indicating pending concealment, anything higher indicating depth to
2797 ;; which subtopic headers should be exposed, and negative numbers
2798 ;; indicating (negative of) the depth to which subtopic headers and
2799 ;; bodies should be exposed.
2801 ;; The produced list can have two types of entries. Bare numbers
2802 ;; indicate points in the buffer where topic headers that should be
2805 ;; - bare negative numbers indicates that the topic starting at the
2806 ;; point which is the negative of the number should be opened,
2807 ;; including their entries.
2808 ;; - bare positive values indicate that this topic header should be
2810 ;; - Lists signify the beginning and end points of regions that should
2811 ;; be flagged, and the flag to employ. (For concealment: `(\?r)', and
2814 ;; (cond ((listp spec)
2817 ;; (setq spec (cdr spec)))
2821 ;;;_ > allout-goto-prefix ()
2822 (defun allout-goto-prefix ()
2823 "Put point at beginning of immediately containing outline topic.
2825 Goes to most immediate subsequent topic if none immediately containing.
2827 Not sensitive to topic visibility.
2829 Returns the point at the beginning of the prefix, or nil if none."
2833 (while (and (not done
)
2834 (search-backward "\n" nil
1))
2836 (if (looking-at allout-regexp
)
2837 (setq done
(allout-prefix-data))
2840 (cond ((looking-at allout-regexp
)
2841 (allout-prefix-data))
2842 ((allout-next-heading))
2845 ;;;_ > allout-goto-prefix-doublechecked ()
2846 (defun allout-goto-prefix-doublechecked ()
2847 "Put point at beginning of immediately containing outline topic.
2849 Like `allout-goto-prefix', but shallow topics (according to
2850 `allout-doublecheck-at-and-shallower') are checked and
2851 disqualified for child containment discontinuity, according to
2852 `allout-aberrant-container-p'."
2853 (if (allout-goto-prefix)
2854 (if (and (allout-do-doublecheck)
2855 (allout-aberrant-container-p))
2856 (allout-previous-heading)
2859 ;;;_ > allout-end-of-prefix ()
2860 (defun allout-end-of-prefix (&optional ignore-decorations
)
2861 "Position cursor at beginning of header text.
2863 If optional IGNORE-DECORATIONS is non-nil, put just after bullet,
2864 otherwise skip white space between bullet and ensuing text."
2866 (if (not (allout-goto-prefix-doublechecked))
2868 (goto-char allout-recent-prefix-end
)
2870 (if ignore-decorations
2872 (while (looking-at "[0-9]") (forward-char 1))
2873 (if (and (not (eolp)) (looking-at "\\s-")) (forward-char 1))))
2874 ;; Reestablish where we are:
2875 (allout-current-depth)))
2876 ;;;_ > allout-current-bullet-pos ()
2877 (defun allout-current-bullet-pos ()
2878 "Return position of current (visible) topic's bullet."
2880 (if (not (allout-current-depth))
2882 (1- allout-recent-prefix-end
)))
2883 ;;;_ > allout-back-to-current-heading (&optional interactive)
2884 (defun allout-back-to-current-heading (&optional interactive
)
2885 "Move to heading line of current topic, or beginning if not in a topic.
2887 If interactive, we position at the end of the prefix.
2889 Return value of resulting point, unless we started outside
2890 of (before any) topics, in which case we return nil."
2894 (allout-beginning-of-current-line)
2895 (let ((bol-point (point)))
2896 (when (allout-goto-prefix-doublechecked)
2897 (if (<= (point) bol-point
)
2899 (setq bol-point
(point))
2900 (allout-beginning-of-current-line)
2901 (if (not (= bol-point
(point)))
2902 (if (looking-at allout-regexp
)
2903 (allout-prefix-data)))
2905 (allout-end-of-prefix)
2907 (goto-char (point-min))
2909 ;;;_ > allout-back-to-heading ()
2910 (defalias 'allout-back-to-heading
'allout-back-to-current-heading
)
2911 ;;;_ > allout-pre-next-prefix ()
2912 (defun allout-pre-next-prefix ()
2913 "Skip forward to just before the next heading line.
2915 Returns that character position."
2917 (if (allout-next-heading)
2918 (goto-char (1- allout-recent-prefix-beginning
))))
2919 ;;;_ > allout-end-of-subtree (&optional current include-trailing-blank)
2920 (defun allout-end-of-subtree (&optional current include-trailing-blank
)
2921 "Put point at the end of the last leaf in the containing topic.
2923 Optional CURRENT means put point at the end of the containing
2926 Optional INCLUDE-TRAILING-BLANK means include a trailing blank line, if
2927 any, as part of the subtree. Otherwise, that trailing blank will be
2928 excluded as delimiting whitespace between topics.
2930 Returns the value of point."
2933 (allout-back-to-current-heading)
2934 (allout-goto-prefix-doublechecked))
2935 (let ((level allout-recent-depth
))
2936 (allout-next-heading)
2937 (while (and (not (eobp))
2938 (> allout-recent-depth level
))
2939 (allout-next-heading))
2941 (allout-end-of-entry)
2943 (if (and (not include-trailing-blank
) (= ?
\n (preceding-char)))
2945 (setq allout-recent-end-of-subtree
(point))))
2946 ;;;_ > allout-end-of-current-subtree (&optional include-trailing-blank)
2947 (defun allout-end-of-current-subtree (&optional include-trailing-blank
)
2949 "Put point at end of last leaf in currently visible containing topic.
2951 Optional INCLUDE-TRAILING-BLANK means include a trailing blank line, if
2952 any, as part of the subtree. Otherwise, that trailing blank will be
2953 excluded as delimiting whitespace between topics.
2955 Returns the value of point."
2957 (allout-end-of-subtree t include-trailing-blank
))
2958 ;;;_ > allout-beginning-of-current-entry (&optional interactive)
2959 (defun allout-beginning-of-current-entry (&optional interactive
)
2960 "When not already there, position point at beginning of current topic header.
2962 If already there, move cursor to bullet for hot-spot operation.
2963 \(See `allout-mode' doc string for details of hot-spot operation.)"
2965 (let ((start-point (point)))
2966 (move-beginning-of-line 1)
2967 (if (< 0 (allout-current-depth))
2968 (goto-char allout-recent-prefix-end
)
2969 (goto-char (point-min)))
2970 (allout-end-of-prefix)
2971 (if (and interactive
2972 (= (point) start-point
))
2973 (goto-char (allout-current-bullet-pos)))))
2974 ;;;_ > allout-end-of-entry (&optional inclusive)
2975 (defun allout-end-of-entry (&optional inclusive
)
2976 "Position the point at the end of the current topics' entry.
2978 Optional INCLUSIVE means also include trailing empty line, if any. When
2979 unset, whitespace between items separates them even when the items are
2982 (allout-pre-next-prefix)
2983 (if (and (not inclusive
) (not (bobp)) (= ?
\n (preceding-char)))
2986 ;;;_ > allout-end-of-current-heading ()
2987 (defun allout-end-of-current-heading ()
2989 (allout-beginning-of-current-entry)
2990 (search-forward "\n" nil t
)
2992 (defalias 'allout-end-of-heading
'allout-end-of-current-heading
)
2993 ;;;_ > allout-get-body-text ()
2994 (defun allout-get-body-text ()
2995 "Return the unmangled body text of the topic immediately containing point."
2997 (allout-end-of-prefix)
2998 (if (not (search-forward "\n" nil t
))
3001 (let ((pre-body (point)))
3004 (allout-end-of-entry t
)
3005 (if (not (= pre-body
(point)))
3006 (buffer-substring-no-properties (1+ pre-body
) (point))))
3013 ;;;_ > allout-ascend-to-depth (depth)
3014 (defun allout-ascend-to-depth (depth)
3015 "Ascend to depth DEPTH, returning depth if successful, nil if not."
3016 (if (and (> depth
0)(<= depth
(allout-depth)))
3017 (let (last-ascended)
3018 (while (and (< depth allout-recent-depth
)
3019 (setq last-ascended
(allout-ascend))))
3020 (goto-char allout-recent-prefix-beginning
)
3021 (if (allout-called-interactively-p) (allout-end-of-prefix))
3022 (and last-ascended allout-recent-depth
))))
3023 ;;;_ > allout-ascend (&optional dont-move-if-unsuccessful)
3024 (defun allout-ascend (&optional dont-move-if-unsuccessful
)
3025 "Ascend one level, returning resulting depth if successful, nil if not.
3027 Point is left at the beginning of the level whether or not
3028 successful, unless optional DONT-MOVE-IF-UNSUCCESSFUL is set, in
3029 which case point is returned to its original starting location."
3030 (if dont-move-if-unsuccessful
3031 (setq dont-move-if-unsuccessful
(point)))
3033 (if (allout-beginning-of-level)
3034 (let ((bolevel (point))
3035 (bolevel-depth allout-recent-depth
))
3036 (allout-previous-heading)
3037 (cond ((< allout-recent-depth bolevel-depth
)
3038 allout-recent-depth
)
3039 ((= allout-recent-depth bolevel-depth
)
3040 (if dont-move-if-unsuccessful
3041 (goto-char dont-move-if-unsuccessful
))
3045 ;; some topic after very first is lower depth than first:
3049 (if (allout-called-interactively-p) (allout-end-of-prefix))))
3050 ;;;_ > allout-descend-to-depth (depth)
3051 (defun allout-descend-to-depth (depth)
3052 "Descend to depth DEPTH within current topic.
3054 Returning depth if successful, nil if not."
3055 (let ((start-point (point))
3056 (start-depth (allout-depth)))
3058 (and (> (allout-depth) 0)
3059 (not (= depth allout-recent-depth
)) ; ... not there yet
3060 (allout-next-heading) ; ... go further
3061 (< start-depth allout-recent-depth
))) ; ... still in topic
3062 (if (and (> (allout-depth) 0)
3063 (= allout-recent-depth depth
))
3065 (goto-char start-point
)
3068 ;;;_ > allout-up-current-level (arg)
3069 (defun allout-up-current-level (arg)
3070 "Move out ARG levels from current visible topic."
3072 (let ((start-point (point)))
3073 (allout-back-to-current-heading)
3074 (if (not (allout-ascend))
3075 (progn (goto-char start-point
)
3076 (error "Can't ascend past outermost level"))
3077 (if (allout-called-interactively-p) (allout-end-of-prefix))
3078 allout-recent-prefix-beginning
)))
3081 ;;;_ > allout-next-sibling (&optional depth backward)
3082 (defun allout-next-sibling (&optional depth backward
)
3083 "Like `allout-forward-current-level', but respects invisible topics.
3085 Traverse at optional DEPTH, or current depth if none specified.
3087 Go backward if optional arg BACKWARD is non-nil.
3089 Return the start point of the new topic if successful, nil otherwise."
3091 (if (if backward
(bobp) (eobp))
3093 (let ((target-depth (or depth
(allout-depth)))
3094 (start-point (point))
3095 (start-prefix-beginning allout-recent-prefix-beginning
)
3100 ;; done too few single steps to resort to the leap routine:
3103 (not (if backward
(bobp) (eobp)))
3104 ;; still traversable:
3105 (if backward
(allout-previous-heading) (allout-next-heading))
3106 ;; we're below the target depth
3107 (> (setq last-depth allout-recent-depth
) target-depth
))
3108 (setq count
(1+ count
))
3109 (if (> count
7) ; lists are commonly 7 +- 2, right?-)
3112 (or (allout-next-sibling-leap target-depth backward
)
3114 (goto-char start-point
)
3115 (if depth
(allout-depth) target-depth
)
3118 (and (> (or last-depth
(allout-depth)) 0)
3119 (= allout-recent-depth target-depth
))
3120 (not (= start-prefix-beginning
3121 allout-recent-prefix-beginning
)))
3122 allout-recent-prefix-beginning
)
3124 (goto-char start-point
)
3125 (if depth
(allout-depth) target-depth
)
3127 ;;;_ > allout-next-sibling-leap (&optional depth backward)
3128 (defun allout-next-sibling-leap (&optional depth backward
)
3129 "Like `allout-next-sibling', but by direct search for topic at depth.
3131 Traverse at optional DEPTH, or current depth if none specified.
3133 Go backward if optional arg BACKWARD is non-nil.
3135 Return the start point of the new topic if successful, nil otherwise.
3137 Costs more than regular `allout-next-sibling' for short traversals:
3139 - we have to check the prior (next, if travelling backwards)
3140 item to confirm connectivity with the prior topic, and
3141 - if confirmed, we have to reestablish the allout-recent-* settings with
3142 some extra navigation
3143 - if confirmation fails, we have to do more work to recover
3145 It is an increasingly big win when there are many intervening
3146 offspring before the next sibling, however, so
3147 `allout-next-sibling' resorts to this if it finds itself in that
3150 (if (if backward
(bobp) (eobp))
3152 (let* ((start-point (point))
3153 (target-depth (or depth
(allout-depth)))
3154 (search-whitespace-regexp nil
)
3155 (depth-biased (- target-depth
2))
3156 (expression (if (<= target-depth
1)
3157 allout-depth-one-regexp
3158 (format allout-depth-specific-regexp
3159 depth-biased depth-biased
)))
3163 (setq found
(save-match-data
3165 (re-search-backward expression nil
'to-limit
)
3167 (re-search-forward expression nil
'to-limit
))))
3168 (if (and found
(allout-aberrant-container-p))
3170 (setq done
(or found
(if backward
(bobp) (eobp)))))
3172 (progn (goto-char start-point
)
3174 ;; rationale: if any intervening items were at a lower depth, we
3175 ;; would now be on the first offspring at the target depth -- ie,
3176 ;; the preceeding item (per the search direction) must be at a
3177 ;; lesser depth. that's all we need to check.
3178 (if backward
(allout-next-heading) (allout-previous-heading))
3179 (if (< allout-recent-depth target-depth
)
3180 ;; return to start and reestablish allout-recent-*:
3182 (goto-char start-point
)
3186 ;; locate cursor and set allout-recent-*:
3187 (allout-goto-prefix))))))
3188 ;;;_ > allout-previous-sibling (&optional depth backward)
3189 (defun allout-previous-sibling (&optional depth backward
)
3190 "Like `allout-forward-current-level' backwards, respecting invisible topics.
3192 Optional DEPTH specifies depth to traverse, default current depth.
3194 Optional BACKWARD reverses direction.
3196 Return depth if successful, nil otherwise."
3197 (allout-next-sibling depth
(not backward
))
3199 ;;;_ > allout-snug-back ()
3200 (defun allout-snug-back ()
3201 "Position cursor at end of previous topic.
3203 Presumes point is at the start of a topic prefix."
3204 (if (or (bobp) (eobp))
3207 (if (or (bobp) (not (= ?
\n (preceding-char))))
3211 ;;;_ > allout-beginning-of-level ()
3212 (defun allout-beginning-of-level ()
3213 "Go back to the first sibling at this level, visible or not."
3214 (allout-end-of-level 'backward
))
3215 ;;;_ > allout-end-of-level (&optional backward)
3216 (defun allout-end-of-level (&optional backward
)
3217 "Go to the last sibling at this level, visible or not."
3219 (let ((depth (allout-depth)))
3220 (while (allout-previous-sibling depth nil
))
3221 (prog1 allout-recent-depth
3222 (if (allout-called-interactively-p) (allout-end-of-prefix)))))
3223 ;;;_ > allout-next-visible-heading (arg)
3224 (defun allout-next-visible-heading (arg)
3225 "Move to the next ARG'th visible heading line, backward if arg is negative.
3227 Move to buffer limit in indicated direction if headings are exhausted."
3230 (let* ((inhibit-field-text-motion t
)
3231 (backward (if (< arg
0) (setq arg
(* -
1 arg
))))
3232 (step (if backward -
1 1))
3233 (progress (allout-current-bullet-pos))
3238 ;; Boundary condition:
3239 (not (if backward
(bobp)(eobp)))
3240 ;; Move, skipping over all concealed lines in one fell swoop:
3241 (prog1 (condition-case nil
(or (line-move step
) t
)
3243 (allout-beginning-of-current-line)
3244 ;; line-move can wind up on the same line if long.
3245 ;; when moving forward, that would yield no-progress
3246 (when (and (not backward
)
3247 (<= (point) progress
))
3248 ;; ensure progress by doing line-move from end-of-line:
3250 (condition-case nil
(or (line-move step
) t
)
3252 (allout-beginning-of-current-line)
3253 (setq progress
(point))))
3254 ;; Deal with apparent header line:
3256 (if (not (looking-at allout-regexp
))
3257 ;; not a header line, keep looking:
3259 (allout-prefix-data)
3260 (if (and (allout-do-doublecheck)
3261 (allout-aberrant-container-p))
3262 ;; skip this aberrant prospective header line:
3264 ;; this prospective headerline qualifies -- register:
3265 (setq got allout-recent-prefix-beginning
)
3266 ;; and break the loop:
3268 ;; Register this got, it may be the last:
3269 (if got
(setq prev got
))
3270 (setq arg
(1- arg
)))
3271 (cond (got ; Last move was to a prefix:
3272 (allout-end-of-prefix))
3273 (prev ; Last move wasn't, but prev was:
3275 (allout-end-of-prefix))
3276 ((not backward
) (end-of-line) nil
))))
3277 ;;;_ > allout-previous-visible-heading (arg)
3278 (defun allout-previous-visible-heading (arg)
3279 "Move to the previous heading line.
3281 With argument, repeats or can move forward if negative.
3282 A heading line is one that starts with a `*' (or that `allout-regexp'
3285 (prog1 (allout-next-visible-heading (- arg
))
3286 (if (allout-called-interactively-p) (allout-end-of-prefix))))
3287 ;;;_ > allout-forward-current-level (arg)
3288 (defun allout-forward-current-level (arg)
3289 "Position point at the next heading of the same level.
3291 Takes optional repeat-count, goes backward if count is negative.
3293 Returns resulting position, else nil if none found."
3295 (let ((start-depth (allout-current-depth))
3297 (backward (> 0 arg
)))
3298 (if (= 0 start-depth
)
3299 (error "No siblings, not in a topic..."))
3300 (if backward
(setq arg
(* -
1 arg
)))
3301 (allout-back-to-current-heading)
3302 (while (and (not (zerop arg
))
3304 (allout-previous-sibling)
3305 (allout-next-sibling)))
3306 (setq arg
(1- arg
)))
3307 (if (not (allout-called-interactively-p))
3309 (allout-end-of-prefix)
3310 (if (not (zerop arg
))
3311 (error "Hit %s level %d topic, traversed %d of %d requested"
3312 (if backward
"first" "last")
3314 (- (abs start-arg
) arg
)
3315 (abs start-arg
))))))
3316 ;;;_ > allout-backward-current-level (arg)
3317 (defun allout-backward-current-level (arg)
3318 "Inverse of `allout-forward-current-level'."
3320 (if (allout-called-interactively-p)
3321 (let ((current-prefix-arg (* -
1 arg
)))
3322 (call-interactively 'allout-forward-current-level
))
3323 (allout-forward-current-level (* -
1 arg
))))
3328 ;;;_ = allout-post-goto-bullet
3329 (defvar allout-post-goto-bullet nil
3330 "Outline internal var, for `allout-pre-command-business' hot-spot operation.
3332 When set, tells post-processing to reposition on topic bullet, and
3333 then unset it. Set by `allout-pre-command-business' when implementing
3334 hot-spot operation, where literal characters typed over a topic bullet
3335 are mapped to the command of the corresponding control-key on the
3336 `allout-mode-map-value'.")
3337 (make-variable-buffer-local 'allout-post-goto-bullet
)
3338 ;;;_ = allout-command-counter
3339 (defvar allout-command-counter
0
3340 "Counter that monotonically increases in allout-mode buffers.
3342 Set by `allout-pre-command-business', to support allout addons in
3343 coordinating with allout activity.")
3344 (make-variable-buffer-local 'allout-command-counter
)
3345 ;;;_ > allout-post-command-business ()
3346 (defun allout-post-command-business ()
3347 "Outline `post-command-hook' function.
3349 - Implement (and clear) `allout-post-goto-bullet', for hot-spot
3352 - Decrypt topic currently being edited if it was encrypted for a save."
3354 ; Apply any external change func:
3355 (if (not (allout-mode-p)) ; In allout-mode.
3358 (if (and (boundp 'allout-after-save-decrypt
)
3359 allout-after-save-decrypt
)
3360 (allout-after-saves-handler))
3362 ;; Implement allout-post-goto-bullet, if set:
3363 (if (and allout-post-goto-bullet
3364 (allout-current-bullet-pos))
3365 (progn (goto-char (allout-current-bullet-pos))
3366 (setq allout-post-goto-bullet nil
)))
3368 ;;;_ > allout-pre-command-business ()
3369 (defun allout-pre-command-business ()
3370 "Outline `pre-command-hook' function for outline buffers.
3372 Among other things, implements special behavior when the cursor is on the
3373 topic bullet character.
3375 When the cursor is on the bullet character, self-insert
3376 characters are reinterpreted as the corresponding
3377 control-character in the `allout-mode-map-value'. The
3378 `allout-mode' `post-command-hook' insures that the cursor which
3379 has moved as a result of such reinterpretation is positioned on
3380 the bullet character of the destination topic.
3382 The upshot is that you can get easy, single (ie, unmodified) key
3383 outline maneuvering operations by positioning the cursor on the bullet
3384 char. When in this mode you can use regular cursor-positioning
3385 command/keystrokes to relocate the cursor off of a bullet character to
3386 return to regular interpretation of self-insert characters."
3388 (if (not (allout-mode-p))
3390 ;; Increment allout-command-counter
3391 (setq allout-command-counter
(1+ allout-command-counter
))
3392 ;; Do hot-spot navigation.
3393 (if (and (eq this-command
'self-insert-command
)
3394 (eq (point)(allout-current-bullet-pos)))
3395 (allout-hotspot-key-handler))))
3396 ;;;_ > allout-hotspot-key-handler ()
3397 (defun allout-hotspot-key-handler ()
3398 "Catchall handling of key bindings in hot-spots.
3400 Translates unmodified keystrokes to corresponding allout commands, when
3401 they would qualify if prefixed with the allout-command-prefix, and sets
3402 this-command accordingly.
3404 Returns the qualifying command, if any, else nil."
3406 (let* ((modified (event-modifiers last-command-event
))
3407 (key-num (cond ((numberp last-command-event
) last-command-event
)
3408 ;; for XEmacs character type:
3409 ((and (fboundp 'characterp
)
3410 (apply 'characterp
(list last-command-event
)))
3411 (apply 'char-to-int
(list last-command-event
)))
3419 ;; exclude control chars and escape:
3422 (setq mapped-binding
3424 ;; try control-modified versions of keys:
3425 (key-binding (vconcat allout-command-prefix
3427 (if (and (<= 97 key-num
) ; "a"
3428 (>= 122 key-num
)) ; "z"
3429 (- key-num
96) key-num
)))
3431 ;; try non-modified versions of keys:
3432 (key-binding (vconcat allout-command-prefix
3435 ;; Qualified as an allout command -- do hot-spot operation.
3436 (setq allout-post-goto-bullet t
)
3437 ;; accept-defaults nil, or else we get allout-item-icon-key-handler.
3438 (setq mapped-binding
(key-binding (vector key-num
))))
3440 (while (keymapp mapped-binding
)
3441 (setq mapped-binding
3442 (lookup-key mapped-binding
(vector (read-char)))))
3444 (when mapped-binding
3445 (setq this-command mapped-binding
)))))
3447 ;;;_ > allout-find-file-hook ()
3448 (defun allout-find-file-hook ()
3449 "Activate `allout-mode' on non-nil `allout-auto-activation', `allout-layout'.
3451 See `allout-init' for setup instructions."
3452 (if (and allout-auto-activation
3453 (not (allout-mode-p))
3457 ;;;_ - Topic Format Assessment
3458 ;;;_ > allout-solicit-alternate-bullet (depth &optional current-bullet)
3459 (defun allout-solicit-alternate-bullet (depth &optional current-bullet
)
3461 "Prompt for and return a bullet char as an alternative to the current one.
3463 Offer one suitable for current depth DEPTH as default."
3465 (let* ((default-bullet (or (and (stringp current-bullet
) current-bullet
)
3466 (allout-bullet-for-depth depth
)))
3467 (sans-escapes (regexp-sans-escapes allout-bullets-string
))
3470 (goto-char (allout-current-bullet-pos))
3471 (setq choice
(solicit-char-in-string
3472 (format "Select bullet: %s ('%s' default): "
3474 (allout-substring-no-properties default-bullet
))
3478 (if (string= choice
"") default-bullet choice
))
3480 ;;;_ > allout-distinctive-bullet (bullet)
3481 (defun allout-distinctive-bullet (bullet)
3482 "True if BULLET is one of those on `allout-distinctive-bullets-string'."
3483 (string-match (regexp-quote bullet
) allout-distinctive-bullets-string
))
3484 ;;;_ > allout-numbered-type-prefix (&optional prefix)
3485 (defun allout-numbered-type-prefix (&optional prefix
)
3486 "True if current header prefix bullet is numbered bullet."
3487 (and allout-numbered-bullet
3488 (string= allout-numbered-bullet
3490 (allout-get-prefix-bullet prefix
)
3491 (allout-get-bullet)))))
3492 ;;;_ > allout-encrypted-type-prefix (&optional prefix)
3493 (defun allout-encrypted-type-prefix (&optional prefix
)
3494 "True if current header prefix bullet is for an encrypted entry (body)."
3495 (and allout-topic-encryption-bullet
3496 (string= allout-topic-encryption-bullet
3498 (allout-get-prefix-bullet prefix
)
3499 (allout-get-bullet)))))
3500 ;;;_ > allout-bullet-for-depth (&optional depth)
3501 (defun allout-bullet-for-depth (&optional depth
)
3502 "Return outline topic bullet suited to optional DEPTH, or current depth."
3503 ;; Find bullet in plain-bullets-string modulo DEPTH.
3504 (if allout-stylish-prefixes
3505 (char-to-string (aref allout-plain-bullets-string
3506 (%
(max 0 (- depth
2))
3507 allout-plain-bullets-string-len
)))
3508 allout-primary-bullet
)
3511 ;;;_ - Topic Production
3512 ;;;_ > allout-make-topic-prefix (&optional prior-bullet
3513 (defun allout-make-topic-prefix (&optional prior-bullet
3519 ;; Depth null means use current depth, non-null means we're either
3520 ;; opening a new topic after current topic, lower or higher, or we're
3521 ;; changing level of current topic.
3522 ;; Solicit dominates specified bullet-char.
3524 "Generate a topic prefix suitable for optional arg DEPTH, or current depth.
3526 All the arguments are optional.
3528 PRIOR-BULLET indicates the bullet of the prefix being changed, or
3529 nil if none. This bullet may be preserved (other options
3530 notwithstanding) if it is on the `allout-distinctive-bullets-string',
3533 Second arg NEW indicates that a new topic is being opened after the
3534 topic at point, if non-nil. Default bullet for new topics, eg, may
3535 be set (contingent to other args) to numbered bullets if previous
3536 sibling is one. The implication otherwise is that the current topic
3537 is being adjusted -- shifted or rebulleted -- and we don't consider
3538 bullet or previous sibling.
3540 Third arg DEPTH forces the topic prefix to that depth, regardless of
3541 the current topics' depth.
3543 If SOLICIT is non-nil, then the choice of bullet is solicited from
3544 user. If it's a character, then that character is offered as the
3545 default, otherwise the one suited to the context (according to
3546 distinction or depth) is offered. (This overrides other options,
3547 including, eg, a distinctive PRIOR-BULLET.) If non-nil, then the
3548 context-specific bullet is used.
3550 Fifth arg, NUMBER-CONTROL, matters only if `allout-numbered-bullet'
3551 is non-nil *and* soliciting was not explicitly invoked. Then
3552 NUMBER-CONTROL non-nil forces prefix to either numbered or
3553 denumbered format, depending on the value of the sixth arg, INDEX.
3555 \(Note that NUMBER-CONTROL does *not* apply to level 1 topics. Sorry...)
3557 If NUMBER-CONTROL is non-nil and sixth arg INDEX is non-nil then
3558 the prefix of the topic is forced to be numbered. Non-nil
3559 NUMBER-CONTROL and nil INDEX forces non-numbered format on the
3560 bullet. Non-nil NUMBER-CONTROL and non-nil, non-number INDEX means
3561 that the index for the numbered prefix will be derived, by counting
3562 siblings back to start of level. If INDEX is a number, then that
3563 number is used as the index for the numbered prefix (allowing, eg,
3564 sequential renumbering to not require this function counting back the
3565 index for each successive sibling)."
3567 ;; The options are ordered in likely frequence of use, most common
3568 ;; highest, least lowest. Ie, more likely to be doing prefix
3569 ;; adjustments than soliciting, and yet more than numbering.
3570 ;; Current prefix is least dominant, but most likely to be commonly
3576 (depth (or depth
(allout-depth)))
3577 (header-lead allout-header-prefix
)
3580 ;; Getting value for bullet char is practically the whole job:
3583 ; Simplest situation -- level 1:
3584 ((<= depth
1) (setq header-lead
"") allout-primary-bullet
)
3585 ; Simple, too: all asterisks:
3586 (allout-old-style-prefixes
3587 ;; Cheat -- make body the whole thing, null out header-lead and
3589 (setq body
(make-string depth
3590 (string-to-char allout-primary-bullet
)))
3591 (setq header-lead
"")
3594 ;; (Neither level 1 nor old-style, so we're space padding.
3595 ;; Sneak it in the condition of the next case, whatever it is.)
3597 ;; Solicitation overrides numbering and other cases:
3598 ((progn (setq body
(make-string (- depth
2) ?\
))
3599 ;; The actual condition:
3601 (let* ((got (allout-solicit-alternate-bullet depth solicit
)))
3602 ;; Gotta check whether we're numbering and got a numbered bullet:
3603 (setq numbering
(and allout-numbered-bullet
3604 (not (and number-control
(not index
)))
3605 (string= got allout-numbered-bullet
)))
3606 ;; Now return what we got, regardless:
3609 ;; Numbering invoked through args:
3610 ((and allout-numbered-bullet number-control
)
3611 (if (setq numbering
(not (setq denumbering
(not index
))))
3612 allout-numbered-bullet
3613 (if (and prior-bullet
3614 (not (string= allout-numbered-bullet
3617 (allout-bullet-for-depth depth
))))
3619 ;;; Neither soliciting nor controlled numbering ;;;
3620 ;;; (may be controlled denumbering, tho) ;;;
3622 ;; Check wrt previous sibling:
3623 ((and new
; only check for new prefixes
3624 (<= depth
(allout-depth))
3625 allout-numbered-bullet
; ... & numbering enabled
3627 (let ((sibling-bullet
3629 ;; Locate correct sibling:
3630 (or (>= depth
(allout-depth))
3631 (allout-ascend-to-depth depth
))
3632 (allout-get-bullet))))
3633 (if (and sibling-bullet
3634 (string= allout-numbered-bullet sibling-bullet
))
3635 (setq numbering sibling-bullet
)))))
3637 ;; Distinctive prior bullet?
3639 (allout-distinctive-bullet prior-bullet
)
3640 ;; Either non-numbered:
3641 (or (not (and allout-numbered-bullet
3642 (string= prior-bullet allout-numbered-bullet
)))
3643 ;; or numbered, and not denumbering:
3644 (setq numbering
(not denumbering
)))
3648 ;; Else, standard bullet per depth:
3649 ((allout-bullet-for-depth depth
)))))
3655 (format "%d" (cond ((and index
(numberp index
)) index
)
3656 (new (1+ (allout-sibling-index depth
)))
3657 ((allout-sibling-index))))))
3660 ;;;_ > allout-open-topic (relative-depth &optional before offer-recent-bullet)
3661 (defun allout-open-topic (relative-depth &optional before offer-recent-bullet
)
3662 "Open a new topic at depth DEPTH.
3664 New topic is situated after current one, unless optional flag BEFORE
3665 is non-nil, or unless current line is completely empty -- lacking even
3666 whitespace -- in which case open is done on the current line.
3668 When adding an offspring, it will be added immediately after the parent if
3669 the other offspring are exposed, or after the last child if the offspring
3670 are hidden. (The intervening offspring will be exposed in the latter
3673 If OFFER-RECENT-BULLET is true, offer to use the bullet of the prior sibling.
3677 - Creation of new topics is with respect to the visible topic
3678 containing the cursor, regardless of intervening concealed ones.
3680 - New headers are generally created after/before the body of a
3681 topic. However, they are created right at cursor location if the
3682 cursor is on a blank line, even if that breaks the current topic
3683 body. This is intentional, to provide a simple means for
3684 deliberately dividing topic bodies.
3686 - Double spacing of topic lists is preserved. Also, the first
3687 level two topic is created double-spaced (and so would be
3688 subsequent siblings, if that's left intact). Otherwise,
3689 single-spacing is used.
3691 - Creation of sibling or nested topics is with respect to the topic
3692 you're starting from, even when creating backwards. This way you
3693 can easily create a sibling in front of the current topic without
3694 having to go to its preceding sibling, and then open forward
3697 (allout-beginning-of-current-line)
3699 (let* ((inhibit-field-text-motion t
)
3700 (depth (+ (allout-current-depth) relative-depth
))
3701 (opening-on-blank (if (looking-at "^\$")
3702 (not (setq before nil
))))
3703 ;; bunch o vars set while computing ref-topic
3707 (ref-topic (save-excursion
3708 (cond ((< relative-depth
0)
3709 (allout-ascend-to-depth depth
))
3710 ((>= relative-depth
1) nil
)
3711 (t (allout-back-to-current-heading)))
3712 (setq ref-depth allout-recent-depth
)
3714 (if (> allout-recent-prefix-end
1)
3715 (allout-recent-bullet)
3717 (setq opening-numbered
3719 (and allout-numbered-bullet
3720 (or (<= relative-depth
0)
3721 (allout-descend-to-depth depth
))
3722 (if (allout-numbered-type-prefix)
3723 allout-numbered-bullet
))))
3729 (if (not opening-on-blank
)
3730 ; Positioning and vertical
3731 ; padding -- only if not
3734 (goto-char ref-topic
)
3735 (setq dbl-space
; Determine double space action:
3736 (or (and (<= relative-depth
0) ; not descending;
3738 ;; at b-o-b or preceded by a blank line?
3739 (or (> 0 (forward-line -
1))
3740 (looking-at "^\\s-*$")
3743 ;; succeeded by a blank line?
3744 (allout-end-of-current-subtree)
3745 (looking-at "\n\n")))
3746 (and (= ref-depth
1)
3750 ;; Don't already have following
3751 ;; vertical padding:
3752 (not (allout-pre-next-prefix)))))))
3754 ;; Position to prior heading, if inserting backwards, and not
3756 (if (and before
(>= relative-depth
0))
3757 (progn (allout-back-to-current-heading)
3758 (setq doing-beginning
(bobp))
3760 (allout-previous-heading)))
3761 (if (and before
(bobp))
3764 (if (<= relative-depth
0)
3765 ;; Not going inwards, don't snug up:
3771 (progn (end-of-line)
3772 (allout-pre-next-prefix)
3773 (while (and (= ?
\n (following-char))
3778 (if (not (looking-at "^$"))
3780 (allout-end-of-current-subtree)
3781 (if (looking-at "\n\n") (forward-char 1))))
3782 ;; Going inwards -- double-space if first offspring is
3783 ;; double-spaced, otherwise snug up.
3784 (allout-end-of-entry)
3788 (allout-beginning-of-current-line)
3791 ;; Blank lines between current header body and next
3792 ;; header -- get to last substantive (non-white-space)
3794 (progn (setq dbl-space t
)
3795 (re-search-backward "[^ \t\n]" nil t
)))
3796 (if (looking-at "\n\n")
3799 (allout-next-heading)
3800 (when (> allout-recent-depth ref-depth
)
3801 ;; This is an offspring.
3803 (looking-at "^\\s-*$")))
3804 (progn (forward-line 1)
3807 (allout-end-of-current-line))
3809 ;;(if doing-beginning (goto-char doing-beginning))
3811 ;; We insert a newline char rather than using open-line to
3812 ;; avoid rear-stickiness inheritence of read-only property.
3813 (progn (if (and (not (> depth ref-depth
))
3816 (if (and (not dbl-space
) (> depth ref-depth
))
3822 (if (and dbl-space
(not (> relative-depth
0)))
3824 (if (and (not (eobp))
3827 ;; bolp doesnt detect concealed
3828 ;; trailing newlines, compensate:
3831 (allout-hidden-p)))))
3834 (setq start
(point))
3835 (insert (concat (allout-make-topic-prefix opening-numbered t depth
)
3837 (setq end
(1+ (point)))
3839 (allout-rebullet-heading (and offer-recent-bullet ref-bullet
)
3841 (if (> relative-depth
0)
3842 (save-excursion (goto-char ref-topic
)
3843 (allout-show-children)))
3846 (run-hook-with-args 'allout-structure-added-hook start end
)
3850 ;;;_ > allout-open-subtopic (arg)
3851 (defun allout-open-subtopic (arg)
3852 "Open new topic header at deeper level than the current one.
3854 Negative universal arg means to open deeper, but place the new topic
3855 prior to the current one."
3857 (allout-open-topic 1 (> 0 arg
) (< 1 arg
)))
3858 ;;;_ > allout-open-sibtopic (arg)
3859 (defun allout-open-sibtopic (arg)
3860 "Open new topic header at same level as the current one.
3862 Positive universal arg means to use the bullet of the prior sibling.
3864 Negative universal arg means to place the new topic prior to the current
3867 (allout-open-topic 0 (> 0 arg
) (not (= 1 arg
))))
3868 ;;;_ > allout-open-supertopic (arg)
3869 (defun allout-open-supertopic (arg)
3870 "Open new topic header at shallower level than the current one.
3872 Negative universal arg means to open shallower, but place the new
3873 topic prior to the current one."
3876 (allout-open-topic -
1 (> 0 arg
) (< 1 arg
)))
3878 ;;;_ - Outline Alteration
3879 ;;;_ : Topic Modification
3880 ;;;_ = allout-former-auto-filler
3881 (defvar allout-former-auto-filler nil
3882 "Name of modal fill function being wrapped by `allout-auto-fill'.")
3883 ;;;_ > allout-auto-fill ()
3884 (defun allout-auto-fill ()
3885 "`allout-mode' autofill function.
3887 Maintains outline hanging topic indentation if
3888 `allout-use-hanging-indents' is set."
3890 (when (not allout-inhibit-auto-fill
)
3891 (let ((fill-prefix (if allout-use-hanging-indents
3892 ;; Check for topic header indentation:
3896 (if (looking-at allout-regexp
)
3897 ;; ... construct indentation to account for
3898 ;; length of topic prefix:
3899 (make-string (progn (allout-end-of-prefix)
3902 (use-auto-fill-function
3903 (if (and (eq allout-outside-normal-auto-fill-function
3905 (eq auto-fill-function
'allout-auto-fill
))
3907 (or allout-outside-normal-auto-fill-function
3908 auto-fill-function
))))
3909 (if (or allout-former-auto-filler allout-use-hanging-indents
)
3910 (funcall use-auto-fill-function
)))))
3911 ;;;_ > allout-reindent-body (old-depth new-depth &optional number)
3912 (defun allout-reindent-body (old-depth new-depth
&optional number
)
3913 "Reindent body lines which were indented at OLD-DEPTH to NEW-DEPTH.
3915 Optional arg NUMBER indicates numbering is being added, and it must
3918 Note that refill of indented paragraphs is not done."
3921 (allout-end-of-prefix)
3922 (let* ((new-margin (current-column))
3923 excess old-indent-begin old-indent-end
3924 ;; We want the column where the header-prefix text started
3925 ;; *before* the prefix was changed, so we infer it relative
3926 ;; to the new margin and the shift in depth:
3927 (old-margin (+ old-depth
(- new-margin new-depth
))))
3929 ;; Process lines up to (but excluding) next topic header:
3933 (and (re-search-forward "\n\\(\\s-*\\)"
3936 ;; Register the indent data, before we reset the
3937 ;; match data with a subsequent `looking-at':
3938 (setq old-indent-begin
(match-beginning 1)
3939 old-indent-end
(match-end 1))
3940 (not (looking-at allout-regexp
)))
3941 (if (> 0 (setq excess
(- (- old-indent-end old-indent-begin
)
3943 ;; Text starts left of old margin -- don't adjust:
3945 ;; Text was hanging at or right of old left margin --
3946 ;; reindent it, preserving its existing indentation
3947 ;; beyond the old margin:
3948 (delete-region old-indent-begin old-indent-end
)
3949 (indent-to (+ new-margin excess
(current-column))))))))))
3950 ;;;_ > allout-rebullet-current-heading (arg)
3951 (defun allout-rebullet-current-heading (arg)
3952 "Solicit new bullet for current visible heading."
3954 (let ((initial-col (current-column))
3955 (on-bullet (eq (point)(allout-current-bullet-pos)))
3957 (backwards (if (< arg
0)
3958 (setq arg
(* arg -
1)))))
3960 (save-excursion (allout-back-to-current-heading)
3961 (allout-end-of-prefix)
3962 (setq from allout-recent-prefix-beginning
3963 to allout-recent-prefix-end
)
3964 (allout-rebullet-heading t
;;; solicit
3966 nil
;;; number-control
3968 t
) ;;; do-successors
3969 (run-hook-with-args 'allout-exposure-change-hook
3974 (setq initial-col nil
) ; Override positioning back to init col
3976 (allout-next-visible-heading 1)
3977 (allout-goto-prefix-doublechecked)
3978 (allout-next-visible-heading -
1))))
3980 (cond (on-bullet (goto-char (allout-current-bullet-pos)))
3981 (initial-col (move-to-column initial-col
)))))
3982 ;;;_ > allout-rebullet-heading (&optional solicit ...)
3983 (defun allout-rebullet-heading (&optional solicit
3989 "Adjust bullet of current topic prefix.
3991 All args are optional.
3993 If SOLICIT is non-nil, then the choice of bullet is solicited from
3994 user. If it's a character, then that character is offered as the
3995 default, otherwise the one suited to the context (according to
3996 distinction or depth) is offered. If non-nil, then the
3997 context-specific bullet is just used.
3999 Second arg DEPTH forces the topic prefix to that depth, regardless
4000 of the topic's current depth.
4002 Third arg NUMBER-CONTROL can force the prefix to or away from
4003 numbered form. It has effect only if `allout-numbered-bullet' is
4004 non-nil and soliciting was not explicitly invoked (via first arg).
4005 Its effect, numbering or denumbering, then depends on the setting
4006 of the fourth arg, INDEX.
4008 If NUMBER-CONTROL is non-nil and fourth arg INDEX is nil, then the
4009 prefix of the topic is forced to be non-numbered. Null index and
4010 non-nil NUMBER-CONTROL forces denumbering. Non-nil INDEX (and
4011 non-nil NUMBER-CONTROL) forces a numbered-prefix form. If non-nil
4012 INDEX is a number, then that number is used for the numbered
4013 prefix. Non-nil and non-number means that the index for the
4014 numbered prefix will be derived by allout-make-topic-prefix.
4016 Fifth arg DO-SUCCESSORS t means re-resolve count on succeeding
4019 Cf vars `allout-stylish-prefixes', `allout-old-style-prefixes',
4020 and `allout-numbered-bullet', which all affect the behavior of
4023 (let* ((current-depth (allout-depth))
4024 (new-depth (or new-depth current-depth
))
4025 (mb allout-recent-prefix-beginning
)
4026 (me allout-recent-prefix-end
)
4027 (current-bullet (buffer-substring-no-properties (- me
1) me
))
4028 (has-annotation (get-text-property mb
'allout-was-hidden
))
4029 (new-prefix (allout-make-topic-prefix current-bullet
4036 ;; Is new one is identical to old?
4037 (if (and (= current-depth new-depth
)
4038 (string= current-bullet
4039 (substring new-prefix
(1- (length new-prefix
)))))
4043 ;; New prefix probably different from old:
4044 ; get rid of old one:
4045 (allout-unprotected (delete-region mb me
))
4047 ; Dispense with number if
4048 ; numbered-bullet prefix:
4050 (if (and allout-numbered-bullet
4051 (string= allout-numbered-bullet current-bullet
)
4052 (looking-at "[0-9]+"))
4054 (delete-region (match-beginning 0)(match-end 0)))))
4056 ;; convey 'allout-was-hidden annotation, if original had it:
4058 (put-text-property 0 (length new-prefix
) 'allout-was-hidden t
4061 ; Put in new prefix:
4062 (allout-unprotected (insert new-prefix
))
4064 ;; Reindent the body if elected, margin changed, and not encrypted body:
4065 (if (and allout-reindent-bodies
4066 (not (= new-depth current-depth
))
4067 (not (allout-encrypted-topic-p)))
4068 (allout-reindent-body current-depth new-depth
))
4070 ;; Recursively rectify successive siblings of orig topic if
4071 ;; caller elected for it:
4074 (while (allout-next-sibling new-depth nil
)
4076 (cond ((numberp index
) (1+ index
))
4077 ((not number-control
) (allout-sibling-index))))
4078 (if (allout-numbered-type-prefix)
4079 (allout-rebullet-heading nil
;;; solicit
4080 new-depth
;;; new-depth
4081 number-control
;;; number-control
4083 nil
))))) ;;;(dont!)do-successors
4084 ) ; (if (and (= current-depth new-depth)...))
4085 ) ; let* ((current-depth (allout-depth))...)
4087 ;;;_ > allout-rebullet-topic (arg)
4088 (defun allout-rebullet-topic (arg &optional sans-offspring
)
4089 "Rebullet the visible topic containing point and all contained subtopics.
4091 Descends into invisible as well as visible topics, however.
4093 When optional SANS-OFFSPRING is non-nil, subtopics are not
4094 shifted. (Shifting a topic outwards without shifting its
4095 offspring is disallowed, since this would create a \"containment
4096 discontinuity\", where the depth difference between a topic and
4097 its immediate offspring is greater than one.)
4099 With repeat count, shift topic depth by that amount."
4101 (let ((start-col (current-column)))
4104 (cond ((null arg
) (setq arg
0))
4105 ((listp arg
) (setq arg
(car arg
))))
4106 ;; Fill the user in, in case we're shifting a big topic:
4107 (if (not (zerop arg
)) (message "Shifting..."))
4108 (allout-back-to-current-heading)
4109 (if (<= (+ allout-recent-depth arg
) 0)
4110 (error "Attempt to shift topic below level 1"))
4111 (allout-rebullet-topic-grunt arg nil nil nil nil sans-offspring
)
4112 (if (not (zerop arg
)) (message "Shifting... done.")))
4113 (move-to-column (max 0 (+ start-col arg
)))))
4114 ;;;_ > allout-rebullet-topic-grunt (&optional relative-depth ...)
4115 (defun allout-rebullet-topic-grunt (&optional relative-depth
4121 "Like `allout-rebullet-topic', but on nearest containing topic
4124 See `allout-rebullet-heading' for rebulleting behavior.
4126 All arguments are optional.
4128 First arg RELATIVE-DEPTH means to shift the depth of the entire
4131 Several subsequent args are for internal recursive use by the function
4132 itself: STARTING-DEPTH, STARTING-POINT, and INDEX.
4134 Finally, if optional SANS-OFFSPRING is non-nil then the offspring
4135 are not shifted. (Shifting a topic outwards without shifting
4136 its offspring is disallowed, since this would create a
4137 \"containment discontinuity\", where the depth difference between
4138 a topic and its immediate offspring is greater than one.)"
4140 ;; XXX the recursion here is peculiar, and in general the routine may
4141 ;; need simplification with refactoring.
4143 (if (and sans-offspring
4145 (< relative-depth
0))
4146 (error (concat "Attempt to shift topic outwards without offspring,"
4147 " would cause containment discontinuity.")))
4149 (let* ((relative-depth (or relative-depth
0))
4150 (new-depth (allout-depth))
4151 (starting-depth (or starting-depth new-depth
))
4152 (on-starting-call (null starting-point
))
4154 ;; Leave index null on starting call, so rebullet-heading
4155 ;; calculates it at what might be new depth:
4156 (and (or (zerop relative-depth
)
4157 (not on-starting-call
))
4158 (allout-sibling-index))))
4159 (starting-index index
)
4160 (moving-outwards (< 0 relative-depth
))
4161 (starting-point (or starting-point
(point)))
4162 (local-point (point)))
4164 ;; Sanity check for excessive promotion done only on starting call:
4165 (and on-starting-call
4167 (> 0 (+ starting-depth relative-depth
))
4168 (error "Attempt to shift topic out beyond level 1"))
4170 (cond ((= starting-depth new-depth
)
4171 ;; We're at depth to work on this one.
4173 ;; When shifting out we work on the children before working on
4174 ;; the parent to avoid interim `allout-aberrant-container-p'
4175 ;; aberrancy, and vice-versa when shifting in:
4176 (if (>= relative-depth
0)
4177 (allout-rebullet-heading nil
4178 (+ starting-depth relative-depth
)
4181 nil
)) ;;; do-successors
4182 (when (not sans-offspring
)
4183 ;; ... and work on subsequent ones which are at greater depth:
4185 (allout-next-heading)
4186 (while (and (not (eobp))
4187 (< starting-depth
(allout-depth)))
4188 (setq index
(1+ index
))
4189 (allout-rebullet-topic-grunt relative-depth
4193 (when (< relative-depth
0)
4195 (goto-char local-point
)
4196 (allout-rebullet-heading nil
;;; solicit
4197 (+ starting-depth relative-depth
)
4200 nil
)))) ;;; do-successors
4202 ((< starting-depth new-depth
)
4203 ;; Rare case -- subtopic more than one level deeper than parent.
4204 ;; Treat this one at an even deeper level:
4205 (allout-rebullet-topic-grunt relative-depth
4211 (if on-starting-call
4213 ;; Rectify numbering of former siblings of the adjusted topic,
4214 ;; if topic has changed depth
4215 (if (or do-successors
4216 (and (not (zerop relative-depth
))
4217 (or (= allout-recent-depth starting-depth
)
4218 (= allout-recent-depth
(+ starting-depth
4220 (allout-rebullet-heading nil nil nil nil t
))
4221 ;; Now rectify numbering of new siblings of the adjusted topic,
4222 ;; if depth has been changed:
4223 (progn (goto-char starting-point
)
4224 (if (not (zerop relative-depth
))
4225 (allout-rebullet-heading nil nil nil nil t
)))))
4228 ;;;_ > allout-renumber-to-depth (&optional depth)
4229 (defun allout-renumber-to-depth (&optional depth
)
4230 "Renumber siblings at current depth.
4232 Affects superior topics if optional arg DEPTH is less than current depth.
4234 Returns final depth."
4236 ;; Proceed by level, processing subsequent siblings on each,
4237 ;; ascending until we get shallower than the start depth:
4239 (let ((ascender (allout-depth))
4241 (while (and (not (eobp))
4243 (>= allout-recent-depth depth
)
4244 (>= ascender depth
))
4245 ; Skip over all topics at
4246 ; lesser depths, which can not
4247 ; have been disturbed:
4248 (while (and (not (setq was-eobp
(eobp)))
4249 (> allout-recent-depth ascender
))
4250 (allout-next-heading))
4251 ; Prime ascender for ascension:
4252 (setq ascender
(1- allout-recent-depth
))
4253 (if (>= allout-recent-depth depth
)
4254 (allout-rebullet-heading nil
;;; solicit
4256 nil
;;; number-control
4258 t
)) ;;; do-successors
4259 (if was-eobp
(goto-char (point-max)))))
4260 allout-recent-depth
)
4261 ;;;_ > allout-number-siblings (&optional denumber)
4262 (defun allout-number-siblings (&optional denumber
)
4263 "Assign numbered topic prefix to this topic and its siblings.
4265 With universal argument, denumber -- assign default bullet to this
4266 topic and its siblings.
4268 With repeated universal argument (`^U^U'), solicit bullet for each
4269 rebulleting each topic at this level."
4274 (allout-back-to-current-heading)
4275 (allout-beginning-of-level)
4276 (let ((depth allout-recent-depth
)
4277 (index (if (not denumber
) 1))
4278 (use-bullet (equal '(16) denumber
))
4281 (allout-rebullet-heading use-bullet
;;; solicit
4283 t
;;; number-control
4285 nil
) ;;; do-successors
4286 (if index
(setq index
(1+ index
)))
4287 (setq more
(allout-next-sibling depth nil
))))))
4288 ;;;_ > allout-shift-in (arg)
4289 (defun allout-shift-in (arg)
4290 "Increase depth of current heading and any items collapsed within it.
4292 With a negative argument, the item is shifted out using
4293 `allout-shift-out', instead.
4295 With an argument greater than one, shift-in the item but not its
4296 offspring, making the item into a sibling of its former children,
4297 and a child of sibling that formerly preceeded it.
4299 You are not allowed to shift the first offspring of a topic
4300 inwards, because that would yield a \"containment
4301 discontinuity\", where the depth difference between a topic and
4302 its immediate offspring is greater than one. The first topic in
4303 the file can be adjusted to any positive depth, however."
4307 (allout-shift-out (* arg -
1))
4308 ;; refuse to create a containment discontinuity:
4310 (allout-back-to-current-heading)
4312 (let* ((current-depth allout-recent-depth
)
4313 (start-point (point))
4314 (predecessor-depth (progn
4316 (allout-goto-prefix-doublechecked)
4317 (if (< (point) start-point
)
4320 (if (and (> predecessor-depth
0)
4321 (> (1+ current-depth
)
4322 (1+ predecessor-depth
)))
4323 (error (concat "Disallowed shift deeper than"
4324 " containing topic's children."))
4325 (allout-back-to-current-heading)
4326 (if (< allout-recent-depth
(1+ current-depth
))
4327 (allout-show-children))))))
4328 (let ((where (point)))
4329 (allout-rebullet-topic 1 (and (> arg
1) 'sans-offspring
))
4330 (run-hook-with-args 'allout-structure-shifted-hook arg where
))))
4331 ;;;_ > allout-shift-out (arg)
4332 (defun allout-shift-out (arg)
4333 "Decrease depth of current heading and any topics collapsed within it.
4334 This will make the item a sibling of its former container.
4336 With a negative argument, the item is shifted in using
4337 `allout-shift-in', instead.
4339 With an argument greater than one, shift-out the item's offspring
4340 but not the item itself, making the former children siblings of
4343 With an argument greater than 1, the item's offspring are shifted
4344 out without shifting the item. This will make the immediate
4345 subtopics into siblings of the item."
4348 (allout-shift-in (* arg -
1))
4349 ;; Get proper exposure in this area:
4350 (save-excursion (if (allout-ascend)
4351 (allout-show-children)))
4352 ;; Show collapsed children if there's a successor which will become
4354 (if (and (allout-current-topic-collapsed-p)
4355 (save-excursion (allout-next-sibling)))
4356 (allout-show-children))
4357 (let ((where (and (allout-depth) allout-recent-prefix-beginning
)))
4360 ;; Shift the offspring but not the topic:
4361 (let ((children-chart (allout-chart-subtree 1)))
4362 (if (listp (car children-chart
))
4364 (setq children-chart
(allout-flatten children-chart
)))
4366 (dolist (child-point children-chart
)
4367 (goto-char child-point
)
4368 (allout-shift-out 1))))
4369 (allout-rebullet-topic (* arg -
1))))
4370 (run-hook-with-args 'allout-structure-shifted-hook
(* arg -
1) where
))))
4371 ;;;_ : Surgery (kill-ring) functions with special provisions for outlines:
4372 ;;;_ > allout-kill-line (&optional arg)
4373 (defun allout-kill-line (&optional arg
)
4374 "Kill line, adjusting subsequent lines suitably for outline mode."
4378 (if (or (not (allout-mode-p))
4380 (not (save-match-data (looking-at allout-regexp
))))
4381 ;; Just do a regular kill:
4383 ;; Ah, have to watch out for adjustments:
4384 (let* ((beg (point))
4386 (beg-hidden (allout-hidden-p))
4387 (end-hidden (save-excursion (allout-end-of-current-line)
4390 (depth (allout-depth)))
4392 (allout-annotate-hidden beg end
)
4394 (if (and (not beg-hidden
) (not end-hidden
))
4395 (allout-unprotected (kill-line arg
))
4397 (run-hook-with-args 'allout-after-copy-or-kill-hook beg end
)
4398 (allout-deannotate-hidden beg end
)
4400 (if allout-numbered-bullet
4401 (save-excursion ; Renumber subsequent topics if needed:
4402 (if (not (save-match-data (looking-at allout-regexp
)))
4403 (allout-next-heading))
4404 (allout-renumber-to-depth depth
)))
4405 (run-hook-with-args 'allout-structure-deleted-hook depth
(point))))))
4406 ;;;_ > allout-copy-line-as-kill ()
4407 (defun allout-copy-line-as-kill ()
4408 "Like allout-kill-topic, but save to kill ring instead of deleting."
4410 (let ((buffer-read-only t
))
4413 (buffer-read-only nil
))))
4414 ;;;_ > allout-kill-topic ()
4415 (defun allout-kill-topic ()
4416 "Kill topic together with subtopics.
4418 Trailing whitespace is killed with a topic if that whitespace:
4420 - would separate the topic from a subsequent sibling
4421 - would separate the topic from the end of buffer
4422 - would not be added to whitespace already separating the topic from the
4425 Topic exposure is marked with text-properties, to be used by
4426 `allout-yank-processing' for exposure recovery."
4429 (let* ((inhibit-field-text-motion t
)
4430 (beg (prog1 (allout-back-to-current-heading) (beginning-of-line)))
4432 (depth allout-recent-depth
))
4433 (allout-end-of-current-subtree)
4434 (if (and (/= (current-column) 0) (not (eobp)))
4437 (if (and (save-match-data (looking-at "\n"))
4439 (or (not (allout-next-heading))
4440 (= depth allout-recent-depth
)))
4441 (and (> (- beg
(point-min)) 3)
4442 (string= (buffer-substring (- beg
2) beg
) "\n\n"))))
4445 (allout-annotate-hidden beg
(setq end
(point)))
4446 (unwind-protect ; for possible barf-if-buffer-read-only.
4447 (allout-unprotected (kill-region beg end
))
4448 (allout-deannotate-hidden beg end
)
4449 (run-hook-with-args 'allout-after-copy-or-kill-hook beg end
)
4452 (allout-renumber-to-depth depth
))
4453 (run-hook-with-args 'allout-structure-deleted-hook depth
(point)))))
4454 ;;;_ > allout-copy-topic-as-kill ()
4455 (defun allout-copy-topic-as-kill ()
4456 "Like `allout-kill-topic', but save to kill ring instead of deleting."
4458 (let ((buffer-read-only t
))
4461 (buffer-read-only (message "Topic copied...")))))
4462 ;;;_ > allout-annotate-hidden (begin end)
4463 (defun allout-annotate-hidden (begin end
)
4464 "Qualify text with properties to indicate exposure status."
4466 (let ((was-modified (buffer-modified-p))
4467 (buffer-read-only nil
))
4468 (allout-deannotate-hidden begin end
)
4471 (let (done next prev overlay
)
4473 ;; at or advance to start of next hidden region:
4474 (if (not (allout-hidden-p))
4477 (allout-next-single-char-property-change (point)
4480 (if (or (not next
) (eq prev next
))
4481 ;; still not at start of hidden area -- must not be any left.
4485 (if (not (allout-hidden-p))
4486 ;; still not at start of hidden area.
4488 (setq overlay
(allout-get-invisibility-overlay))
4489 (setq next
(overlay-end overlay
)
4491 ;; advance to end of this hidden area:
4495 (let ((buffer-undo-list t
))
4496 (put-text-property (overlay-start overlay
) next
4497 'allout-was-hidden t
)))))))))
4498 (set-buffer-modified-p was-modified
)))
4499 ;;;_ > allout-deannotate-hidden (begin end)
4500 (defun allout-deannotate-hidden (begin end
)
4501 "Remove allout hidden-text annotation between BEGIN and END."
4504 (let ((inhibit-read-only t
)
4505 (buffer-undo-list t
))
4506 (remove-text-properties begin end
'(allout-was-hidden t
)))))
4507 ;;;_ > allout-hide-by-annotation (begin end)
4508 (defun allout-hide-by-annotation (begin end
)
4509 "Translate text properties indicating exposure status into actual exposure."
4512 (let ((was-modified (buffer-modified-p))
4515 ;; at or advance to start of next annotation:
4516 (if (not (get-text-property (point) 'allout-was-hidden
))
4517 (setq next
(allout-next-single-char-property-change
4518 (point) 'allout-was-hidden nil end
)))
4519 (if (or (not next
) (eq prev next
))
4520 ;; no more or not advancing -- must not be any left.
4524 (if (not (get-text-property (point) 'allout-was-hidden
))
4525 ;; still not at start of annotation.
4527 ;; advance to just after end of this annotation:
4528 (setq next
(allout-next-single-char-property-change
4529 (point) 'allout-was-hidden nil end
))
4530 (overlay-put (make-overlay prev next nil
'front-advance
)
4531 'category
'allout-exposure-category
)
4532 (allout-deannotate-hidden prev next
)
4534 (if next
(goto-char next
)))))
4535 (set-buffer-modified-p was-modified
))))
4536 ;;;_ > allout-yank-processing ()
4537 (defun allout-yank-processing (&optional arg
)
4539 "Incidental allout-specific business to be done just after text yanks.
4541 Does depth adjustment of yanked topics, when:
4543 1 the stuff being yanked starts with a valid outline header prefix, and
4544 2 it is being yanked at the end of a line which consists of only a valid
4547 Also, adjusts numbering of subsequent siblings when appropriate.
4549 Depth adjustment alters the depth of all the topics being yanked
4550 the amount it takes to make the first topic have the depth of the
4551 header into which it's being yanked.
4553 The point is left in front of yanked, adjusted topics, rather than
4554 at the end (and vice-versa with the mark). Non-adjusted yanks,
4555 however, are left exactly like normal, non-allout-specific yanks."
4558 ; Get to beginning, leaving
4559 ; region around subject:
4560 (if (< (allout-mark-marker t
) (point))
4561 (exchange-point-and-mark))
4563 (let* ((subj-beg (point))
4565 (subj-end (allout-mark-marker t
))
4566 ;; 'resituate' if yanking an entire topic into topic header:
4567 (resituate (and (let ((allout-inhibit-aberrance-doublecheck t
))
4568 (allout-e-o-prefix-p))
4569 (looking-at allout-regexp
)
4570 (allout-prefix-data)))
4571 ;; `rectify-numbering' if resituating (where several topics may
4572 ;; be resituating) or yanking a topic into a topic slot (bol):
4573 (rectify-numbering (or resituate
4574 (and into-bol
(looking-at allout-regexp
)))))
4576 ;; Yanking a topic into the start of a topic -- reconcile to fit:
4577 (let* ((inhibit-field-text-motion t
)
4578 (prefix-len (if (not (match-end 1))
4580 (- (match-end 1) subj-beg
)))
4581 (subj-depth allout-recent-depth
)
4582 (prefix-bullet (allout-recent-bullet))
4584 ;; Nil if adjustment unnecessary, otherwise depth to which
4585 ;; adjustment should be made:
4587 (and (goto-char subj-end
)
4589 (goto-char subj-beg
)
4590 (and (looking-at allout-regexp
)
4593 (not (= (point) subj-beg
)))
4594 (looking-at allout-regexp
)
4595 (allout-prefix-data))
4596 allout-recent-depth
)))
4598 (setq rectify-numbering allout-numbered-bullet
)
4600 ; Do the adjustment:
4603 (narrow-to-region subj-beg subj-end
)
4604 ; Trim off excessive blank
4605 ; line at end, if any:
4606 (goto-char (point-max))
4607 (if (looking-at "^$")
4608 (allout-unprotected (delete-char -
1)))
4609 ; Work backwards, with each
4611 ; successively excluding the
4612 ; last processed topic from
4613 ; the narrow region:
4615 (allout-back-to-current-heading)
4616 ; go as high as we can in each bunch:
4617 (while (allout-ascend t
))
4620 (allout-rebullet-topic-grunt (- adjust-to-depth
4623 (if (setq more
(not (bobp)))
4626 (narrow-to-region subj-beg
(point))))))
4627 ;; Preserve new bullet if it's a distinctive one, otherwise
4629 (if (string-match (regexp-quote prefix-bullet
)
4630 allout-distinctive-bullets-string
)
4631 ; Delete from bullet of old to
4632 ; before bullet of new:
4636 (delete-region (point) subj-beg
))
4637 (set-marker (allout-mark-marker t
) subj-end
)
4638 (goto-char subj-beg
)
4639 (allout-end-of-prefix))
4640 ; Delete base subj prefix,
4644 (delete-region (point) (+ (point)
4648 ; and delete residual subj
4649 ; prefix digits and space:
4650 (while (looking-at "[0-9]") (delete-char 1))
4651 (if (looking-at " ")
4652 (delete-char 1))))))
4653 (exchange-point-and-mark))))
4654 (if rectify-numbering
4657 ; Give some preliminary feedback:
4658 (message "... reconciling numbers")
4659 ; ... and renumber, in case necessary:
4660 (goto-char subj-beg
)
4661 (if (allout-goto-prefix-doublechecked)
4663 (allout-rebullet-heading nil
;;; solicit
4664 (allout-depth) ;;; depth
4665 nil
;;; number-control
4669 (if (or into-bol resituate
)
4670 (allout-hide-by-annotation (point) (allout-mark-marker t
))
4671 (allout-deannotate-hidden (allout-mark-marker t
) (point)))
4673 (exchange-point-and-mark))
4674 (run-hook-with-args 'allout-structure-added-hook subj-beg subj-end
))))
4675 ;;;_ > allout-yank (&optional arg)
4676 (defun allout-yank (&optional arg
)
4677 "`allout-mode' yank, with depth and numbering adjustment of yanked topics.
4679 Non-topic yanks work no differently than normal yanks.
4681 If a topic is being yanked into a bare topic prefix, the depth of the
4682 yanked topic is adjusted to the depth of the topic prefix.
4684 1 we're yanking in an `allout-mode' buffer
4685 2 the stuff being yanked starts with a valid outline header prefix, and
4686 3 it is being yanked at the end of a line which consists of only a valid
4689 If these conditions hold then the depth of the yanked topics are all
4690 adjusted the amount it takes to make the first one at the depth of the
4691 header into which it's being yanked.
4693 The point is left in front of yanked, adjusted topics, rather than
4694 at the end (and vice-versa with the mark). Non-adjusted yanks,
4695 however, (ones that don't qualify for adjustment) are handled
4696 exactly like normal yanks.
4698 Numbering of yanked topics, and the successive siblings at the depth
4699 into which they're being yanked, is adjusted.
4701 `allout-yank-pop' works with `allout-yank' just like normal `yank-pop'
4702 works with normal `yank' in non-outline buffers."
4705 (setq this-command
'yank
)
4709 (allout-yank-processing)))
4710 ;;;_ > allout-yank-pop (&optional arg)
4711 (defun allout-yank-pop (&optional arg
)
4712 "Yank-pop like `allout-yank' when popping to bare outline prefixes.
4714 Adapts level of popped topics to level of fresh prefix.
4716 Note -- prefix changes to distinctive bullets will stick, if followed
4717 by pops to non-distinctive yanks. Bug..."
4720 (setq this-command
'yank
)
4723 (allout-yank-processing)))
4725 ;;;_ - Specialty bullet functions
4726 ;;;_ : File Cross references
4727 ;;;_ > allout-resolve-xref ()
4728 (defun allout-resolve-xref ()
4729 "Pop to file associated with current heading, if it has an xref bullet.
4731 \(Works according to setting of `allout-file-xref-bullet')."
4733 (if (not allout-file-xref-bullet
)
4735 "Outline cross references disabled -- no `allout-file-xref-bullet'")
4736 (if (not (string= (allout-current-bullet) allout-file-xref-bullet
))
4737 (error "Current heading lacks cross-reference bullet `%s'"
4738 allout-file-xref-bullet
)
4739 (let ((inhibit-field-text-motion t
)
4743 (let* ((text-start allout-recent-prefix-end
)
4744 (heading-end (point-at-eol)))
4745 (goto-char text-start
)
4747 (if (re-search-forward "\\s-\\(\\S-*\\)" heading-end t
)
4748 (buffer-substring (match-beginning 1)
4750 (setq file-name
(expand-file-name file-name
))
4751 (if (or (file-exists-p file-name
)
4752 (if (file-writable-p file-name
)
4753 (y-or-n-p (format "%s not there, create one? "
4755 (error "%s not found and can't be created" file-name
)))
4756 (condition-case failure
4757 (find-file-other-window file-name
)
4759 (error "%s not found" file-name
))
4765 ;;;_ #6 Exposure Control
4768 ;;;_ > allout-flag-region (from to flag)
4769 (defun allout-flag-region (from to flag
)
4770 "Conceal text between FROM and TO if FLAG is non-nil, else reveal it.
4772 Exposure-change hook `allout-exposure-change-hook' is run with the same
4773 arguments as this function, after the exposure changes are made."
4775 ;; We use outline invisibility spec.
4776 (remove-overlays from to
'category
'allout-exposure-category
)
4778 (let ((o (make-overlay from to nil
'front-advance
)))
4779 (overlay-put o
'category
'allout-exposure-category
)
4780 (when (featurep 'xemacs
)
4781 (let ((props (symbol-plist 'allout-exposure-category
)))
4784 ;; as of 2008-02-27, xemacs lacks modification-hooks
4785 (overlay-put o
(pop props
) (pop props
))
4787 (run-hook-with-args 'allout-exposure-change-hook from to flag
))
4788 ;;;_ > allout-flag-current-subtree (flag)
4789 (defun allout-flag-current-subtree (flag)
4790 "Conceal currently-visible topic's subtree if FLAG non-nil, else reveal it."
4793 (allout-back-to-current-heading)
4794 (let ((inhibit-field-text-motion t
))
4796 (allout-flag-region (point)
4797 ;; Exposing must not leave trailing blanks hidden,
4798 ;; but can leave them exposed when hiding, so we
4799 ;; can use flag's inverse as the
4800 ;; include-trailing-blank cue:
4801 (allout-end-of-current-subtree (not flag
))
4804 ;;;_ - Topic-specific
4805 ;;;_ > allout-show-entry ()
4806 (defun allout-show-entry ()
4807 "Like `allout-show-current-entry', but reveals entries in hidden topics.
4809 This is a way to give restricted peek at a concealed locality without the
4810 expense of exposing its context, but can leave the outline with aberrant
4811 exposure. `allout-show-offshoot' should be used after the peek to rectify
4817 (allout-goto-prefix-doublechecked)
4818 (setq beg
(if (allout-hidden-p) (1- (point)) (point)))
4819 (setq end
(allout-pre-next-prefix))
4820 (allout-flag-region beg end nil
)
4822 ;;;_ > allout-show-children (&optional level strict)
4823 (defun allout-show-children (&optional level strict
)
4825 "If point is visible, show all direct subheadings of this heading.
4827 Otherwise, do `allout-show-to-offshoot', and then show subheadings.
4829 Optional LEVEL specifies how many levels below the current level
4830 should be shown, or all levels if t. Default is 1.
4832 Optional STRICT means don't resort to -show-to-offshoot, no matter
4833 what. This is basically so -show-to-offshoot, which is called by
4834 this function, can employ the pure offspring-revealing capabilities of
4837 Returns point at end of subtree that was opened, if any. (May get a
4838 point of non-opened subtree?)"
4841 (let ((start-point (point)))
4842 (if (and (not strict
)
4845 (progn (allout-show-to-offshoot) ; Point's concealed, open to
4847 ;; Then recurse, but with "strict" set so we don't
4848 ;; infinite regress:
4849 (allout-show-children level t
))
4852 (allout-beginning-of-current-line)
4855 ;; translate the level spec for this routine to the ones
4856 ;; used by -chart-subtree and -chart-to-reveal:
4857 (chart-level (cond ((not level
) 1)
4860 (chart (allout-chart-subtree chart-level
))
4861 (to-reveal (or (allout-chart-to-reveal chart chart-level
)
4862 ;; interactive, show discontinuous children:
4864 (allout-called-interactively-p)
4866 (allout-back-to-current-heading)
4867 (setq depth
(allout-current-depth))
4868 (and (allout-next-heading)
4869 (> allout-recent-depth
4872 "Discontinuous offspring; use `%s %s'%s."
4873 (substitute-command-keys
4874 "\\[universal-argument]")
4875 (substitute-command-keys
4876 "\\[allout-shift-out]")
4877 " to elevate them.")
4878 (allout-chart-to-reveal
4879 chart
(- allout-recent-depth depth
))))))
4880 (goto-char start-point
)
4881 (when (and strict
(allout-hidden-p))
4882 ;; Concealed root would already have been taken care of,
4883 ;; unless strict was set.
4884 (allout-flag-region (point) (allout-snug-back) nil
)
4885 (when allout-show-bodies
4886 (goto-char (car to-reveal
))
4887 (allout-show-current-entry)))
4889 (goto-char (car to-reveal
))
4890 (allout-flag-region (save-excursion (allout-snug-back) (point))
4891 (progn (search-forward "\n" nil t
)
4894 (when allout-show-bodies
4895 (goto-char (car to-reveal
))
4896 (allout-show-current-entry))
4897 (setq to-reveal
(cdr to-reveal
)))))))
4898 ;; Compensate for `save-excursion's maintenance of point
4899 ;; within invisible text:
4900 (goto-char start-point
)))
4901 ;;;_ > allout-show-to-offshoot ()
4902 (defun allout-show-to-offshoot ()
4903 "Like `allout-show-entry', but reveals all concealed ancestors, as well.
4905 Useful for coherently exposing to a random point in a hidden region."
4908 (let ((inhibit-field-text-motion t
)
4910 (orig-pref (allout-goto-prefix-doublechecked))
4913 (while (or (> bag-it
1) (allout-hidden-p))
4914 (while (allout-hidden-p)
4915 (move-beginning-of-line 1)
4916 (if (allout-hidden-p) (forward-char -
1)))
4917 (if (= last-at
(setq last-at
(point)))
4918 ;; Oops, we're not making any progress! Show the current topic
4919 ;; completely, and try one more time here, if we haven't already.
4920 (progn (beginning-of-line)
4921 (allout-show-current-subtree)
4923 (setq bag-it
(1+ bag-it
))
4925 (error "allout-show-to-offshoot: %s"
4926 "Stumped by aberrant nesting.")))
4927 (if (> bag-it
0) (setq bag-it
0))
4928 (allout-show-children)
4929 (goto-char orig-pref
)))
4930 (goto-char orig-pt
)))
4931 (if (allout-hidden-p)
4932 (allout-show-entry)))
4933 ;;;_ > allout-hide-current-entry ()
4934 (defun allout-hide-current-entry ()
4935 "Hide the body directly following this heading."
4937 (allout-back-to-current-heading)
4939 (let ((inhibit-field-text-motion t
))
4941 (allout-flag-region (point)
4942 (progn (allout-end-of-entry) (point))
4944 ;;;_ > allout-show-current-entry (&optional arg)
4945 (defun allout-show-current-entry (&optional arg
)
4946 "Show body following current heading, or hide entry with universal argument."
4950 (allout-hide-current-entry)
4951 (save-excursion (allout-show-to-offshoot))
4953 (allout-flag-region (point)
4954 (progn (allout-end-of-entry t
) (point))
4957 ;;;_ > allout-show-current-subtree (&optional arg)
4958 (defun allout-show-current-subtree (&optional arg
)
4959 "Show everything within the current topic.
4960 With a repeat-count, expose this topic and its siblings."
4963 (if (<= (allout-current-depth) 0)
4964 ;; Outside any topics -- try to get to the first:
4965 (if (not (allout-next-heading))
4967 ;; got to first, outermost topic -- set to expose it and siblings:
4968 (message "Above outermost topic -- exposing all.")
4969 (allout-flag-region (point-min)(point-max) nil
))
4970 (allout-beginning-of-current-line)
4972 (allout-flag-current-subtree nil
)
4973 (allout-beginning-of-level)
4974 (allout-expose-topic '(* :))))))
4975 ;;;_ > allout-current-topic-collapsed-p (&optional include-single-liners)
4976 (defun allout-current-topic-collapsed-p (&optional include-single-liners
)
4977 "True if the currently visible containing topic is already collapsed.
4979 Single line topics intrinsically can be considered as being both
4980 collapsed and uncollapsed. If optional INCLUDE-SINGLE-LINERS is
4981 true, then single-line topics are considered to be collapsed. By
4982 default, they are treated as being uncollapsed."
4986 ;; Is the topic all on one line (allowing for trailing blank line)?
4987 (>= (progn (allout-back-to-current-heading)
4988 (let ((inhibit-field-text-motion t
))
4989 (move-end-of-line 1))
4991 (allout-end-of-current-subtree (not (looking-at "\n\n"))))
4993 (or include-single-liners
4994 (progn (backward-char 1) (allout-hidden-p)))))))
4995 ;;;_ > allout-hide-current-subtree (&optional just-close)
4996 (defun allout-hide-current-subtree (&optional just-close
)
4997 "Close the current topic, or containing topic if this one is already closed.
4999 If this topic is closed and it's a top level topic, close this topic
5002 If optional arg JUST-CLOSE is non-nil, do not close the parent or
5003 siblings, even if the target topic is already closed."
5006 (let* ((from (point))
5007 (sibs-msg "Top-level topic already closed -- closing siblings...")
5008 (current-exposed (not (allout-current-topic-collapsed-p t
))))
5009 (cond (current-exposed (allout-flag-current-subtree t
))
5011 ((allout-ascend) (allout-hide-current-subtree))
5014 (allout-goto-prefix-doublechecked)
5015 (allout-expose-topic '(0 :))
5016 (message (concat sibs-msg
" Done."))))
5018 ;;;_ > allout-toggle-current-subtree-exposure
5019 (defun allout-toggle-current-subtree-exposure ()
5020 "Show or hide the current subtree depending on its current state."
5021 ;; thanks to tassilo for suggesting this.
5024 (allout-back-to-heading)
5025 (if (allout-hidden-p (point-at-eol))
5026 (allout-show-current-subtree)
5027 (allout-hide-current-subtree))))
5028 ;;;_ > allout-show-current-branches ()
5029 (defun allout-show-current-branches ()
5030 "Show all subheadings of this heading, but not their bodies."
5032 (let ((inhibit-field-text-motion t
))
5033 (beginning-of-line))
5034 (allout-show-children t
))
5035 ;;;_ > allout-hide-current-leaves ()
5036 (defun allout-hide-current-leaves ()
5037 "Hide the bodies of the current topic and all its offspring."
5039 (allout-back-to-current-heading)
5040 (allout-hide-region-body (point) (progn (allout-end-of-current-subtree)
5043 ;;;_ - Region and beyond
5044 ;;;_ > allout-show-all ()
5045 (defun allout-show-all ()
5046 "Show all of the text in the buffer."
5048 (message "Exposing entire buffer...")
5049 (allout-flag-region (point-min) (point-max) nil
)
5050 (message "Exposing entire buffer... Done."))
5051 ;;;_ > allout-hide-bodies ()
5052 (defun allout-hide-bodies ()
5053 "Hide all of buffer except headings."
5055 (allout-hide-region-body (point-min) (point-max)))
5056 ;;;_ > allout-hide-region-body (start end)
5057 (defun allout-hide-region-body (start end
)
5058 "Hide all body lines in the region, but not headings."
5062 (narrow-to-region start end
)
5063 (goto-char (point-min))
5064 (let ((inhibit-field-text-motion t
))
5067 (allout-flag-region (point) (allout-end-of-entry) t
)
5070 (if (looking-at "\n\n")
5073 ;;;_ > allout-expose-topic (spec)
5074 (defun allout-expose-topic (spec)
5075 "Apply exposure specs to successive outline topic items.
5077 Use the more convenient frontend, `allout-new-exposure', if you don't
5078 need evaluation of the arguments, or even better, the `allout-layout'
5079 variable-keyed mode-activation/auto-exposure feature of allout outline
5080 mode. See the respective documentation strings for more details.
5082 Cursor is left at start position.
5084 SPEC is either a number or a list.
5086 Successive specs on a list are applied to successive sibling topics.
5088 A simple spec (either a number, one of a few symbols, or the null
5089 list) dictates the exposure for the corresponding topic.
5091 Non-null lists recursively designate exposure specs for respective
5092 subtopics of the current topic.
5094 The `:' repeat spec is used to specify exposure for any number of
5095 successive siblings, up to the trailing ones for which there are
5096 explicit specs following the `:'.
5098 Simple (numeric and null-list) specs are interpreted as follows:
5100 Numbers indicate the relative depth to open the corresponding topic.
5101 - negative numbers force the topic to be closed before opening to the
5102 absolute value of the number, so all siblings are open only to
5104 - positive numbers open to the relative depth indicated by the
5105 number, but do not force already opened subtopics to be closed.
5106 - 0 means to close topic -- hide all offspring.
5108 apply prior element to all siblings at current level, *up to*
5109 those siblings that would be covered by specs following the `:'
5110 on the list. Ie, apply to all topics at level but the last
5111 ones. (Only first of multiple colons at same level is
5112 respected -- subsequent ones are discarded.)
5113 * - completely opens the topic, including bodies.
5114 + - shows all the sub headers, but not the bodies
5115 - - exposes the body of the corresponding topic.
5118 \(allout-expose-topic '(-1 : 0))
5119 Close this and all following topics at current level, exposing
5120 only their immediate children, but close down the last topic
5121 at this current level completely.
5122 \(allout-expose-topic '(-1 () : 1 0))
5123 Close current topic so only the immediate subtopics are shown;
5124 show the children in the second to last topic, and completely
5126 \(allout-expose-topic '(-2 : -1 *))
5127 Expose children and grandchildren of all topics at current
5128 level except the last two; expose children of the second to
5129 last and completely open the last one."
5131 (interactive "xExposure spec: ")
5132 (if (not (listp spec
))
5134 (let ((depth (allout-depth))
5139 (setq prev-elem curr-elem
5140 curr-elem
(car spec
)
5142 (cond ; Do current element:
5143 ((null curr-elem
) nil
)
5144 ((symbolp curr-elem
)
5145 (cond ((eq curr-elem
'*) (allout-show-current-subtree)
5146 (if (> allout-recent-end-of-subtree max-pos
)
5147 (setq max-pos allout-recent-end-of-subtree
)))
5149 (if (not (allout-hidden-p))
5150 (save-excursion (allout-hide-current-subtree t
)))
5151 (allout-show-current-branches)
5152 (if (> allout-recent-end-of-subtree max-pos
)
5153 (setq max-pos allout-recent-end-of-subtree
)))
5154 ((eq curr-elem
'-
) (allout-show-current-entry))
5157 ;; Expand the `repeat' spec to an explicit version,
5158 ;; w.r.t. remaining siblings:
5159 (let ((residue ; = # of sibs not covered by remaining spec
5160 ;; Dang, could be nice to make use of the chart, sigh:
5161 (- (length (allout-chart-siblings))
5164 ;; Some residue -- cover it with prev-elem:
5165 (setq spec
(append (make-list residue prev-elem
)
5167 ((numberp curr-elem
)
5168 (if (and (>= 0 curr-elem
) (not (allout-hidden-p)))
5169 (save-excursion (allout-hide-current-subtree t
)
5172 (if (> allout-recent-end-of-subtree max-pos
)
5174 allout-recent-end-of-subtree
)))))
5175 (if (> (abs curr-elem
) 0)
5176 (progn (allout-show-children (abs curr-elem
))
5177 (if (> allout-recent-end-of-subtree max-pos
)
5178 (setq max-pos allout-recent-end-of-subtree
)))))
5180 (if (allout-descend-to-depth (1+ depth
))
5181 (let ((got (allout-expose-topic curr-elem
)))
5182 (if (and got
(> got max-pos
)) (setq max-pos got
))))))
5183 (cond (stay (setq stay nil
))
5184 ((listp (car spec
)) nil
)
5185 ((> max-pos
(point))
5186 ;; Capitalize on max-pos state to get us nearer next sibling:
5187 (progn (goto-char (min (point-max) max-pos
))
5188 (allout-next-heading)))
5189 ((allout-next-sibling depth
))))
5191 ;;;_ > allout-old-expose-topic (spec &rest followers)
5192 (defun allout-old-expose-topic (spec &rest followers
)
5194 "Deprecated. Use `allout-expose-topic' (with different schema
5197 Dictate wholesale exposure scheme for current topic, according to SPEC.
5199 SPEC is either a number or a list. Optional successive args
5200 dictate exposure for subsequent siblings of current topic.
5202 A simple spec (either a number, a special symbol, or the null list)
5203 dictates the overall exposure for a topic. Non null lists are
5204 composite specs whose first element dictates the overall exposure for
5205 a topic, with the subsequent elements in the list interpreted as specs
5206 that dictate the exposure for the successive offspring of the topic.
5208 Simple (numeric and null-list) specs are interpreted as follows:
5210 - Numbers indicate the relative depth to open the corresponding topic:
5211 - negative numbers force the topic to be close before opening to the
5212 absolute value of the number.
5213 - positive numbers just open to the relative depth indicated by the number.
5215 - `*' completely opens the topic, including bodies.
5216 - `+' shows all the sub headers, but not the bodies
5217 - `-' exposes the body and immediate offspring of the corresponding topic.
5219 If the spec is a list, the first element must be a number, which
5220 dictates the exposure depth of the topic as a whole. Subsequent
5221 elements of the list are nested SPECs, dictating the specific exposure
5222 for the corresponding offspring of the topic.
5224 Optional FOLLOWERS arguments dictate exposure for succeeding siblings."
5226 (interactive "xExposure spec: ")
5227 (let ((inhibit-field-text-motion t
)
5228 (depth (allout-current-depth))
5230 (cond ((null spec
) nil
)
5232 (if (eq spec
'*) (allout-show-current-subtree))
5233 (if (eq spec
'+) (allout-show-current-branches))
5234 (if (eq spec
'-
) (allout-show-current-entry)))
5237 (save-excursion (allout-hide-current-subtree t
)
5239 (if (or (not max-pos
)
5240 (> (point) max-pos
))
5241 (setq max-pos
(point)))
5243 (setq spec
(* -
1 spec
)))))
5245 (allout-show-children spec
)))
5247 ;(let ((got (allout-old-expose-topic (car spec))))
5248 ; (if (and got (or (not max-pos) (> got max-pos)))
5249 ; (setq max-pos got)))
5250 (let ((new-depth (+ (allout-current-depth) 1))
5252 (setq max-pos
(allout-old-expose-topic (car spec
)))
5253 (setq spec
(cdr spec
))
5255 (allout-descend-to-depth new-depth
)
5256 (not (allout-hidden-p)))
5257 (progn (setq got
(apply 'allout-old-expose-topic spec
))
5258 (if (and got
(or (not max-pos
) (> got max-pos
)))
5259 (setq max-pos got
)))))))
5260 (while (and followers
5261 (progn (if (and max-pos
(< (point) max-pos
))
5262 (progn (goto-char max-pos
)
5263 (setq max-pos nil
)))
5265 (allout-next-sibling depth
)))
5266 (allout-old-expose-topic (car followers
))
5267 (setq followers
(cdr followers
)))
5269 ;;;_ > allout-new-exposure '()
5270 (defmacro allout-new-exposure
(&rest spec
)
5271 "Literal frontend for `allout-expose-topic', doesn't evaluate arguments.
5272 Some arguments that would need to be quoted in `allout-expose-topic'
5273 need not be quoted in `allout-new-exposure'.
5275 Cursor is left at start position.
5277 Use this instead of obsolete `allout-exposure'.
5280 \(allout-new-exposure (-1 () () () 1) 0)
5281 Close current topic at current level so only the immediate
5282 subtopics are shown, except also show the children of the
5283 third subtopic; and close the next topic at the current level.
5284 \(allout-new-exposure : -1 0)
5285 Close all topics at current level to expose only their
5286 immediate children, except for the last topic at the current
5287 level, in which even its immediate children are hidden.
5288 \(allout-new-exposure -2 : -1 *)
5289 Expose children and grandchildren of first topic at current
5290 level, and expose children of subsequent topics at current
5291 level *except* for the last, which should be opened completely."
5292 (list 'save-excursion
5293 '(if (not (or (allout-goto-prefix-doublechecked)
5294 (allout-next-heading)))
5295 (error "allout-new-exposure: Can't find any outline topics"))
5296 (list 'allout-expose-topic
(list 'quote spec
))))
5298 ;;;_ #7 Systematic outline presentation -- copying, printing, flattening
5300 ;;;_ - Mapping and processing of topics
5301 ;;;_ ( See also Subtree Charting, in Navigation code.)
5302 ;;;_ > allout-stringify-flat-index (flat-index)
5303 (defun allout-stringify-flat-index (flat-index &optional context
)
5304 "Convert list representing section/subsection/... to document string.
5306 Optional arg CONTEXT indicates interior levels to include."
5310 (context-depth (or (and context
2) 1)))
5311 ;; Take care of the explicit context:
5312 (while (> context-depth
0)
5313 (setq numstr
(int-to-string (car flat-index
))
5314 flat-index
(cdr flat-index
)
5315 result
(if flat-index
5316 (cons delim
(cons numstr result
))
5317 (cons numstr result
))
5318 context-depth
(if flat-index
(1- context-depth
) 0)))
5320 ;; Take care of the indentation:
5327 (1+ (truncate (if (zerop (car flat-index
))
5329 (log10 (car flat-index
)))))
5332 (setq flat-index
(cdr flat-index
)))
5333 ;; Dispose of single extra delim:
5334 (setq result
(cdr result
))))
5335 (apply 'concat result
)))
5336 ;;;_ > allout-stringify-flat-index-plain (flat-index)
5337 (defun allout-stringify-flat-index-plain (flat-index)
5338 "Convert list representing section/subsection/... to document string."
5342 (setq result
(cons (int-to-string (car flat-index
))
5344 (cons delim result
))))
5345 (setq flat-index
(cdr flat-index
)))
5346 (apply 'concat result
)))
5347 ;;;_ > allout-stringify-flat-index-indented (flat-index)
5348 (defun allout-stringify-flat-index-indented (flat-index)
5349 "Convert list representing section/subsection/... to document string."
5353 ;; Take care of the explicit context:
5354 (setq numstr
(int-to-string (car flat-index
))
5355 flat-index
(cdr flat-index
)
5356 result
(if flat-index
5357 (cons delim
(cons numstr result
))
5358 (cons numstr result
)))
5360 ;; Take care of the indentation:
5367 (1+ (truncate (if (zerop (car flat-index
))
5369 (log10 (car flat-index
)))))
5372 (setq flat-index
(cdr flat-index
)))
5373 ;; Dispose of single extra delim:
5374 (setq result
(cdr result
))))
5375 (apply 'concat result
)))
5376 ;;;_ > allout-listify-exposed (&optional start end format)
5377 (defun allout-listify-exposed (&optional start end format
)
5379 "Produce a list representing exposed topics in current region.
5381 This list can then be used by `allout-process-exposed' to manipulate
5384 Optional START and END indicate bounds of region.
5386 Optional arg, FORMAT, designates an alternate presentation form for
5389 list -- Present prefix as numeric section.subsection..., starting with
5390 section indicated by the list, innermost nesting first.
5391 `indent' (symbol) -- Convert header prefixes to all white space,
5392 except for distinctive bullets.
5394 The elements of the list produced are lists that represents a topic
5395 header and body. The elements of that list are:
5397 - a number representing the depth of the topic,
5398 - a string representing the header-prefix, including trailing whitespace and
5400 - a string representing the bullet character,
5401 - and a series of strings, each containing one line of the exposed
5402 portion of the topic entry."
5407 ((inhibit-field-text-motion t
)
5409 strings prefix result depth new-depth out gone-out bullet beg
5414 ;; Goto initial topic, and register preceeding stuff, if any:
5415 (if (> (allout-goto-prefix-doublechecked) start
)
5416 ;; First topic follows beginning point -- register preliminary stuff:
5418 (list (list 0 "" nil
5419 (buffer-substring-no-properties start
5421 (while (and (not done
)
5422 (not (eobp)) ; Loop until we've covered the region.
5423 (not (> (point) end
)))
5424 (setq depth allout-recent-depth
; Current topics depth,
5425 bullet
(allout-recent-bullet) ; ... bullet,
5426 prefix
(allout-recent-prefix)
5427 beg
(progn (allout-end-of-prefix t
) (point))) ; and beginning.
5428 (setq done
; The boundary for the current topic:
5429 (not (allout-next-visible-heading 1)))
5430 (setq new-depth allout-recent-depth
)
5432 out
(< new-depth depth
))
5437 (while (> next
(point)) ; Get all the exposed text in
5439 (cons (buffer-substring-no-properties
5441 ;To hidden text or end of line:
5444 (allout-back-to-visible-text)))
5446 (when (< (point) next
) ; Resume from after hid text, if any.
5448 (beginning-of-line))
5450 ;; Accumulate list for this topic:
5451 (setq strings
(nreverse strings
))
5455 (let ((special (if (string-match
5456 (regexp-quote bullet
)
5457 allout-distinctive-bullets-string
)
5459 (cond ((listp format
)
5461 (if allout-abbreviate-flattened-numbering
5462 (allout-stringify-flat-index format
5464 (allout-stringify-flat-index-plain
5468 ((eq format
'indent
)
5471 (concat (make-string (1+ depth
) ?
)
5472 (substring prefix -
1))
5475 (make-string depth ?
)
5477 (t (error "allout-listify-exposed: %s %s"
5478 "invalid format" format
))))
5479 (list depth prefix strings
))
5481 ;; Reasses format, if any:
5482 (if (and format
(listp format
))
5483 (cond ((= new-depth depth
)
5484 (setq format
(cons (1+ (car format
))
5486 ((> new-depth depth
) ; descending -- assume by 1:
5487 (setq format
(cons 1 format
)))
5490 (while (< new-depth depth
)
5491 (setq format
(cdr format
))
5492 (setq depth
(1- depth
)))
5493 ; And increment the current one:
5495 (cons (1+ (or (car format
)
5498 ;; Put the list with first at front, to last at back:
5499 (nreverse result
))))
5500 ;;;_ > allout-region-active-p ()
5501 (defmacro allout-region-active-p
()
5502 (cond ((fboundp 'use-region-p
) '(use-region-p))
5503 ((fboundp 'region-active-p
) '(region-active-p))
5505 ;;_ > allout-process-exposed (&optional func from to frombuf
5507 (defun allout-process-exposed (&optional func from to frombuf tobuf
5509 "Map function on exposed parts of current topic; results to another buffer.
5511 All args are options; default values itemized below.
5513 Apply FUNCTION to exposed portions FROM position TO position in buffer
5514 FROMBUF to buffer TOBUF. Sixth optional arg, FORMAT, designates an
5515 alternate presentation form:
5517 `flat' -- Present prefix as numeric section.subsection..., starting with
5518 section indicated by the START-NUM, innermost nesting first.
5519 X`flat-indented' -- Prefix is like `flat' for first topic at each
5520 X level, but subsequent topics have only leaf topic
5521 X number, padded with blanks to line up with first.
5522 `indent' (symbol) -- Convert header prefixes to all white space,
5523 except for distinctive bullets.
5526 FUNCTION: `allout-insert-listified'
5527 FROM: region start, if region active, else start of buffer
5528 TO: region end, if region active, else end of buffer
5529 FROMBUF: current buffer
5530 TOBUF: buffer name derived: \"*current-buffer-name exposed*\"
5533 ; Resolve arguments,
5534 ; defaulting if necessary:
5535 (if (not func
) (setq func
'allout-insert-listified
))
5536 (if (not (and from to
))
5537 (if (allout-region-active-p)
5538 (setq from
(region-beginning) to
(region-end))
5539 (setq from
(point-min) to
(point-max))))
5541 (if (not (bufferp frombuf
))
5542 ;; Specified but not a buffer -- get it:
5543 (let ((got (get-buffer frombuf
)))
5545 (error (concat "allout-process-exposed: source buffer "
5548 (setq frombuf got
))))
5549 ;; not specified -- default it:
5550 (setq frombuf
(current-buffer)))
5552 (if (not (bufferp tobuf
))
5553 (setq tobuf
(get-buffer-create tobuf
)))
5554 ;; not specified -- default it:
5555 (setq tobuf
(concat "*" (buffer-name frombuf
) " exposed*")))
5560 (progn (set-buffer frombuf
)
5561 (allout-listify-exposed from to format
))))
5563 (mapc func listified
)
5564 (pop-to-buffer tobuf
)))
5567 ;;;_ > allout-insert-listified (listified)
5568 (defun allout-insert-listified (listified)
5569 "Insert contents of listified outline portion in current buffer.
5571 LISTIFIED is a list representing each topic header and body:
5573 \`(depth prefix text)'
5575 or \`(depth prefix text bullet-plus)'
5577 If `bullet-plus' is specified, it is inserted just after the entire prefix."
5578 (setq listified
(cdr listified
))
5579 (let ((prefix (prog1
5581 (setq listified
(cdr listified
))))
5584 (setq listified
(cdr listified
))))
5585 (bullet-plus (car listified
)))
5587 (if bullet-plus
(insert (concat " " bullet-plus
)))
5590 (if (setq text
(cdr text
))
5593 ;;;_ > allout-copy-exposed-to-buffer (&optional arg tobuf format)
5594 (defun allout-copy-exposed-to-buffer (&optional arg tobuf format
)
5595 "Duplicate exposed portions of current outline to another buffer.
5597 Other buffer has current buffers name with \" exposed\" appended to it.
5599 With repeat count, copy the exposed parts of only the current topic.
5601 Optional second arg TOBUF is target buffer name.
5603 Optional third arg FORMAT, if non-nil, symbolically designates an
5604 alternate presentation format for the outline:
5606 `flat' - Convert topic header prefixes to numeric
5607 section.subsection... identifiers.
5608 `indent' - Convert header prefixes to all white space, except for
5609 distinctive bullets.
5610 `indent-flat' - The best of both - only the first of each level has
5611 the full path, the rest have only the section number
5612 of the leaf, preceded by the right amount of indentation."
5616 (setq tobuf
(get-buffer-create (concat "*" (buffer-name) " exposed*"))))
5617 (let* ((start-pt (point))
5618 (beg (if arg
(allout-back-to-current-heading) (point-min)))
5619 (end (if arg
(allout-end-of-current-subtree) (point-max)))
5620 (buf (current-buffer))
5622 (if (eq format
'flat
)
5623 (setq format
(if arg
(save-excursion
5625 (allout-topic-flat-index))
5627 (with-current-buffer tobuf
(erase-buffer))
5628 (allout-process-exposed 'allout-insert-listified
5634 (goto-char (point-min))
5636 (goto-char start-pt
)))
5637 ;;;_ > allout-flatten-exposed-to-buffer (&optional arg tobuf)
5638 (defun allout-flatten-exposed-to-buffer (&optional arg tobuf
)
5639 "Present numeric outline of outline's exposed portions in another buffer.
5641 The resulting outline is not compatible with outline mode -- use
5642 `allout-copy-exposed-to-buffer' if you want that.
5644 Use `allout-indented-exposed-to-buffer' for indented presentation.
5646 With repeat count, copy the exposed portions of only current topic.
5648 Other buffer has current buffer's name with \" exposed\" appended to
5649 it, unless optional second arg TOBUF is specified, in which case it is
5652 (allout-copy-exposed-to-buffer arg tobuf
'flat
))
5653 ;;;_ > allout-indented-exposed-to-buffer (&optional arg tobuf)
5654 (defun allout-indented-exposed-to-buffer (&optional arg tobuf
)
5655 "Present indented outline of outline's exposed portions in another buffer.
5657 The resulting outline is not compatible with outline mode -- use
5658 `allout-copy-exposed-to-buffer' if you want that.
5660 Use `allout-flatten-exposed-to-buffer' for numeric sectional presentation.
5662 With repeat count, copy the exposed portions of only current topic.
5664 Other buffer has current buffer's name with \" exposed\" appended to
5665 it, unless optional second arg TOBUF is specified, in which case it is
5668 (allout-copy-exposed-to-buffer arg tobuf
'indent
))
5670 ;;;_ - LaTeX formatting
5671 ;;;_ > allout-latex-verb-quote (string &optional flow)
5672 (defun allout-latex-verb-quote (string &optional flow
)
5673 "Return copy of STRING for literal reproduction across LaTeX processing.
5674 Expresses the original characters (including carriage returns) of the
5675 string across LaTeX processing."
5676 (mapconcat (function
5678 (cond ((memq char
'(?
\\ ?$ ?% ?
# ?
& ?
{ ?
} ?_ ?^ ?- ?
*))
5679 (concat "\\char" (number-to-string char
) "{}"))
5680 ((= char ?
\n) "\\\\")
5681 (t (char-to-string char
)))))
5684 ;;;_ > allout-latex-verbatim-quote-curr-line ()
5685 (defun allout-latex-verbatim-quote-curr-line ()
5686 "Express line for exact (literal) representation across LaTeX processing.
5688 Adjust line contents so it is unaltered (from the original line)
5689 across LaTeX processing, within the context of a `verbatim'
5690 environment. Leaves point at the end of the line."
5691 (let ((inhibit-field-text-motion t
))
5694 (end (point-at-eol)))
5696 (while (re-search-forward "\\\\"
5697 ;;"\\\\\\|\\{\\|\\}\\|\\_\\|\\$\\|\\\"\\|\\&\\|\\^\\|\\-\\|\\*\\|#"
5698 end
; bounded by end-of-line
5699 1) ; no matches, move to end & return nil
5700 (goto-char (match-beginning 2))
5703 (goto-char (1+ (match-end 2))))))))
5704 ;;;_ > allout-insert-latex-header (buffer)
5705 (defun allout-insert-latex-header (buffer)
5706 "Insert initial LaTeX commands at point in BUFFER."
5707 ;; Much of this is being derived from the stuff in appendix of E in
5708 ;; the TeXBook, pg 421.
5710 (let ((doc-style (format "\n\\documentstyle{%s}\n"
5712 (page-numbering (if allout-number-pages
5713 "\\pagestyle{empty}\n"
5715 (titlecmd (format "\\newcommand{\\titlecmd}[1]{{%s #1}}\n"
5716 allout-title-style
))
5717 (labelcmd (format "\\newcommand{\\labelcmd}[1]{{%s #1}}\n"
5718 allout-label-style
))
5719 (headlinecmd (format "\\newcommand{\\headlinecmd}[1]{{%s #1}}\n"
5720 allout-head-line-style
))
5721 (bodylinecmd (format "\\newcommand{\\bodylinecmd}[1]{{%s #1}}\n"
5722 allout-body-line-style
))
5723 (setlength (format "%s%s%s%s"
5724 "\\newlength{\\stepsize}\n"
5725 "\\setlength{\\stepsize}{"
5728 (oneheadline (format "%s%s%s%s%s%s%s"
5729 "\\newcommand{\\OneHeadLine}[3]{%\n"
5731 "\\hspace*{#2\\stepsize}%\n"
5732 "\\labelcmd{#1}\\hspace*{.2cm}"
5733 "\\headlinecmd{#3}\\\\["
5736 (onebodyline (format "%s%s%s%s%s%s"
5737 "\\newcommand{\\OneBodyLine}[2]{%\n"
5739 "\\hspace*{#1\\stepsize}%\n"
5740 "\\bodylinecmd{#2}\\\\["
5743 (begindoc "\\begin{document}\n\\begin{center}\n")
5744 (title (format "%s%s%s%s"
5746 (allout-latex-verb-quote (if allout-title
5749 (error "<unnamed buffer>"))
5752 "\\end{center}\n\n"))
5753 (hsize "\\hsize = 7.5 true in\n")
5754 (hoffset "\\hoffset = -1.5 true in\n")
5755 (vspace "\\vspace{.1cm}\n\n"))
5756 (insert (concat doc-style
5771 ;;;_ > allout-insert-latex-trailer (buffer)
5772 (defun allout-insert-latex-trailer (buffer)
5773 "Insert concluding LaTeX commands at point in BUFFER."
5775 (insert "\n\\end{document}\n"))
5776 ;;;_ > allout-latexify-one-item (depth prefix bullet text)
5777 (defun allout-latexify-one-item (depth prefix bullet text
)
5778 "Insert LaTeX commands for formatting one outline item.
5780 Args are the topics numeric DEPTH, the header PREFIX lead string, the
5781 BULLET string, and a list of TEXT strings for the body."
5782 (let* ((head-line (if text
(car text
)))
5783 (body-lines (cdr text
))
5787 (insert (concat "\\OneHeadLine{\\verb\1 "
5788 (allout-latex-verb-quote bullet
)
5793 (allout-latex-verb-quote head-line
)
5796 (if (not body-lines
)
5798 ;;(insert "\\beginlines\n")
5799 (insert "\\begin{verbatim}\n")
5801 (setq curr-line
(car body-lines
))
5802 (if (and (not body-content
)
5803 (not (string-match "^\\s-*$" curr-line
)))
5804 (setq body-content t
))
5805 ; Mangle any occurrences of
5806 ; "\end{verbatim}" in text,
5808 (if (and body-content
5809 (setq bop
(string-match "\\end{verbatim}" curr-line
)))
5810 (setq curr-line
(concat (substring curr-line
0 bop
)
5812 (substring curr-line bop
))))
5813 ;;(insert "|" (car body-lines) "|")
5815 (allout-latex-verbatim-quote-curr-line)
5817 (setq body-lines
(cdr body-lines
)))
5819 (setq body-content nil
)
5823 ;;(insert "\\endlines\n")
5824 (insert "\\end{verbatim}\n")
5826 ;;;_ > allout-latexify-exposed (arg &optional tobuf)
5827 (defun allout-latexify-exposed (arg &optional tobuf
)
5828 "Format current topics exposed portions to TOBUF for LaTeX processing.
5829 TOBUF defaults to a buffer named the same as the current buffer, but
5830 with \"*\" prepended and \" latex-formed*\" appended.
5832 With repeat count, copy the exposed portions of entire buffer."
5837 (get-buffer-create (concat "*" (buffer-name) " latexified*"))))
5838 (let* ((start-pt (point))
5839 (beg (if arg
(point-min) (allout-back-to-current-heading)))
5840 (end (if arg
(point-max) (allout-end-of-current-subtree)))
5841 (buf (current-buffer)))
5844 (allout-insert-latex-header tobuf
)
5845 (goto-char (point-max))
5846 (allout-process-exposed 'allout-latexify-one-item
5851 (goto-char (point-max))
5852 (allout-insert-latex-trailer tobuf
)
5853 (goto-char (point-min))
5855 (goto-char start-pt
)))
5858 ;;;_ > allout-toggle-current-subtree-encryption (&optional keymode-cue)
5859 (defun allout-toggle-current-subtree-encryption (&optional keymode-cue
)
5860 "Encrypt clear or decrypt encoded topic text.
5862 Allout uses emacs 'epg' libary to perform encryption. Symmetric
5863 and keypair encryption are supported. All encryption is ascii
5866 Entry encryption defaults to symmetric key mode unless keypair
5867 recipients are associated with the file \(see
5868 `epa-file-encrypt-to') or the function is invoked with a
5869 \(KEYMODE-CUE) universal argument greater than 1.
5871 When encrypting, KEYMODE-CUE universal argument greater than 1
5872 causes prompting for recipients for public-key keypair
5873 encryption. Selecting no recipients results in symmetric key
5876 Further, encrypting with a KEYMODE-CUE universal argument greater
5877 than 4 - eg, preceded by a doubled Ctrl-U - causes association of
5878 the specified recipients with the file, replacing those currently
5879 associated with it. This can be used to deassociate any
5880 recipients with the file, by selecting no recipients in the
5883 Encrypted topic's bullets are set to a `~' to signal that the
5884 contents of the topic (body and subtopics, but not heading) is
5885 pending encryption or encrypted. `*' asterisk immediately after
5886 the bullet signals that the body is encrypted, its absence means
5887 the topic is meant to be encrypted but is not currently. When a
5888 file with topics pending encryption is saved, topics pending
5889 encryption are encrypted. See allout-encrypt-unencrypted-on-saves
5890 for auto-encryption specifics.
5892 \*NOTE WELL* that automatic encryption that happens during saves will
5893 default to symmetric encryption -- you must deliberately (re)encrypt key-pair
5894 encrypted topics if you want them to continue to use the key-pair cipher.
5896 Level-one topics, with prefix consisting solely of an `*' asterisk, cannot be
5897 encrypted. If you want to encrypt the contents of a top-level topic, use
5898 \\[allout-shift-in] to increase its depth."
5901 (allout-back-to-current-heading)
5902 (allout-toggle-subtree-encryption keymode-cue
)))
5903 ;;;_ > allout-toggle-subtree-encryption (&optional keymode-cue)
5904 (defun allout-toggle-subtree-encryption (&optional keymode-cue
)
5905 "Encrypt clear text or decrypt encoded topic contents (body and subtopics.)
5907 Entry encryption defaults to symmetric key mode unless keypair
5908 recipients are associated with the file \(see
5909 `epa-file-encrypt-to') or the function is invoked with a
5910 \(KEYMODE-CUE) universal argument greater than 1.
5912 When encrypting, KEYMODE-CUE universal argument greater than 1
5913 causes prompting for recipients for public-key keypair
5914 encryption. Selecting no recipients results in symmetric key
5917 Further, encrypting with a KEYMODE-CUE universal argument greater
5918 than 4 - eg, preceded by a doubled Ctrl-U - causes association of
5919 the specified recipients with the file, replacing those currently
5920 associated with it. This can be used to deassociate any
5921 recipients with the file, by selecting no recipients in the
5924 Encryption and decryption uses the emacs epg library.
5926 Encrypted text will be ascii-armored.
5928 See `allout-toggle-current-subtree-encryption' for more details."
5932 (allout-end-of-prefix t
)
5934 (if (= allout-recent-depth
1)
5935 (error (concat "Cannot encrypt or decrypt level 1 topics -"
5936 " shift it in to make it encryptable")))
5938 (let* ((allout-buffer (current-buffer))
5940 (bullet-pos allout-recent-prefix-beginning
)
5941 (after-bullet-pos (point))
5943 (progn (if (= (point-max) after-bullet-pos
)
5944 (error "no body to encrypt"))
5945 (allout-encrypted-topic-p)))
5946 (was-collapsed (if (not (search-forward "\n" nil t
))
5950 (subtree-beg (1+ (point)))
5951 (subtree-end (allout-end-of-subtree))
5952 (subject-text (buffer-substring-no-properties subtree-beg
5954 (subtree-end-char (char-after (1- subtree-end
)))
5955 (subtree-trailing-char (char-after subtree-end
))
5956 ;; kluge -- result-text needs to be nil, but we also want to
5957 ;; check for the error condition
5958 (result-text (if (or (string= "" subject-text
)
5959 (string= "\n" subject-text
))
5960 (error "No topic contents to %scrypt"
5961 (if was-encrypted
"de" "en"))
5963 ;; Assess key parameters:
5964 (was-coding-system buffer-file-coding-system
))
5966 (when (not was-encrypted
)
5967 ;; ensure that non-ascii chars pending encryption are noticed before
5968 ;; they're encrypted, so the coding system is set to accommodate
5970 (setq buffer-file-coding-system
5971 (allout-select-safe-coding-system subtree-beg subtree-end
))
5972 ;; if the coding system for the text being encrypted is different
5973 ;; than that prevailing, then there a real risk that the coding
5974 ;; system can't be noticed by emacs when the file is visited. to
5975 ;; mitigate that, offer to preserve the coding system using a file
5977 (if (and (not (equal buffer-file-coding-system
5980 (format (concat "Register coding system %s as file local"
5981 " var? Necessary when only encrypted text"
5982 " is in that coding system. ")
5983 buffer-file-coding-system
)))
5984 (allout-adjust-file-variable "buffer-file-coding-system"
5985 buffer-file-coding-system
)))
5988 (allout-encrypt-string subject-text was-encrypted
5989 (current-buffer) keymode-cue
))
5991 ;; Replace the subtree with the processed product.
5994 (set-buffer allout-buffer
)
5995 (delete-region subtree-beg subtree-end
)
5996 (insert result-text
)
5998 (allout-flag-region (1- subtree-beg
) (point) t
))
5999 ;; adjust trailing-blank-lines to preserve topic spacing:
6000 (if (not was-encrypted
)
6001 (if (and (= subtree-end-char ?
\n)
6002 (= subtree-trailing-char ?
\n))
6003 (insert subtree-trailing-char
)))
6004 ;; Ensure that the item has an encrypted-entry bullet:
6005 (if (not (string= (buffer-substring-no-properties
6006 (1- after-bullet-pos
) after-bullet-pos
)
6007 allout-topic-encryption-bullet
))
6008 (progn (goto-char (1- after-bullet-pos
))
6010 (insert allout-topic-encryption-bullet
)))
6012 ;; Remove the is-encrypted bullet qualifier:
6013 (progn (goto-char after-bullet-pos
)
6015 ;; Add the is-encrypted bullet qualifier:
6016 (goto-char after-bullet-pos
)
6018 (run-hook-with-args 'allout-structure-added-hook
6019 bullet-pos subtree-end
))))
6020 ;;;_ > allout-encrypt-string (text decrypt allout-buffer keymode-cue
6021 ;;; &optional rejected)
6022 (defun allout-encrypt-string (text decrypt allout-buffer keymode-cue
6024 "Encrypt or decrypt message TEXT.
6026 Returns the resulting string, or nil if the transformation fails.
6028 If DECRYPT is true (default false), then decrypt instead of encrypt.
6030 ALLOUT-BUFFER identifies the buffer containing the text.
6032 Entry encryption defaults to symmetric key mode unless keypair
6033 recipients are associated with the file \(see
6034 `epa-file-encrypt-to') or the function is invoked with a
6035 \(KEYMODE-CUE) universal argument greater than 1.
6037 When encrypting, KEYMODE-CUE universal argument greater than 1
6038 causes prompting for recipients for public-key keypair
6039 encryption. Selecting no recipients results in symmetric key
6042 Further, encrypting with a KEYMODE-CUE universal argument greater
6043 than 4 - eg, preceded by a doubled Ctrl-U - causes association of
6044 the specified recipients with the file, replacing those currently
6045 associated with it. This can be used to deassociate any
6046 recipients with the file, by selecting no recipients in the
6049 Optional REJECTED is for internal use, to convey the number of
6050 rejections due to matches against
6051 `allout-encryption-ciphertext-rejection-regexps', as limited by
6052 `allout-encryption-ciphertext-rejection-ceiling'.
6054 NOTE: A few GnuPG v2 versions improperly preserve incorrect
6055 symmetric decryption keys, preventing entry of the correct key on
6056 subsequent decryption attempts until the cache times-out. That
6057 can take several minutes. \(Decryption of other entries is not
6058 affected.) Upgrade your EasyPG version, if you can, and you can
6059 deliberately clear your gpg-agent's cache by sending it a '-HUP'
6065 (let* ((epg-context (let* ((context (epg-make-context nil t
)))
6066 (epg-context-set-passphrase-callback
6067 context
#'epa-passphrase-callback-function
)
6069 (encoding (with-current-buffer allout-buffer
6070 buffer-file-coding-system
))
6071 (multibyte (with-current-buffer allout-buffer
6072 enable-multibyte-characters
))
6073 ;; "sanitization" avoids encryption results that are outline structure.
6074 (sani-regexps 'allout-encryption-plaintext-sanitization-regexps
)
6075 (strip-plaintext-regexps (if (not decrypt
)
6076 (allout-get-configvar-values
6078 (rejection-regexps 'allout-encryption-ciphertext-rejection-regexps
)
6079 (reject-ciphertext-regexps (if (not decrypt
)
6080 (allout-get-configvar-values
6081 rejection-regexps
)))
6082 (rejected (or rejected
0))
6083 (rejections-left (- allout-encryption-ciphertext-rejection-ceiling
6085 (keypair-mode (cond (decrypt 'decrypting
)
6086 ((<= (prefix-numeric-value keymode-cue
) 1)
6088 ((<= (prefix-numeric-value keymode-cue
) 4)
6090 ((> (prefix-numeric-value keymode-cue
) 4)
6092 (keypair-message (concat "Select encryption recipients.\n"
6093 "Symmetric encryption is done if no"
6094 " recipients are selected. "))
6095 (encrypt-to (and (boundp 'epa-file-encrypt-to
) epa-file-encrypt-to
))
6101 ;; Massage the subject text for encoding and filtering.
6104 ;; convey the text characteristics of the original buffer:
6105 (allout-set-buffer-multibyte multibyte
)
6107 (set-buffer-file-coding-system encoding
)
6109 (encode-coding-region (point-min) (point-max) encoding
)))
6111 ;; remove sanitization regexps matches before encrypting:
6112 (when (and strip-plaintext-regexps
(not decrypt
))
6113 (dolist (re strip-plaintext-regexps
)
6114 (let ((re (if (listp re
) (car re
) re
))
6115 (replacement (if (listp re
) (cadr re
) "")))
6116 (goto-char (point-min))
6118 (while (re-search-forward re nil t
)
6119 (replace-match replacement nil nil
))))))
6120 (setq massaged-text
(buffer-substring-no-properties (point-min)
6122 ;; determine key mode and, if keypair, recipients:
6128 (default (if encrypt-to
(epg-list-keys epg-context encrypt-to
)))
6130 ((prompt prompt-save
)
6131 (save-window-excursion
6132 (epa-select-keys epg-context keypair-message
)))))
6136 (epg-decrypt-string epg-context
6137 (encode-coding-string massaged-text
6138 (or encoding
'utf-8
)))
6139 (replace-regexp-in-string "\n$" ""
6140 (epg-encrypt-string epg-context
6141 (encode-coding-string massaged-text
6142 (or encoding
'utf-8
))
6145 ;; validate result -- non-empty
6146 (if (not result-text
)
6147 (error "%scryption failed." (if decrypt
"De" "En")))
6150 (when (eq keypair-mode
'prompt-save
)
6151 ;; set epa-file-encrypt-to in the buffer:
6152 (setq epa-file-encrypt-to
(mapcar (lambda (key)
6154 (car (epg-key-user-id-list key
))))
6156 ;; change the file variable:
6157 (allout-adjust-file-variable "epa-file-encrypt-to" epa-file-encrypt-to
))
6160 ;; Retry (within limit) if ciphertext contains rejections:
6162 ;; Check for disqualification of this ciphertext:
6163 (let ((regexps reject-ciphertext-regexps
)
6165 (while (and regexps
(not reject-it
))
6166 (setq reject-it
(string-match (car regexps
) result-text
))
6169 (setq rejections-left
(1- rejections-left
))
6170 (if (<= rejections-left
0)
6171 (error (concat "Ciphertext rejected too many times"
6173 allout-encryption-ciphertext-rejection-ceiling
6174 'allout-encryption-ciphertext-rejection-regexps
)
6175 ;; try again (gpg-agent may have the key cached):
6176 (allout-encrypt-string text decrypt allout-buffer keypair-mode
6179 ;; Barf if encryption yields extraordinary control chars:
6181 (string-match "[\C-a\C-k\C-o-\C-z\C-@]"
6183 (error (concat "Encryption produced non-armored text, which"
6184 "conflicts with allout mode -- reconfigure!")))
6187 ;;;_ > allout-encrypted-topic-p ()
6188 (defun allout-encrypted-topic-p ()
6189 "True if the current topic is encryptable and encrypted."
6191 (allout-end-of-prefix t
)
6192 (and (string= (buffer-substring-no-properties (1- (point)) (point))
6193 allout-topic-encryption-bullet
)
6194 (save-match-data (looking-at "\\*")))
6197 ;;;_ > allout-next-topic-pending-encryption (&optional except-mark)
6198 (defun allout-next-topic-pending-encryption (&optional except-mark
)
6199 "Return the point of the next topic pending encryption, or nil if none.
6201 EXCEPT-MARK identifies a point whose containing topics should be excluded
6202 from encryption. This supports 'except-current mode of
6203 `allout-encrypt-unencrypted-on-saves'.
6205 Such a topic has the `allout-topic-encryption-bullet' without an
6206 immediately following '*' that would mark the topic as being encrypted. It
6207 must also have content."
6208 (let (done got content-beg
)
6212 (if (not (re-search-forward
6213 (format "\\(\\`\\|\n\\)%s *%s[^*]"
6214 (regexp-quote allout-header-prefix
)
6215 (regexp-quote allout-topic-encryption-bullet
))
6219 (goto-char (setq got
(match-beginning 0)))
6220 (if (save-match-data (looking-at "\n"))
6227 ((not (search-forward "\n"))
6236 (setq content-beg
(point))
6238 (allout-end-of-subtree)
6239 (if (or (<= (point) content-beg
)
6241 (<= content-beg except-mark
)
6242 (>= (point) except-mark
)))
6254 ;;;_ > allout-encrypt-decrypted (&optional except-mark)
6255 (defun allout-encrypt-decrypted (&optional except-mark
)
6256 "Encrypt topics pending encryption except those containing exemption point.
6258 EXCEPT-MARK identifies a point whose containing topics should be excluded
6259 from encryption. This supports the `except-current' mode of
6260 `allout-encrypt-unencrypted-on-saves'.
6262 If a topic that is currently being edited was encrypted, we return a list
6263 containing the location of the topic and the location of the cursor just
6264 before the topic was encrypted. This can be used, eg, to decrypt the topic
6265 and exactly resituate the cursor if this is being done as part of a file
6266 save. See `allout-encrypt-unencrypted-on-saves' for more info."
6271 (let* ((current-mark (point-marker))
6272 (current-mark-position (marker-position current-mark
))
6275 editing-topic editing-point
)
6276 (goto-char (point-min))
6277 (while (allout-next-topic-pending-encryption except-mark
)
6278 (setq was-modified
(buffer-modified-p))
6279 (when (save-excursion
6280 (and (boundp 'allout-encrypt-unencrypted-on-saves
)
6281 allout-encrypt-unencrypted-on-saves
6282 (setq bo-subtree
(re-search-forward "$"))
6283 (not (allout-hidden-p))
6284 (>= current-mark
(point))
6285 (allout-end-of-current-subtree)
6286 (<= current-mark
(point))))
6287 (setq editing-topic
(point)
6288 ;; we had to wait for this 'til now so prior topics are
6289 ;; encrypted, any relevant text shifts are in place:
6290 editing-point
(- current-mark-position
6291 (count-trailing-whitespace-region
6292 bo-subtree current-mark-position
))))
6293 (allout-toggle-subtree-encryption)
6294 (if (not was-modified
)
6295 (set-buffer-modified-p nil
))
6297 (if (not was-modified
)
6298 (set-buffer-modified-p nil
))
6299 (if editing-topic
(list editing-topic editing-point
))
6305 ;;;_ #9 miscellaneous
6307 ;;;_ > outlineify-sticky ()
6308 ;; outlinify-sticky is correct spelling; provide this alias for sticklers:
6310 (defalias 'outlinify-sticky
'outlineify-sticky
)
6312 (defun outlineify-sticky (&optional arg
)
6313 "Activate outline mode and establish file var so it is started subsequently.
6315 See doc-string for `allout-layout' and `allout-init' for details on
6316 setup for auto-startup."
6320 (if (allout-mode-p) (allout-mode)) ; deactivate so we can re-activate...
6324 (goto-char (point-min))
6325 (if (allout-goto-prefix)
6327 (allout-open-topic 2)
6328 (insert (concat "Dummy outline topic header -- see"
6329 "`allout-mode' docstring: `^Hm'."))
6330 (allout-adjust-file-variable
6331 "allout-layout" (or allout-layout
'(-1 : 0))))))
6332 ;;;_ > allout-file-vars-section-data ()
6333 (defun allout-file-vars-section-data ()
6334 "Return data identifying the file-vars section, or nil if none.
6336 Returns a list of the form (BEGINNING-POINT PREFIX-STRING SUFFIX-STRING)."
6337 ;; minimally gleaned from emacs 21.4 files.el hack-local-variables function.
6338 (let (beg prefix suffix
)
6340 (goto-char (point-max))
6341 (search-backward "\n\^L" (max (- (point-max) 3000) (point-min)) 'move
)
6342 (if (let ((case-fold-search t
))
6343 (not (search-forward "Local Variables:" nil t
)))
6345 (setq beg
(- (point) 16))
6346 (setq suffix
(buffer-substring-no-properties
6348 (progn (if (search-forward "\n" nil t
)
6351 (setq prefix
(buffer-substring-no-properties
6352 (progn (if (search-backward "\n" nil t
)
6356 (list beg prefix suffix
))
6360 ;;;_ > allout-adjust-file-variable (varname value)
6361 (defun allout-adjust-file-variable (varname value
)
6362 "Adjust the setting of an Emacs file variable named VARNAME to VALUE.
6364 This activity is inhibited if either `enable-local-variables'
6365 `allout-enable-file-variable-adjustment' are nil.
6367 When enabled, an entry for the variable is created if not already present,
6368 or changed if established with a different value. The section for the file
6369 variables, itself, is created if not already present. When created, the
6370 section lines (including the section line) exist as second-level topics in
6371 a top-level topic at the end of the file.
6373 `enable-local-variables' must be true for any of this to happen."
6374 (if (not (and enable-local-variables
6375 allout-enable-file-variable-adjustment
))
6378 (let ((inhibit-field-text-motion t
)
6379 (section-data (allout-file-vars-section-data))
6382 (setq beg
(car section-data
)
6383 prefix
(cadr section-data
)
6384 suffix
(car (cddr section-data
)))
6385 ;; create the section
6386 (goto-char (point-max))
6388 (allout-open-topic 0)
6390 (insert "Local emacs vars.\n")
6391 (allout-open-topic 1)
6394 prefix
(buffer-substring-no-properties (progn
6399 (insert "Local variables:\n")
6400 (allout-open-topic 0)
6403 ;; look for existing entry or create one, leaving point for insertion
6406 (allout-show-to-offshoot)
6407 (if (search-forward (concat "\n" prefix varname
":") nil t
)
6408 (let* ((value-beg (point))
6409 (line-end (progn (if (search-forward "\n" nil t
)
6412 (value-end (- line-end
(length suffix
))))
6413 (if (> value-end value-beg
)
6414 (delete-region value-beg value-end
)))
6418 (insert (concat prefix varname
":")))
6419 (insert (format " %S%s" value suffix
))
6424 ;;;_ > allout-get-configvar-values (varname)
6425 (defun allout-get-configvar-values (configvar-name)
6426 "Return a list of values of the symbols in list bound to CONFIGVAR-NAME.
6428 The user is prompted for removal of symbols that are unbound, and they
6429 otherwise are ignored.
6431 CONFIGVAR-NAME should be the name of the configuration variable,
6434 (let ((configvar-value (symbol-value configvar-name
))
6436 (dolist (sym configvar-value
)
6437 (if (not (boundp sym
))
6438 (if (yes-or-no-p (format "%s entry `%s' is unbound -- remove it? "
6439 configvar-name sym
))
6440 (delq sym
(symbol-value configvar-name
)))
6441 (push (symbol-value sym
) got
)))
6444 ;;;_ > allout-mark-topic ()
6445 (defun allout-mark-topic ()
6446 "Put the region around topic currently containing point."
6448 (let ((inhibit-field-text-motion t
))
6449 (beginning-of-line))
6450 (allout-goto-prefix-doublechecked)
6452 (allout-end-of-current-subtree)
6453 (exchange-point-and-mark))
6455 ;;;_ > solicit-char-in-string (prompt string &optional do-defaulting)
6456 (defun solicit-char-in-string (prompt string
&optional do-defaulting
)
6457 "Solicit (with first arg PROMPT) choice of a character from string STRING.
6459 Optional arg DO-DEFAULTING indicates to accept empty input (CR)."
6461 (let ((new-prompt prompt
)
6465 (message "%s" new-prompt
)
6467 ;; We do our own reading here, so we can circumvent, eg, special
6468 ;; treatment for `?' character. (Oughta use minibuffer keymap instead.)
6470 (char-to-string (let ((cursor-in-echo-area nil
)) (read-char))))
6473 (cond ((string-match (regexp-quote got
) string
) got
)
6474 ((and do-defaulting
(string= got
"\r"))
6475 ;; Return empty string to default:
6477 ((string= got
"\C-g") (signal 'quit nil
))
6479 (setq new-prompt
(concat prompt
6485 ;; got something out of loop -- return it:
6489 ;;;_ > regexp-sans-escapes (string)
6490 (defun regexp-sans-escapes (regexp &optional successive-backslashes
)
6491 "Return a copy of REGEXP with all character escapes stripped out.
6493 Representations of actual backslashes -- '\\\\\\\\' -- are left as a
6496 Optional arg SUCCESSIVE-BACKSLASHES is used internally for recursion."
6498 (if (string= regexp
"")
6500 ;; Set successive-backslashes to number if current char is
6501 ;; backslash, or else to nil:
6502 (setq successive-backslashes
6503 (if (= (aref regexp
0) ?
\\)
6504 (if successive-backslashes
(1+ successive-backslashes
) 1)
6506 (if (or (not successive-backslashes
) (= 2 successive-backslashes
))
6507 ;; Include first char:
6508 (concat (substring regexp
0 1)
6509 (regexp-sans-escapes (substring regexp
1)))
6510 ;; Exclude first char, but maintain count:
6511 (regexp-sans-escapes (substring regexp
1) successive-backslashes
))))
6512 ;;;_ > count-trailing-whitespace-region (beg end)
6513 (defun count-trailing-whitespace-region (beg end
)
6514 "Return number of trailing whitespace chars between BEG and END.
6516 If BEG is bigger than END we return 0."
6523 (while (re-search-forward "[ ][ ]*$" end t
)
6524 (goto-char (1+ (match-beginning 2)))
6525 (setq count
(1+ count
)))
6527 ;;;_ > allout-format-quote (string)
6528 (defun allout-format-quote (string)
6529 "Return a copy of string with all \"%\" characters doubled."
6531 (mapcar (lambda (char) (if (= char ?%
) "%%" (char-to-string char
)))
6534 ;;;_ > allout-flatten (list)
6535 (defun allout-flatten (list)
6536 "Return a list of all atoms in list."
6538 (cond ((null list
) nil
)
6539 ((atom (car list
)) (cons (car list
) (allout-flatten (cdr list
))))
6540 (t (append (allout-flatten (car list
)) (allout-flatten (cdr list
))))))
6541 ;;;_ : Compatibility:
6542 ;;;_ : xemacs undo-in-progress provision:
6543 (unless (boundp 'undo-in-progress
)
6544 (defvar undo-in-progress nil
6545 "Placeholder defvar for XEmacs compatibility from allout.el.")
6546 (defadvice undo-more
(around allout activate
)
6547 ;; This defadvice used only in emacs that lack undo-in-progress, eg xemacs.
6548 (let ((undo-in-progress t
)) ad-do-it
)))
6550 ;;;_ > allout-mark-marker to accommodate divergent emacsen:
6551 (defun allout-mark-marker (&optional force buffer
)
6552 "Accommodate the different signature for `mark-marker' across Emacsen.
6554 XEmacs takes two optional args, while mainline GNU Emacs does not,
6555 so pass them along when appropriate."
6556 (if (featurep 'xemacs
)
6557 (apply 'mark-marker force buffer
)
6559 ;;;_ > subst-char-in-string if necessary
6560 (if (not (fboundp 'subst-char-in-string
))
6561 (defun subst-char-in-string (fromchar tochar string
&optional inplace
)
6562 "Replace FROMCHAR with TOCHAR in STRING each time it occurs.
6563 Unless optional argument INPLACE is non-nil, return a new string."
6564 (let ((i (length string
))
6565 (newstr (if inplace string
(copy-sequence string
))))
6568 (if (eq (aref newstr i
) fromchar
)
6569 (aset newstr i tochar
)))
6571 ;;;_ > wholenump if necessary
6572 (if (not (fboundp 'wholenump
))
6573 (defalias 'wholenump
'natnump
))
6574 ;;;_ > remove-overlays if necessary
6575 (if (not (fboundp 'remove-overlays
))
6576 (defun remove-overlays (&optional beg end name val
)
6577 "Clear BEG and END of overlays whose property NAME has value VAL.
6578 Overlays might be moved and/or split.
6579 BEG and END default respectively to the beginning and end of buffer."
6580 (unless beg
(setq beg
(point-min)))
6581 (unless end
(setq end
(point-max)))
6583 (setq beg
(prog1 end
(setq end beg
))))
6585 (dolist (o (overlays-in beg end
))
6586 (when (eq (overlay-get o name
) val
)
6587 ;; Either push this overlay outside beg...end
6588 ;; or split it to exclude beg...end
6589 ;; or delete it entirely (if it is contained in beg...end).
6590 (if (< (overlay-start o
) beg
)
6591 (if (> (overlay-end o
) end
)
6593 (move-overlay (copy-overlay o
)
6594 (overlay-start o
) beg
)
6595 (move-overlay o end
(overlay-end o
)))
6596 (move-overlay o
(overlay-start o
) beg
))
6597 (if (> (overlay-end o
) end
)
6598 (move-overlay o end
(overlay-end o
))
6599 (delete-overlay o
)))))))
6601 ;;;_ > copy-overlay if necessary -- xemacs ~ 21.4
6602 (if (not (fboundp 'copy-overlay
))
6603 (defun copy-overlay (o)
6604 "Return a copy of overlay O."
6605 (let ((o1 (make-overlay (overlay-start o
) (overlay-end o
)
6606 ;; FIXME: there's no easy way to find the
6607 ;; insertion-type of the two markers.
6608 (overlay-buffer o
)))
6609 (props (overlay-properties o
)))
6611 (overlay-put o1
(pop props
) (pop props
)))
6613 ;;;_ > add-to-invisibility-spec if necessary -- xemacs ~ 21.4
6614 (if (not (fboundp 'add-to-invisibility-spec
))
6615 (defun add-to-invisibility-spec (element)
6616 "Add ELEMENT to `buffer-invisibility-spec'.
6617 See documentation for `buffer-invisibility-spec' for the kind of elements
6619 (if (eq buffer-invisibility-spec t
)
6620 (setq buffer-invisibility-spec
(list t
)))
6621 (setq buffer-invisibility-spec
6622 (cons element buffer-invisibility-spec
))))
6623 ;;;_ > remove-from-invisibility-spec if necessary -- xemacs ~ 21.4
6624 (if (not (fboundp 'remove-from-invisibility-spec
))
6625 (defun remove-from-invisibility-spec (element)
6626 "Remove ELEMENT from `buffer-invisibility-spec'."
6627 (if (consp buffer-invisibility-spec
)
6628 (setq buffer-invisibility-spec
(delete element
6629 buffer-invisibility-spec
)))))
6630 ;;;_ > move-beginning-of-line if necessary -- older emacs, xemacs
6631 (if (not (fboundp 'move-beginning-of-line
))
6632 (defun move-beginning-of-line (arg)
6633 "Move point to beginning of current line as displayed.
6634 \(This disregards invisible newlines such as those
6635 which are part of the text that an image rests on.)
6637 With argument ARG not nil or 1, move forward ARG - 1 lines first.
6638 If point reaches the beginning or end of buffer, it stops there.
6639 To ignore intangibility, bind `inhibit-point-motion-hooks' to t."
6641 (or arg
(setq arg
1))
6643 (condition-case nil
(line-move (1- arg
)) (error nil
)))
6645 ;; Move to beginning-of-line, ignoring fields and invisibles.
6646 (skip-chars-backward "^\n")
6647 (while (and (not (bobp))
6649 (get-char-property (1- (point)) 'invisible
)))
6650 (if (eq buffer-invisibility-spec t
)
6652 (or (memq prop buffer-invisibility-spec
)
6653 (assq prop buffer-invisibility-spec
)))))
6654 (goto-char (if (featurep 'xemacs
)
6655 (previous-property-change (point))
6656 (previous-char-property-change (point))))
6657 (skip-chars-backward "^\n"))
6658 (vertical-motion 0))
6660 ;;;_ > move-end-of-line if necessary -- Emacs < 22.1, xemacs
6661 (if (not (fboundp 'move-end-of-line
))
6662 (defun move-end-of-line (arg)
6663 "Move point to end of current line as displayed.
6664 \(This disregards invisible newlines such as those
6665 which are part of the text that an image rests on.)
6667 With argument ARG not nil or 1, move forward ARG - 1 lines first.
6668 If point reaches the beginning or end of buffer, it stops there.
6669 To ignore intangibility, bind `inhibit-point-motion-hooks' to t."
6671 (or arg
(setq arg
1))
6676 (let ((goal-column 0))
6677 (and (condition-case nil
6678 (or (line-move arg
) t
)
6686 (get-char-property (1- (point))
6688 (if (eq buffer-invisibility-spec t
)
6691 buffer-invisibility-spec
)
6693 buffer-invisibility-spec
)))))
6695 (previous-char-property-change (point))))
6699 (if (and (> (point) newpos
)
6700 (eq (preceding-char) ?
\n))
6702 (if (and (> (point) newpos
) (not (eobp))
6703 (not (eq (following-char) ?
\n)))
6704 ;; If we skipped something intangible
6705 ;; and now we're not really at eol,
6710 ;;;_ > allout-next-single-char-property-change -- alias unless lacking
6711 (defalias 'allout-next-single-char-property-change
6712 (if (fboundp 'next-single-char-property-change
)
6713 'next-single-char-property-change
6714 'next-single-property-change
)
6715 ;; No docstring because xemacs defalias doesn't support it.
6717 ;;;_ > allout-previous-single-char-property-change -- alias unless lacking
6718 (defalias 'allout-previous-single-char-property-change
6719 (if (fboundp 'previous-single-char-property-change
)
6720 'previous-single-char-property-change
6721 'previous-single-property-change
)
6722 ;; No docstring because xemacs defalias doesn't support it.
6724 ;;;_ > allout-set-buffer-multibyte
6725 (if (fboundp 'set-buffer-multibyte
)
6726 (defalias 'allout-set-buffer-multibyte
'set-buffer-multibyte
)
6728 ;; this definition is used only in older or alternative emacs, where
6729 ;; the setting is our only recourse.
6730 (defun allout-set-buffer-multibyte (is-multibyte)
6731 (set enable-multibyte-characters is-multibyte
))))
6732 ;;;_ > allout-select-safe-coding-system
6733 (defalias 'allout-select-safe-coding-system
6734 (if (fboundp 'select-safe-coding-system
)
6735 'select-safe-coding-system
6736 'detect-coding-region
)
6738 ;;;_ > allout-substring-no-properties
6739 ;; define as alias first, so byte compiler is happy.
6740 (defalias 'allout-substring-no-properties
'substring-no-properties
)
6741 ;; then supplant with definition if underlying alias absent.
6742 (if (not (fboundp 'substring-no-properties
))
6743 (defun allout-substring-no-properties (string &optional start end
)
6744 (substring string
(or start
0) end
))
6748 ;;;_ > allout-bullet-isearch (&optional bullet)
6749 (defun allout-bullet-isearch (&optional bullet
)
6750 "Isearch (regexp) for topic with bullet BULLET."
6753 (setq bullet
(solicit-char-in-string
6754 "ISearch for topic with bullet: "
6755 (regexp-sans-escapes allout-bullets-string
))))
6757 (let ((isearch-regexp t
)
6758 (isearch-string (concat "^"
6759 allout-header-prefix
6762 (isearch-repeat 'forward
)
6765 ;;;_ #11 Unit tests -- this should be last item before "Provide"
6766 ;;;_ > allout-run-unit-tests ()
6767 (defun allout-run-unit-tests ()
6768 "Run the various allout unit tests."
6769 (message "Running allout tests...")
6770 (allout-test-resumptions)
6771 (message "Running allout tests... Done.")
6773 ;;;_ : test resumptions:
6774 ;;;_ > allout-tests-obliterate-variable (name)
6775 (defun allout-tests-obliterate-variable (name)
6776 "Completely unbind variable with NAME."
6777 (if (local-variable-p name
(current-buffer)) (kill-local-variable name
))
6778 (while (boundp name
) (makunbound name
)))
6779 ;;;_ > allout-test-resumptions ()
6780 (defvar allout-tests-globally-unbound nil
6781 "Fodder for allout resumptions tests -- defvar just for byte compiler.")
6782 (defvar allout-tests-globally-true nil
6783 "Fodder for allout resumptions tests -- defvar just for byte compiler.")
6784 (defvar allout-tests-locally-true nil
6785 "Fodder for allout resumptions tests -- defvar just for byte compiler.")
6786 (defun allout-test-resumptions ()
6787 "Exercise allout resumptions."
6788 ;; for each resumption case, we also test that the right local/global
6789 ;; scopes are affected during resumption effects:
6791 ;; ensure that previously unbound variables return to the unbound state.
6793 (allout-tests-obliterate-variable 'allout-tests-globally-unbound
)
6794 (allout-add-resumptions '(allout-tests-globally-unbound t
))
6795 (assert (not (default-boundp 'allout-tests-globally-unbound
)))
6796 (assert (local-variable-p 'allout-tests-globally-unbound
(current-buffer)))
6797 (assert (boundp 'allout-tests-globally-unbound
))
6798 (assert (equal allout-tests-globally-unbound t
))
6799 (allout-do-resumptions)
6800 (assert (not (local-variable-p 'allout-tests-globally-unbound
6802 (assert (not (boundp 'allout-tests-globally-unbound
))))
6804 ;; ensure that variable with prior global value is resumed
6806 (allout-tests-obliterate-variable 'allout-tests-globally-true
)
6807 (setq allout-tests-globally-true t
)
6808 (allout-add-resumptions '(allout-tests-globally-true nil
))
6809 (assert (equal (default-value 'allout-tests-globally-true
) t
))
6810 (assert (local-variable-p 'allout-tests-globally-true
(current-buffer)))
6811 (assert (equal allout-tests-globally-true nil
))
6812 (allout-do-resumptions)
6813 (assert (not (local-variable-p 'allout-tests-globally-true
6815 (assert (boundp 'allout-tests-globally-true
))
6816 (assert (equal allout-tests-globally-true t
)))
6818 ;; ensure that prior local value is resumed
6820 (allout-tests-obliterate-variable 'allout-tests-locally-true
)
6821 (set (make-local-variable 'allout-tests-locally-true
) t
)
6822 (assert (not (default-boundp 'allout-tests-locally-true
))
6823 nil
(concat "Test setup mistake -- variable supposed to"
6824 " not have global binding, but it does."))
6825 (assert (local-variable-p 'allout-tests-locally-true
(current-buffer))
6826 nil
(concat "Test setup mistake -- variable supposed to have"
6827 " local binding, but it lacks one."))
6828 (allout-add-resumptions '(allout-tests-locally-true nil
))
6829 (assert (not (default-boundp 'allout-tests-locally-true
)))
6830 (assert (local-variable-p 'allout-tests-locally-true
(current-buffer)))
6831 (assert (equal allout-tests-locally-true nil
))
6832 (allout-do-resumptions)
6833 (assert (boundp 'allout-tests-locally-true
))
6834 (assert (local-variable-p 'allout-tests-locally-true
(current-buffer)))
6835 (assert (equal allout-tests-locally-true t
))
6836 (assert (not (default-boundp 'allout-tests-locally-true
))))
6838 ;; ensure that last of multiple resumptions holds, for various scopes.
6840 (allout-tests-obliterate-variable 'allout-tests-globally-unbound
)
6841 (allout-tests-obliterate-variable 'allout-tests-globally-true
)
6842 (setq allout-tests-globally-true t
)
6843 (allout-tests-obliterate-variable 'allout-tests-locally-true
)
6844 (set (make-local-variable 'allout-tests-locally-true
) t
)
6845 (allout-add-resumptions '(allout-tests-globally-unbound t
)
6846 '(allout-tests-globally-true nil
)
6847 '(allout-tests-locally-true nil
))
6848 (allout-add-resumptions '(allout-tests-globally-unbound 2)
6849 '(allout-tests-globally-true 3)
6850 '(allout-tests-locally-true 4))
6851 ;; reestablish many of the basic conditions are maintained after re-add:
6852 (assert (not (default-boundp 'allout-tests-globally-unbound
)))
6853 (assert (local-variable-p 'allout-tests-globally-unbound
(current-buffer)))
6854 (assert (equal allout-tests-globally-unbound
2))
6855 (assert (default-boundp 'allout-tests-globally-true
))
6856 (assert (local-variable-p 'allout-tests-globally-true
(current-buffer)))
6857 (assert (equal allout-tests-globally-true
3))
6858 (assert (not (default-boundp 'allout-tests-locally-true
)))
6859 (assert (local-variable-p 'allout-tests-locally-true
(current-buffer)))
6860 (assert (equal allout-tests-locally-true
4))
6861 (allout-do-resumptions)
6862 (assert (not (local-variable-p 'allout-tests-globally-unbound
6864 (assert (not (boundp 'allout-tests-globally-unbound
)))
6865 (assert (not (local-variable-p 'allout-tests-globally-true
6867 (assert (boundp 'allout-tests-globally-true
))
6868 (assert (equal allout-tests-globally-true t
))
6869 (assert (boundp 'allout-tests-locally-true
))
6870 (assert (local-variable-p 'allout-tests-locally-true
(current-buffer)))
6871 (assert (equal allout-tests-locally-true t
))
6872 (assert (not (default-boundp 'allout-tests-locally-true
))))
6874 ;; ensure that deliberately unbinding registered variables doesn't foul things
6876 (allout-tests-obliterate-variable 'allout-tests-globally-unbound
)
6877 (allout-tests-obliterate-variable 'allout-tests-globally-true
)
6878 (setq allout-tests-globally-true t
)
6879 (allout-tests-obliterate-variable 'allout-tests-locally-true
)
6880 (set (make-local-variable 'allout-tests-locally-true
) t
)
6881 (allout-add-resumptions '(allout-tests-globally-unbound t
)
6882 '(allout-tests-globally-true nil
)
6883 '(allout-tests-locally-true nil
))
6884 (allout-tests-obliterate-variable 'allout-tests-globally-unbound
)
6885 (allout-tests-obliterate-variable 'allout-tests-globally-true
)
6886 (allout-tests-obliterate-variable 'allout-tests-locally-true
)
6887 (allout-do-resumptions))
6889 ;;;_ % Run unit tests if `allout-run-unit-tests-after-load' is true:
6890 (when allout-run-unit-tests-on-load
6891 (allout-run-unit-tests))
6896 ;;;_* Local emacs vars.
6897 ;; The following `allout-layout' local variable setting:
6898 ;; - closes all topics from the first topic to just before the third-to-last,
6899 ;; - shows the children of the third to last (config vars)
6900 ;; - and the second to last (code section),
6901 ;; - and closes the last topic (this local-variables section).
6903 ;;allout-layout: (0 : -1 -1 0)
6906 ;;; allout.el ends here