*** empty log message ***
[emacs.git] / lisp / allout.el
blob40a6b76bb1a3760a250ce08d61090d9fd1acfa1b
1 ;;;_* allout.el --- Extensive outline mode for use alone and with other modes.
3 ;; Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc.
5 ;; Author: Ken Manheimer <klm@python.org>
6 ;; Maintainer: Ken Manheimer <klm@python.org>
7 ;; Created: Dec 1991 - first release to usenet
8 ;; Version: $Id: allout.el,v 4.35 2000/02/01 15:58:14 klm Exp klm $||
9 ;; Keywords: outline mode wp languages
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software; you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation; either version 2, or (at your option)
16 ;; any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs; see the file COPYING. If not, write to the
25 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
26 ;; Boston, MA 02111-1307, USA.
28 ;;;_* Commentary:
30 ;; Allout outline mode provides extensive outline formatting and
31 ;; and manipulation beyond standard emacs outline mode. It provides
32 ;; for structured editing of outlines, as well as navigation and
33 ;; exposure. It also provides for syntax-sensitive text like
34 ;; programming languages. (For an example, see the allout code
35 ;; itself, which is organized in ;; an outline framework.)
36 ;;
37 ;; In addition to outline navigation and exposure, allout includes:
38 ;;
39 ;; - topic-oriented repositioning, cut, and paste
40 ;; - integral outline exposure-layout
41 ;; - incremental search with dynamic exposure and reconcealment of hidden text
42 ;; - automatic topic-number maintenance
43 ;; - "Hot-spot" operation, for single-keystroke maneuvering and
44 ;; exposure control. (See the outline-mode docstring.)
45 ;;
46 ;; and many other features.
47 ;;
48 ;; The outline menubar additions provide quick reference to many of
49 ;; the features, and see the docstring of the variable `outline-init'
50 ;; for instructions on priming your emacs session for automatic
51 ;; activation of outline-mode.
52 ;;
53 ;; See the docstring of the variables `outline-layout' and
54 ;; `outline-auto-activation' for details on automatic activation of
55 ;; allout outline-mode as a minor mode. (It has changed since allout
56 ;; 3.x, for those of you that depend on the old method.)
58 ;; Note - the lines beginning with `;;;_' are outline topic headers.
59 ;; Just `ESC-x eval-current-buffer' to give it a whirl.
61 ;; Ken Manheimer klm@python.org
63 ;;;_* Provide
64 (provide 'outline)
65 (provide 'allout)
67 ;;;_* USER CUSTOMIZATION VARIABLES:
68 (defgroup allout nil
69 "Extensive outline mode for use alone and with other modes."
70 :prefix "outline-"
71 :group 'outlines)
73 ;;;_ + Layout, Mode, and Topic Header Configuration
75 ;;;_ = outline-auto-activation
76 (defcustom outline-auto-activation nil
77 "*Regulates auto-activation modality of allout outlines - see `outline-init'.
79 Setq-default by `outline-init' to regulate whether or not allout
80 outline mode is automatically activated when the buffer-specific
81 variable `outline-layout' is non-nil, and whether or not the layout
82 dictated by `outline-layout' should be imposed on mode activation.
84 With value `t', auto-mode-activation and auto-layout are enabled.
85 \(This also depends on `outline-find-file-hooks' being installed in
86 `find-file-hooks', which is also done by `outline-init'.)
88 With value `ask', auto-mode-activation is enabled, and endorsement for
89 performing auto-layout is asked of the user each time.
91 With value `activate', only auto-mode-activation is enabled,
92 auto-layout is not.
94 With value `nil', neither auto-mode-activation nor auto-layout are
95 enabled.
97 See the docstring for `outline-init' for the proper interface to
98 this variable."
99 :type '(choice (const :tag "On" t)
100 (const :tag "Ask about layout" "ask")
101 (const :tag "Mode only" "activate")
102 (const :tag "Off" nil))
103 :group 'allout)
104 ;;;_ = outline-layout
105 (defvar outline-layout nil
106 "*Layout specification and provisional mode trigger for allout outlines.
108 Buffer-specific.
110 A list value specifies a default layout for the current buffer, to be
111 applied upon activation of allout outline-mode. Any non-nil value will
112 automatically trigger allout outline-mode, provided `outline-init'
113 has been called to enable it.
115 See the docstring for `outline-init' for details on setting up for
116 auto-mode-activation, and for `outline-expose-topic' for the format of
117 the layout specification.
119 You can associate a particular outline layout with a file by setting
120 this var via the file's local variables. For example, the following
121 lines at the bottom of an Emacs Lisp file:
123 ;;;Local variables:
124 ;;;outline-layout: \(0 : -1 -1 0)
125 ;;;End:
127 will, modulo the above-mentioned conditions, cause the mode to be
128 activated when the file is visited, followed by the equivalent of
129 `\(outline-expose-topic 0 : -1 -1 0)'. \(This is the layout used for
130 the allout.el, itself.)
132 Also, allout's mode-specific provisions will make topic prefixes default
133 to the comment-start string, if any, of the language of the file. This
134 is modulo the setting of `outline-use-mode-specific-leader', which see.")
135 (make-variable-buffer-local 'outline-layout)
136 ;;;_ = outline-show-bodies
137 (defcustom outline-show-bodies nil
138 "*If non-nil, show entire body when exposing a topic, rather than
139 just the header."
140 :type 'boolean
141 :group 'allout)
142 (make-variable-buffer-local 'outline-show-bodies)
144 ;;;_ = outline-header-prefix
145 (defcustom outline-header-prefix "."
146 "*Leading string which helps distinguish topic headers.
148 Outline topic header lines are identified by a leading topic
149 header prefix, which mostly have the value of this var at their front.
150 \(Level 1 topics are exceptions. They consist of only a single
151 character, which is typically set to the outline-primary-bullet. Many
152 outlines start at level 2 to avoid this discrepancy."
153 :type 'string
154 :group 'allout)
155 (make-variable-buffer-local 'outline-header-prefix)
156 ;;;_ = outline-primary-bullet
157 (defcustom outline-primary-bullet "*"
158 "Bullet used for top-level outline topics.
160 Outline topic header lines are identified by a leading topic header
161 prefix, which is concluded by bullets that includes the value of this
162 var and the respective outline-*-bullets-string vars.
164 The value of an asterisk (`*') provides for backwards compatibility
165 with the original emacs outline mode. See outline-plain-bullets-string
166 and outline-distinctive-bullets-string for the range of available
167 bullets."
168 :type 'string
169 :group 'allout)
170 (make-variable-buffer-local 'outline-primary-bullet)
171 ;;;_ = outline-plain-bullets-string
172 (defcustom outline-plain-bullets-string ".:,;"
173 "*The bullets normally used in outline topic prefixes.
175 See `outline-distinctive-bullets-string' for the other kind of
176 bullets.
178 DO NOT include the close-square-bracket, `]', as a bullet.
180 Outline mode has to be reactivated in order for changes to the value
181 of this var to take effect."
182 :type 'string
183 :group 'allout)
184 (make-variable-buffer-local 'outline-plain-bullets-string)
185 ;;;_ = outline-distinctive-bullets-string
186 (defcustom outline-distinctive-bullets-string "*+-=>([{}&!?#%\"X@$~_\\"
187 "*Persistent outline header bullets used to distinguish special topics.
189 These bullets are used to distinguish topics from the run-of-the-mill
190 ones. They are not used in the standard topic headers created by
191 the topic-opening, shifting, and rebulleting \(eg, on topic shift,
192 topic paste, blanket rebulleting) routines, but are offered among the
193 choices for rebulleting. They are not altered by the above automatic
194 rebulleting, so they can be used to characterize topics, eg:
196 `?' question topics
197 `\(' parenthetic comment \(with a matching close paren inside)
198 `[' meta-note \(with a matching close ] inside)
199 `\"' a quote
200 `=' value settings
201 `~' \"more or less\"
203 ... just for example. (`#' typically has a special meaning to the
204 software, according to the value of `outline-numbered-bullet'.)
206 See `outline-plain-bullets-string' for the selection of
207 alternating bullets.
209 You must run `set-outline-regexp' in order for outline mode to
210 reconcile to changes of this value.
212 DO NOT include the close-square-bracket, `]', on either of the bullet
213 strings."
214 :type 'string
215 :group 'allout)
216 (make-variable-buffer-local 'outline-distinctive-bullets-string)
218 ;;;_ = outline-use-mode-specific-leader
219 (defcustom outline-use-mode-specific-leader t
220 "*When non-nil, use mode-specific topic-header prefixes.
222 Allout outline mode will use the mode-specific `outline-mode-leaders'
223 and/or comment-start string, if any, to lead the topic prefix string,
224 so topic headers look like comments in the programming language.
226 String values are used as they stand.
228 Value `t' means to first check for assoc value in `outline-mode-leaders'
229 alist, then use comment-start string, if any, then use default \(`.').
230 \(See note about use of comment-start strings, below.)
232 Set to the symbol for either of `outline-mode-leaders' or
233 `comment-start' to use only one of them, respectively.
235 Value `nil' means to always use the default \(`.').
237 comment-start strings that do not end in spaces are tripled, and an
238 `_' underscore is tacked on the end, to distinguish them from regular
239 comment strings. comment-start strings that do end in spaces are not
240 tripled, but an underscore is substituted for the space. [This
241 presumes that the space is for appearance, not comment syntax. You
242 can use `outline-mode-leaders' to override this behavior, when
243 incorrect.]"
244 :type '(choice (const t) (const nil) string
245 (const outline-mode-leaders)
246 (const comment-start))
247 :group 'allout)
248 ;;;_ = outline-mode-leaders
249 (defvar outline-mode-leaders '()
250 "Specific outline-prefix leading strings per major modes.
252 Entries will be used instead or in lieu of mode-specific
253 comment-start strings. See also `outline-use-mode-specific-leader'.
255 If you're constructing a string that will comment-out outline
256 structuring so it can be included in program code, append an extra
257 character, like an \"_\" underscore, to distinguish the lead string
258 from regular comments that start at bol.")
260 ;;;_ = outline-old-style-prefixes
261 (defcustom outline-old-style-prefixes nil
262 "*When non-nil, use only old-and-crusty outline-mode `*' topic prefixes.
264 Non-nil restricts the topic creation and modification
265 functions to asterix-padded prefixes, so they look exactly
266 like the original emacs-outline style prefixes.
268 Whatever the setting of this variable, both old and new style prefixes
269 are always respected by the topic maneuvering functions."
270 :type 'boolean
271 :group 'allout)
272 (make-variable-buffer-local 'outline-old-style-prefixes)
273 ;;;_ = outline-stylish-prefixes - alternating bullets
274 (defcustom outline-stylish-prefixes t
275 "*Do fancy stuff with topic prefix bullets according to level, etc.
277 Non-nil enables topic creation, modification, and repositioning
278 functions to vary the topic bullet char (the char that marks the topic
279 depth) just preceding the start of the topic text) according to level.
280 Otherwise, only asterisks (`*') and distinctive bullets are used.
282 This is how an outline can look (but sans indentation) with stylish
283 prefixes:
285 * Top level
286 .* A topic
287 . + One level 3 subtopic
288 . . One level 4 subtopic
289 . . A second 4 subtopic
290 . + Another level 3 subtopic
291 . #1 A numbered level 4 subtopic
292 . #2 Another
293 . ! Another level 4 subtopic with a different distinctive bullet
294 . #4 And another numbered level 4 subtopic
296 This would be an outline with stylish prefixes inhibited (but the
297 numbered and other distinctive bullets retained):
299 * Top level
300 .* A topic
301 . * One level 3 subtopic
302 . * One level 4 subtopic
303 . * A second 4 subtopic
304 . * Another level 3 subtopic
305 . #1 A numbered level 4 subtopic
306 . #2 Another
307 . ! Another level 4 subtopic with a different distinctive bullet
308 . #4 And another numbered level 4 subtopic
310 Stylish and constant prefixes (as well as old-style prefixes) are
311 always respected by the topic maneuvering functions, regardless of
312 this variable setting.
314 The setting of this var is not relevant when outline-old-style-prefixes
315 is non-nil."
316 :type 'boolean
317 :group 'allout)
318 (make-variable-buffer-local 'outline-stylish-prefixes)
320 ;;;_ = outline-numbered-bullet
321 (defcustom outline-numbered-bullet "#"
322 "*String designating bullet of topics that have auto-numbering; nil for none.
324 Topics having this bullet have automatic maintenance of a sibling
325 sequence-number tacked on, just after the bullet. Conventionally set
326 to \"#\", you can set it to a bullet of your choice. A nil value
327 disables numbering maintenance."
328 :type '(choice (const nil) string)
329 :group 'allout)
330 (make-variable-buffer-local 'outline-numbered-bullet)
331 ;;;_ = outline-file-xref-bullet
332 (defcustom outline-file-xref-bullet "@"
333 "*Bullet signifying file cross-references, for `outline-resolve-xref'.
335 Set this var to the bullet you want to use for file cross-references."
336 :type '(choice (const nil) string)
337 :group 'allout)
339 ;;;_ = outline-presentation-padding
340 (defcustom outline-presentation-padding 2
341 "*Presentation-format white-space padding factor, for greater indent."
342 :type 'integer
343 :group 'allout)
345 (make-variable-buffer-local 'outline-presentation-padding)
347 ;;;_ = outline-abbreviate-flattened-numbering
348 (defcustom outline-abbreviate-flattened-numbering nil
349 "*If non-nil, `outline-flatten-exposed-to-buffer' abbreviates topic
350 numbers to minimal amount with some context. Otherwise, entire
351 numbers are always used."
352 :type 'boolean
353 :group 'allout)
355 ;;;_ + LaTeX formatting
356 ;;;_ - outline-number-pages
357 (defcustom outline-number-pages nil
358 "*Non-nil turns on page numbering for LaTeX formatting of an outline."
359 :type 'boolean
360 :group 'allout)
361 ;;;_ - outline-label-style
362 (defcustom outline-label-style "\\large\\bf"
363 "*Font and size of labels for LaTeX formatting of an outline."
364 :type 'string
365 :group 'allout)
366 ;;;_ - outline-head-line-style
367 (defcustom outline-head-line-style "\\large\\sl "
368 "*Font and size of entries for LaTeX formatting of an outline."
369 :type 'string
370 :group 'allout)
371 ;;;_ - outline-body-line-style
372 (defcustom outline-body-line-style " "
373 "*Font and size of entries for LaTeX formatting of an outline."
374 :type 'string
375 :group 'allout)
376 ;;;_ - outline-title-style
377 (defcustom outline-title-style "\\Large\\bf"
378 "*Font and size of titles for LaTeX formatting of an outline."
379 :type 'string
380 :group 'allout)
381 ;;;_ - outline-title
382 (defcustom outline-title '(or buffer-file-name (current-buffer-name))
383 "*Expression to be evaluated to determine the title for LaTeX
384 formatted copy."
385 :type 'sexp
386 :group 'allout)
387 ;;;_ - outline-line-skip
388 (defcustom outline-line-skip ".05cm"
389 "*Space between lines for LaTeX formatting of an outline."
390 :type 'string
391 :group 'allout)
392 ;;;_ - outline-indent
393 (defcustom outline-indent ".3cm"
394 "*LaTeX formatted depth-indent spacing."
395 :type 'string
396 :group 'allout)
398 ;;;_ + Miscellaneous customization
400 ;;;_ = outline-command-prefix
401 (defcustom outline-command-prefix "\C-c"
402 "*Key sequence to be used as prefix for outline mode command key bindings."
403 :type 'string
404 :group 'allout)
406 ;;;_ = outline-keybindings-list
407 ;;; You have to reactivate outline-mode - `(outline-mode t)' - to
408 ;;; institute changes to this var.
409 (defvar outline-keybindings-list ()
410 "*List of outline-mode key / function bindings, for outline-mode-map.
412 String or vector key will be prefaced with outline-command-prefix,
413 unless optional third, non-nil element is present.")
414 (setq outline-keybindings-list
416 ; Motion commands:
417 ("\C-n" outline-next-visible-heading)
418 ("\C-p" outline-previous-visible-heading)
419 ("\C-u" outline-up-current-level)
420 ("\C-f" outline-forward-current-level)
421 ("\C-b" outline-backward-current-level)
422 ("\C-a" outline-beginning-of-current-entry)
423 ("\C-e" outline-end-of-current-entry)
424 ; Exposure commands:
425 ("\C-i" outline-show-children)
426 ("\C-s" outline-show-current-subtree)
427 ("\C-h" outline-hide-current-subtree)
428 ("\C-o" outline-show-current-entry)
429 ("!" outline-show-all)
430 ; Alteration commands:
431 (" " outline-open-sibtopic)
432 ("." outline-open-subtopic)
433 ("," outline-open-supertopic)
434 ("'" outline-shift-in)
435 (">" outline-shift-in)
436 ("<" outline-shift-out)
437 ("\C-m" outline-rebullet-topic)
438 ("*" outline-rebullet-current-heading)
439 ("#" outline-number-siblings)
440 ("\C-k" outline-kill-line t)
441 ("\C-y" outline-yank t)
442 ("\M-y" outline-yank-pop t)
443 ("\C-k" outline-kill-topic)
444 ; Miscellaneous commands:
445 ;([?\C-\ ] outline-mark-topic)
446 ("@" outline-resolve-xref)
447 ("=c" outline-copy-exposed-to-buffer)
448 ("=i" outline-indented-exposed-to-buffer)
449 ("=t" outline-latexify-exposed)
450 ("=p" outline-flatten-exposed-to-buffer)))
452 ;;;_ = outline-isearch-dynamic-expose
453 (defcustom outline-isearch-dynamic-expose t
454 "*Non-nil enable dynamic exposure of hidden incremental-search
455 targets as they're encountered."
456 :type 'boolean
457 :group 'allout)
458 (make-variable-buffer-local 'outline-isearch-dynamic-expose)
460 ;;;_ = outline-use-hanging-indents
461 (defcustom outline-use-hanging-indents t
462 "*If non-nil, topic body text auto-indent defaults to indent of the header.
463 Ie, it is indented to be just past the header prefix. This is
464 relevant mostly for use with indented-text-mode, or other situations
465 where auto-fill occurs.
467 \[This feature no longer depends in any way on the `filladapt.el'
468 lisp-archive package.\]"
469 :type 'boolean
470 :group 'allout)
471 (make-variable-buffer-local 'outline-use-hanging-indents)
473 ;;;_ = outline-reindent-bodies
474 (defcustom outline-reindent-bodies (if outline-use-hanging-indents
475 'text)
476 "*Non-nil enables auto-adjust of topic body hanging indent with depth shifts.
478 When active, topic body lines that are indented even with or beyond
479 their topic header are reindented to correspond with depth shifts of
480 the header.
482 A value of `t' enables reindent in non-programming-code buffers, ie
483 those that do not have the variable `comment-start' set. A value of
484 `force' enables reindent whether or not `comment-start' is set."
485 :type '(choice (const nil) (const t) (const text) (const force))
486 :group 'allout)
488 (make-variable-buffer-local 'outline-reindent-bodies)
490 ;;;_ = outline-inhibit-protection
491 (defcustom outline-inhibit-protection nil
492 "*Non-nil disables warnings and confirmation-checks for concealed-text edits.
494 Outline mode uses emacs change-triggered functions to detect unruly
495 changes to concealed regions. Set this var non-nil to disable the
496 protection, potentially increasing text-entry responsiveness a bit.
498 This var takes effect at outline-mode activation, so you may have to
499 deactivate and then reactivate the mode if you want to toggle the
500 behavior."
501 :type 'boolean
502 :group 'allout)
504 ;;;_* CODE - no user customizations below.
506 ;;;_ #1 Internal Outline Formatting and Configuration
507 ;;;_ : Version
508 ;;;_ = outline-version
509 (defvar outline-version
510 (let ((rcs-rev "$Revision: 4.35 $"))
511 (condition-case err
512 (save-match-data
513 (string-match "Revision: \\([0-9]+\\.[0-9]+\\)" rcs-rev)
514 (substring rcs-rev (match-beginning 1) (match-end 1)))
515 ('error rcs-rev)))
516 "Revision number of currently loaded outline package. \(allout.el)")
517 ;;;_ > outline-version
518 (defun outline-version (&optional here)
519 "Return string describing the loaded outline version."
520 (interactive "P")
521 (let ((msg (concat "Allout Outline Mode v " outline-version)))
522 (if here (insert-string msg))
523 (message "%s" msg)
524 msg))
525 ;;;_ : Topic header format
526 ;;;_ = outline-regexp
527 (defvar outline-regexp ""
528 "*Regular expression to match the beginning of a heading line.
530 Any line whose beginning matches this regexp is considered a
531 heading. This var is set according to the user configuration vars
532 by set-outline-regexp.")
533 (make-variable-buffer-local 'outline-regexp)
534 ;;;_ = outline-bullets-string
535 (defvar outline-bullets-string ""
536 "A string dictating the valid set of outline topic bullets.
538 This var should *not* be set by the user - it is set by `set-outline-regexp',
539 and is produced from the elements of `outline-plain-bullets-string'
540 and `outline-distinctive-bullets-string'.")
541 (make-variable-buffer-local 'outline-bullets-string)
542 ;;;_ = outline-bullets-string-len
543 (defvar outline-bullets-string-len 0
544 "Length of current buffers' outline-plain-bullets-string.")
545 (make-variable-buffer-local 'outline-bullets-string-len)
546 ;;;_ = outline-line-boundary-regexp
547 (defvar outline-line-boundary-regexp ()
548 "Outline-regexp with outline-style beginning-of-line anchor.
550 \(Ie, C-j, *or* C-m, for prefixes of hidden topics). This is properly
551 set when outline-regexp is produced by `set-outline-regexp', so
552 that (match-beginning 2) and (match-end 2) delimit the prefix.")
553 (make-variable-buffer-local 'outline-line-boundary-regexp)
554 ;;;_ = outline-bob-regexp
555 (defvar outline-bob-regexp ()
556 "Like outline-line-boundary-regexp, for headers at beginning of buffer.
557 \(match-beginning 2) and \(match-end 2) delimit the prefix.")
558 (make-variable-buffer-local 'outline-bob-regexp)
559 ;;;_ = outline-header-subtraction
560 (defvar outline-header-subtraction (1- (length outline-header-prefix))
561 "Outline-header prefix length to subtract when computing topic depth.")
562 (make-variable-buffer-local 'outline-header-subtraction)
563 ;;;_ = outline-plain-bullets-string-len
564 (defvar outline-plain-bullets-string-len (length outline-plain-bullets-string)
565 "Length of outline-plain-bullets-string, updated by set-outline-regexp.")
566 (make-variable-buffer-local 'outline-plain-bullets-string-len)
569 ;;;_ X outline-reset-header-lead (header-lead)
570 (defun outline-reset-header-lead (header-lead)
571 "*Reset the leading string used to identify topic headers."
572 (interactive "sNew lead string: ")
573 (setq outline-header-prefix header-lead)
574 (setq outline-header-subtraction (1- (length outline-header-prefix)))
575 (set-outline-regexp))
576 ;;;_ X outline-lead-with-comment-string (header-lead)
577 (defun outline-lead-with-comment-string (&optional header-lead)
578 "*Set the topic-header leading string to specified string.
580 Useful when for encapsulating outline structure in programming
581 language comments. Returns the leading string."
583 (interactive "P")
584 (if (not (stringp header-lead))
585 (setq header-lead (read-string
586 "String prefix for topic headers: ")))
587 (setq outline-reindent-bodies nil)
588 (outline-reset-header-lead header-lead)
589 header-lead)
590 ;;;_ > outline-infer-header-lead ()
591 (defun outline-infer-header-lead ()
592 "Determine appropriate `outline-header-prefix'.
594 Works according to settings of:
596 `comment-start'
597 `outline-header-prefix' (default)
598 `outline-use-mode-specific-leader'
599 and `outline-mode-leaders'.
601 Apply this via \(re)activation of `outline-mode', rather than
602 invoking it directly."
603 (let* ((use-leader (and (boundp 'outline-use-mode-specific-leader)
604 (if (or (stringp outline-use-mode-specific-leader)
605 (memq outline-use-mode-specific-leader
606 '(outline-mode-leaders
607 comment-start
608 t)))
609 outline-use-mode-specific-leader
610 ;; Oops - garbled value, equate with effect of 't:
611 t)))
612 (leader
613 (cond
614 ((not use-leader) nil)
615 ;; Use the explicitly designated leader:
616 ((stringp use-leader) use-leader)
617 (t (or (and (memq use-leader '(t outline-mode-leaders))
618 ;; Get it from outline mode leaders?
619 (cdr (assq major-mode outline-mode-leaders)))
620 ;; ... didn't get from outline-mode-leaders...
621 (and (memq use-leader '(t comment-start))
622 comment-start
623 ;; Use comment-start, maybe tripled, and with
624 ;; underscore:
625 (concat
626 (if (string= " "
627 (substring comment-start
628 (1- (length comment-start))))
629 ;; Use comment-start, sans trailing space:
630 (substring comment-start 0 -1)
631 (concat comment-start comment-start comment-start))
632 ;; ... and append underscore, whichever:
633 "_")))))))
634 (if (not leader)
636 (if (string= leader outline-header-prefix)
637 nil ; no change, nothing to do.
638 (setq outline-header-prefix leader)
639 outline-header-prefix))))
640 ;;;_ > outline-infer-body-reindent ()
641 (defun outline-infer-body-reindent ()
642 "Determine proper setting for `outline-reindent-bodies'.
644 Depends on default setting of `outline-reindent-bodies' \(which see)
645 and presence of setting for `comment-start', to tell whether the
646 file is programming code."
647 (if (and outline-reindent-bodies
648 comment-start
649 (not (eq 'force outline-reindent-bodies)))
650 (setq outline-reindent-bodies nil)))
651 ;;;_ > set-outline-regexp ()
652 (defun set-outline-regexp ()
653 "Generate proper topic-header regexp form for outline functions.
655 Works with respect to `outline-plain-bullets-string' and
656 `outline-distinctive-bullets-string'."
658 (interactive)
659 ;; Derive outline-bullets-string from user configured components:
660 (setq outline-bullets-string "")
661 (let ((strings (list 'outline-plain-bullets-string
662 'outline-distinctive-bullets-string
663 'outline-primary-bullet))
664 cur-string
665 cur-len
666 cur-char
667 cur-char-string
668 index
669 new-string)
670 (while strings
671 (setq new-string "") (setq index 0)
672 (setq cur-len (length (setq cur-string (symbol-value (car strings)))))
673 (while (< index cur-len)
674 (setq cur-char (aref cur-string index))
675 (setq outline-bullets-string
676 (concat outline-bullets-string
677 (cond
678 ; Single dash would denote a
679 ; sequence, repeated denotes
680 ; a dash:
681 ((eq cur-char ?-) "--")
682 ; literal close-square-bracket
683 ; doesn't work right in the
684 ; expr, exclude it:
685 ((eq cur-char ?\]) "")
686 (t (regexp-quote (char-to-string cur-char))))))
687 (setq index (1+ index)))
688 (setq strings (cdr strings)))
690 ;; Derive next for repeated use in outline-pending-bullet:
691 (setq outline-plain-bullets-string-len (length outline-plain-bullets-string))
692 (setq outline-header-subtraction (1- (length outline-header-prefix)))
693 ;; Produce the new outline-regexp:
694 (setq outline-regexp (concat "\\(\\"
695 outline-header-prefix
696 "[ \t]*["
697 outline-bullets-string
698 "]\\)\\|\\"
699 outline-primary-bullet
700 "+\\|\^l"))
701 (setq outline-line-boundary-regexp
702 (concat "\\([\n\r]\\)\\(" outline-regexp "\\)"))
703 (setq outline-bob-regexp
704 (concat "\\(\\`\\)\\(" outline-regexp "\\)"))
706 ;;;_ : Key bindings
707 ;;;_ = outline-mode-map
708 (defvar outline-mode-map nil "Keybindings for (allout) outline minor mode.")
709 ;;;_ > produce-outline-mode-map (keymap-alist &optional base-map)
710 (defun produce-outline-mode-map (keymap-list &optional base-map)
711 "Produce keymap for use as outline-mode-map, from keymap-list.
713 Built on top of optional BASE-MAP, or empty sparse map if none specified.
714 See doc string for outline-keybindings-list for format of binding list."
715 (let ((map (or base-map (make-sparse-keymap)))
716 (pref (list outline-command-prefix)))
717 (mapcar (function
718 (lambda (cell)
719 (let ((add-pref (null (cdr (cdr cell))))
720 (key-suff (list (car cell))))
721 (apply 'define-key
722 (list map
723 (apply 'concat (if add-pref
724 (append pref key-suff)
725 key-suff))
726 (car (cdr cell)))))))
727 keymap-list)
728 map))
729 ;;;_ = outline-prior-bindings - being deprecated.
730 (defvar outline-prior-bindings nil
731 "Variable for use in V18, with outline-added-bindings, for
732 resurrecting, on mode deactivation, bindings that existed before
733 activation. Being deprecated.")
734 ;;;_ = outline-added-bindings - being deprecated
735 (defvar outline-added-bindings nil
736 "Variable for use in V18, with outline-prior-bindings, for
737 resurrecting, on mode deactivation, bindings that existed before
738 activation. Being deprecated.")
739 ;;;_ : Menu bar
740 (defun produce-outline-mode-menubar-entries ()
741 (require 'easymenu)
742 (easy-menu-define outline-mode-exposure-menu
743 outline-mode-map
744 "Allout outline exposure menu."
745 '("Exposure"
746 ["Show Entry" outline-show-current-entry t]
747 ["Show Children" outline-show-children t]
748 ["Show Subtree" outline-show-current-subtree t]
749 ["Hide Subtree" outline-hide-current-subtree t]
750 ["Hide Leaves" outline-hide-current-leaves t]
751 "----"
752 ["Show All" outline-show-all t]))
753 (easy-menu-define outline-mode-editing-menu
754 outline-mode-map
755 "Allout outline editing menu."
756 '("Headings"
757 ["Open Sibling" outline-open-sibtopic t]
758 ["Open Subtopic" outline-open-subtopic t]
759 ["Open Supertopic" outline-open-supertopic t]
760 "----"
761 ["Shift Topic In" outline-shift-in t]
762 ["Shift Topic Out" outline-shift-out t]
763 ["Rebullet Topic" outline-rebullet-topic t]
764 ["Rebullet Heading" outline-rebullet-current-heading t]
765 ["Number Siblings" outline-number-siblings t]))
766 (easy-menu-define outline-mode-navigation-menu
767 outline-mode-map
768 "Allout outline navigation menu."
769 '("Navigation"
770 ["Next Visible Heading" outline-next-visible-heading t]
771 ["Previous Visible Heading"
772 outline-previous-visible-heading t]
773 "----"
774 ["Up Level" outline-up-current-level t]
775 ["Forward Current Level" outline-forward-current-level t]
776 ["Backward Current Level"
777 outline-backward-current-level t]
778 "----"
779 ["Beginning of Entry"
780 outline-beginning-of-current-entry t]
781 ["End of Entry" outline-end-of-current-entry t]
782 ["End of Subtree" outline-end-of-current-subtree t]))
783 (easy-menu-define outline-mode-misc-menu
784 outline-mode-map
785 "Allout outlines miscellaneous bindings."
786 '("Misc"
787 ["Version" outline-version t]
788 "----"
789 ["Duplicate Exposed" outline-copy-exposed-to-buffer t]
790 ["Duplicate Exposed, numbered"
791 outline-flatten-exposed-to-buffer t]
792 ["Duplicate Exposed, indented"
793 outline-indented-exposed-to-buffer t]
794 "----"
795 ["Set Header Lead" outline-reset-header-lead t]
796 ["Set New Exposure" outline-expose-topic t])))
797 ;;;_ : Mode-Specific Variable Maintenance Utilities
798 ;;;_ = outline-mode-prior-settings
799 (defvar outline-mode-prior-settings nil
800 "Internal outline mode use; settings to be resumed on mode deactivation.")
801 (make-variable-buffer-local 'outline-mode-prior-settings)
802 ;;;_ > outline-resumptions (name &optional value)
803 (defun outline-resumptions (name &optional value)
805 "Registers or resumes settings over outline-mode activation/deactivation.
807 First arg is NAME of variable affected. Optional second arg is list
808 containing outline-mode-specific VALUE to be imposed on named
809 variable, and to be registered. (It's a list so you can specify
810 registrations of null values.) If no value is specified, the
811 registered value is returned (encapsulated in the list, so the caller
812 can distinguish nil vs no value), and the registration is popped
813 from the list."
815 (let ((on-list (assq name outline-mode-prior-settings))
816 prior-capsule ; By `capsule' i mean a list
817 ; containing a value, so we can
818 ; distinguish nil from no value.
821 (if value
823 ;; Registering:
824 (progn
825 (if on-list
826 nil ; Already preserved prior value - don't mess with it.
827 ;; Register the old value, or nil if previously unbound:
828 (setq outline-mode-prior-settings
829 (cons (list name
830 (if (boundp name) (list (symbol-value name))))
831 outline-mode-prior-settings)))
832 ; And impose the new value, locally:
833 (progn (make-local-variable name)
834 (set name (car value))))
836 ;; Relinquishing:
837 (if (not on-list)
839 ;; Oops, not registered - leave it be:
842 ;; Some registration:
843 ; reestablish it:
844 (setq prior-capsule (car (cdr on-list)))
845 (if prior-capsule
846 (set name (car prior-capsule)) ; Some prior value - reestablish it.
847 (makunbound name)) ; Previously unbound - demolish var.
848 ; Remove registration:
849 (let (rebuild)
850 (while outline-mode-prior-settings
851 (if (not (eq (car outline-mode-prior-settings)
852 on-list))
853 (setq rebuild
854 (cons (car outline-mode-prior-settings)
855 rebuild)))
856 (setq outline-mode-prior-settings
857 (cdr outline-mode-prior-settings)))
858 (setq outline-mode-prior-settings rebuild)))))
860 ;;;_ : Mode-specific incidentals
861 ;;;_ = outline-during-write-cue nil
862 (defvar outline-during-write-cue nil
863 "Used to inhibit outline change-protection during file write.
865 See also `outline-post-command-business', `outline-write-file-hook',
866 `outline-before-change-protect', and `outline-post-command-business'
867 functions.")
868 ;;;_ = outline-pre-was-isearching nil
869 (defvar outline-pre-was-isearching nil
870 "Cue for isearch-dynamic-exposure mechanism, implemented in
871 outline-pre- and -post-command-hooks.")
872 (make-variable-buffer-local 'outline-pre-was-isearching)
873 ;;;_ = outline-isearch-prior-pos nil
874 (defvar outline-isearch-prior-pos nil
875 "Cue for isearch-dynamic-exposure tracking, used by outline-isearch-expose.")
876 (make-variable-buffer-local 'outline-isearch-prior-pos)
877 ;;;_ = outline-isearch-did-quit
878 (defvar outline-isearch-did-quit nil
879 "Distinguishes isearch conclusion and cancellation.
881 Maintained by outline-isearch-abort \(which is wrapped around the real
882 isearch-abort), and monitored by outline-isearch-expose for action.")
883 (make-variable-buffer-local 'outline-isearch-did-quit)
884 ;;;_ = outline-override-protect nil
885 (defvar outline-override-protect nil
886 "Used in outline-mode for regulate of concealed-text protection mechanism.
888 Allout outline mode regulates alteration of concealed text to protect
889 against inadvertent, unnoticed changes. This is for use by specific,
890 native outline functions to temporarily override that protection.
891 It's automatically reset to nil after every buffer modification.")
892 (make-variable-buffer-local 'outline-override-protect)
893 ;;;_ > outline-unprotected (expr)
894 (defmacro outline-unprotected (expr)
895 "Evaluate EXPRESSION with `outline-override-protect' let-bound `t'."
896 `(let ((outline-override-protect t))
897 ,expr))
898 ;;;_ = outline-undo-aggregation
899 (defvar outline-undo-aggregation 30
900 "Amount of successive self-insert actions to bunch together per undo.
902 This is purely a kludge variable, regulating the compensation for a bug in
903 the way that before-change-functions and undo interact.")
904 (make-variable-buffer-local 'outline-undo-aggregation)
905 ;;;_ = file-var-bug hack
906 (defvar outline-v18/19-file-var-hack nil
907 "Horrible hack used to prevent invalid multiple triggering of outline
908 mode from prop-line file-var activation. Used by outline-mode function
909 to track repeats.")
910 ;;;_ > outline-write-file-hook ()
911 (defun outline-write-file-hook ()
912 "In outline mode, run as a local-write-file-hooks activity.
914 Currently just sets `outline-during-write-cue', so outline-change-protection
915 knows to keep inactive during file write."
916 (setq outline-during-write-cue t)
917 nil)
919 ;;;_ #2 Mode activation
920 ;;;_ = outline-mode
921 (defvar outline-mode () "Allout outline mode minor-mode flag.")
922 (make-variable-buffer-local 'outline-mode)
923 ;;;_ > outline-mode-p ()
924 (defmacro outline-mode-p ()
925 "Return t if outline-mode is active in current buffer."
926 'outline-mode)
927 ;;;_ = outline-explicitly-deactivated
928 (defvar outline-explicitly-deactivated nil
929 "Outline-mode was last deliberately deactivated.
930 So outline-post-command-business should not reactivate it...")
931 (make-variable-buffer-local 'outline-explicitly-deactivated)
932 ;;;_ > outline-init (&optional mode)
933 (defun outline-init (&optional mode)
934 "Prime outline-mode to enable/disable auto-activation, wrt `outline-layout'.
936 MODE is one of the following symbols:
938 - nil \(or no argument) deactivate auto-activation/layout;
939 - `activate', enable auto-activation only;
940 - `ask', enable auto-activation, and enable auto-layout but with
941 confirmation for layout operation solicited from user each time;
942 - `report', just report and return the current auto-activation state;
943 - anything else \(eg, t) for auto-activation and auto-layout, without
944 any confirmation check.
946 Use this function to setup your emacs session for automatic activation
947 of allout outline mode, contingent to the buffer-specific setting of
948 the `outline-layout' variable. (See `outline-layout' and
949 `outline-expose-topic' docstrings for more details on auto layout).
951 `outline-init' works by setting up (or removing) the outline-mode
952 find-file-hook, and giving `outline-auto-activation' a suitable
953 setting.
955 To prime your emacs session for full auto-outline operation, include
956 the following two lines in your emacs init file:
958 \(require 'allout)
959 \(outline-init t)"
961 (interactive)
962 (if (interactive-p)
963 (progn
964 (setq mode
965 (completing-read
966 (concat "Select outline auto setup mode "
967 "(empty for report, ? for options) ")
968 '(("nil")("full")("activate")("deactivate")
969 ("ask") ("report") (""))
972 (if (string= mode "")
973 (setq mode 'report)
974 (setq mode (intern-soft mode)))))
975 (let
976 ;; convenience aliases, for consistent ref to respective vars:
977 ((hook 'outline-find-file-hook)
978 (curr-mode 'outline-auto-activation))
980 (cond ((not mode)
981 (setq find-file-hooks (delq hook find-file-hooks))
982 (if (interactive-p)
983 (message "Allout outline mode auto-activation inhibited.")))
984 ((eq mode 'report)
985 (if (not (memq hook find-file-hooks))
986 (outline-init nil)
987 ;; Just punt and use the reports from each of the modes:
988 (outline-init (symbol-value curr-mode))))
989 (t (add-hook 'find-file-hooks hook)
990 (set curr-mode ; `set', not `setq'!
991 (cond ((eq mode 'activate)
992 (message
993 "Outline mode auto-activation enabled.")
994 'activate)
995 ((eq mode 'report)
996 ;; Return the current mode setting:
997 (outline-init mode))
998 ((eq mode 'ask)
999 (message
1000 (concat "Outline mode auto-activation and "
1001 "-layout \(upon confirmation) enabled."))
1002 'ask)
1003 ((message
1004 "Outline mode auto-activation and -layout enabled.")
1005 'full)))))))
1007 ;;;_ > outline-setup-menubar ()
1008 (defun outline-setup-menubar ()
1009 "Populate the current buffer's menubar with allout outline-mode stuff."
1010 (let ((menus (list outline-mode-exposure-menu
1011 outline-mode-editing-menu
1012 outline-mode-navigation-menu
1013 outline-mode-misc-menu))
1014 cur)
1015 (while menus
1016 (setq cur (car menus)
1017 menus (cdr menus))
1018 (easy-menu-add cur))))
1019 ;;;_ > outline-mode (&optional toggle)
1020 ;;;_ : Defun:
1021 (defun outline-mode (&optional toggle)
1022 ;;;_ . Doc string:
1023 "Toggle minor mode for controlling exposure and editing of text outlines.
1025 Optional arg forces mode to re-initialize iff arg is positive num or
1026 symbol. Allout outline mode always runs as a minor mode.
1028 Allout outline mode provides extensive outline-oriented formatting and
1029 manipulation. It enables structural editing of outlines, as well as
1030 navigation and exposure. It also is specifically aimed at
1031 accommodating syntax-sensitive text like programming languages. \(For
1032 an example, see the allout code itself, which is organized as an allout
1033 outline.)
1035 In addition to outline navigation and exposure, allout includes:
1037 - topic-oriented repositioning, cut, and paste
1038 - integral outline exposure-layout
1039 - incremental search with dynamic exposure and reconcealment of hidden text
1040 - automatic topic-number maintenance
1041 - \"Hot-spot\" operation, for single-keystroke maneuvering and
1042 exposure control. \(See the outline-mode docstring.)
1044 and many other features.
1046 Below is a description of the bindings, and then explanation of
1047 special outline-mode features and terminology. See also the outline
1048 menubar additions for quick reference to many of the features, and see
1049 the docstring of the variable `outline-init' for instructions on
1050 priming your emacs session for automatic activation of outline-mode.
1053 The bindings are dictated by the `outline-keybindings-list' and
1054 `outline-command-prefix' variables.
1056 Navigation: Exposure Control:
1057 ---------- ----------------
1058 C-c C-n outline-next-visible-heading | C-c C-h outline-hide-current-subtree
1059 C-c C-p outline-previous-visible-heading | C-c C-i outline-show-children
1060 C-c C-u outline-up-current-level | C-c C-s outline-show-current-subtree
1061 C-c C-f outline-forward-current-level | C-c C-o outline-show-current-entry
1062 C-c C-b outline-backward-current-level | ^U C-c C-s outline-show-all
1063 C-c C-e outline-end-of-current-entry | outline-hide-current-leaves
1064 C-c C-a outline-beginning-of-current-entry, alternately, goes to hot-spot
1066 Topic Header Production:
1067 -----------------------
1068 C-c<SP> outline-open-sibtopic Create a new sibling after current topic.
1069 C-c . outline-open-subtopic ... an offspring of current topic.
1070 C-c , outline-open-supertopic ... a sibling of the current topic's parent.
1072 Topic Level and Prefix Adjustment:
1073 ---------------------------------
1074 C-c > outline-shift-in Shift current topic and all offspring deeper.
1075 C-c < outline-shift-out ... less deep.
1076 C-c<CR> outline-rebullet-topic Reconcile bullets of topic and its offspring
1077 - distinctive bullets are not changed, others
1078 alternated according to nesting depth.
1079 C-c b outline-rebullet-current-heading Prompt for alternate bullet for
1080 current topic.
1081 C-c # outline-number-siblings Number bullets of topic and siblings - the
1082 offspring are not affected. With repeat
1083 count, revoke numbering.
1085 Topic-oriented Killing and Yanking:
1086 ----------------------------------
1087 C-c C-k outline-kill-topic Kill current topic, including offspring.
1088 C-k outline-kill-line Like kill-line, but reconciles numbering, etc.
1089 C-y outline-yank Yank, adjusting depth of yanked topic to
1090 depth of heading if yanking into bare topic
1091 heading (ie, prefix sans text).
1092 M-y outline-yank-pop Is to outline-yank as yank-pop is to yank
1094 Misc commands:
1095 -------------
1096 M-x outlineify-sticky Activate outline mode for current buffer,
1097 and establish a default file-var setting
1098 for `outline-layout'.
1099 C-c C-SPC outline-mark-topic
1100 C-c = c outline-copy-exposed-to-buffer
1101 Duplicate outline, sans concealed text, to
1102 buffer with name derived from derived from
1103 that of current buffer - \"*XXX exposed*\".
1104 C-c = p outline-flatten-exposed-to-buffer
1105 Like above 'copy-exposed', but convert topic
1106 prefixes to section.subsection... numeric
1107 format.
1108 ESC ESC (outline-init t) Setup emacs session for outline mode
1109 auto-activation.
1111 HOT-SPOT Operation
1113 Hot-spot operation provides a means for easy, single-keystroke outline
1114 navigation and exposure control.
1116 \\<outline-mode-map>
1117 When the text cursor is positioned directly on the bullet character of
1118 a topic, regular characters (a to z) invoke the commands of the
1119 corresponding outline-mode keymap control chars. For example, \"f\"
1120 would invoke the command typically bound to \"C-c C-f\"
1121 \(\\[outline-forward-current-level] `outline-forward-current-level').
1123 Thus, by positioning the cursor on a topic bullet, you can execute
1124 the outline navigation and manipulation commands with a single
1125 keystroke. Non-literal chars never get this special translation, so
1126 you can use them to get away from the hot-spot, and back to normal
1127 operation.
1129 Note that the command `outline-beginning-of-current-entry' \(\\[outline-beginning-of-current-entry]\)
1130 will move to the hot-spot when the cursor is already located at the
1131 beginning of the current entry, so you can simply hit \\[outline-beginning-of-current-entry]
1132 twice in a row to get to the hot-spot.
1134 Terminology
1136 Topic hierarchy constituents - TOPICS and SUBTOPICS:
1138 TOPIC: A basic, coherent component of an emacs outline. It can
1139 contain other topics, and it can be subsumed by other topics,
1140 CURRENT topic:
1141 The visible topic most immediately containing the cursor.
1142 DEPTH: The degree of nesting of a topic; it increases with
1143 containment. Also called the:
1144 LEVEL: The same as DEPTH.
1146 ANCESTORS:
1147 The topics that contain a topic.
1148 PARENT: A topic's immediate ancestor. It has a depth one less than
1149 the topic.
1150 OFFSPRING:
1151 The topics contained by a topic;
1152 SUBTOPIC:
1153 An immediate offspring of a topic;
1154 CHILDREN:
1155 The immediate offspring of a topic.
1156 SIBLINGS:
1157 Topics having the same parent and depth.
1159 Topic text constituents:
1161 HEADER: The first line of a topic, include the topic PREFIX and header
1162 text.
1163 PREFIX: The leading text of a topic which which distinguishes it from
1164 normal text. It has a strict form, which consists of a
1165 prefix-lead string, padding, and a bullet. The bullet may be
1166 followed by a number, indicating the ordinal number of the
1167 topic among its siblings, a space, and then the header text.
1169 The relative length of the PREFIX determines the nesting depth
1170 of the topic.
1171 PREFIX-LEAD:
1172 The string at the beginning of a topic prefix, normally a `.'.
1173 It can be customized by changing the setting of
1174 `outline-header-prefix' and then reinitializing outline-mode.
1176 By setting the prefix-lead to the comment-string of a
1177 programming language, you can embed outline-structuring in
1178 program code without interfering with the language processing
1179 of that code. See `outline-use-mode-specific-leader'
1180 docstring for more detail.
1181 PREFIX-PADDING:
1182 Spaces or asterisks which separate the prefix-lead and the
1183 bullet, according to the depth of the topic.
1184 BULLET: A character at the end of the topic prefix, it must be one of
1185 the characters listed on `outline-plain-bullets-string' or
1186 `outline-distinctive-bullets-string'. (See the documentation
1187 for these variables for more details.) The default choice of
1188 bullet when generating varies in a cycle with the depth of the
1189 topic.
1190 ENTRY: The text contained in a topic before any offspring.
1191 BODY: Same as ENTRY.
1194 EXPOSURE:
1195 The state of a topic which determines the on-screen visibility
1196 of its offspring and contained text.
1197 CONCEALED:
1198 Topics and entry text whose display is inhibited. Contiguous
1199 units of concealed text is represented by `...' ellipses.
1200 (Ref the `selective-display' var.)
1202 Concealed topics are effectively collapsed within an ancestor.
1203 CLOSED: A topic whose immediate offspring and body-text is concealed.
1204 OPEN: A topic that is not closed, though its offspring or body may be."
1205 ;;;_ . Code
1206 (interactive "P")
1208 (let* ((active (and (not (equal major-mode 'outline))
1209 (outline-mode-p)))
1210 ; Massage universal-arg `toggle' val:
1211 (toggle (and toggle
1212 (or (and (listp toggle)(car toggle))
1213 toggle)))
1214 ; Activation specifically demanded?
1215 (explicit-activation (or
1217 (and toggle
1218 (or (symbolp toggle)
1219 (and (natnump toggle)
1220 (not (zerop toggle)))))))
1221 ;; outline-mode already called once during this complex command?
1222 (same-complex-command (eq outline-v18/19-file-var-hack
1223 (car command-history)))
1224 do-layout
1227 ; See comments below re v19.18,.19 bug.
1228 (setq outline-v18/19-file-var-hack (car command-history))
1230 (cond
1232 ;; Provision for v19.18, 19.19 bug -
1233 ;; Emacs v 19.18, 19.19 file-var code invokes prop-line-designated
1234 ;; modes twice when file is visited. We have to avoid toggling mode
1235 ;; off on second invocation, so we detect it as best we can, and
1236 ;; skip everything.
1237 ((and same-complex-command ; Still in same complex command
1238 ; as last time outline-mode invoked.
1239 active ; Already activated.
1240 (not explicit-activation) ; Prop-line file-vars don't have args.
1241 (string-match "^19.1[89]" ; Bug only known to be in v19.18 and
1242 emacs-version)); 19.19.
1245 ;; Deactivation:
1246 ((and (not explicit-activation)
1247 (or active toggle))
1248 ; Activation not explicitly
1249 ; requested, and either in
1250 ; active state or *de*activation
1251 ; specifically requested:
1252 (setq outline-explicitly-deactivated t)
1253 (if (string-match "^18\." emacs-version)
1254 ; Revoke those keys that remain
1255 ; as we set them:
1256 (let ((curr-loc (current-local-map)))
1257 (mapcar (function
1258 (lambda (cell)
1259 (if (eq (lookup-key curr-loc (car cell))
1260 (car (cdr cell)))
1261 (define-key curr-loc (car cell)
1262 (assq (car cell) outline-prior-bindings)))))
1263 outline-added-bindings)
1264 (outline-resumptions 'outline-added-bindings)
1265 (outline-resumptions 'outline-prior-bindings)))
1267 (if outline-old-style-prefixes
1268 (progn
1269 (outline-resumptions 'outline-primary-bullet)
1270 (outline-resumptions 'outline-old-style-prefixes)))
1271 (outline-resumptions 'selective-display)
1272 (if (and (boundp 'before-change-functions) before-change-functions)
1273 (outline-resumptions 'before-change-functions))
1274 (setq local-write-file-hooks
1275 (delq 'outline-write-file-hook
1276 local-write-file-hooks))
1277 (outline-resumptions 'paragraph-start)
1278 (outline-resumptions 'paragraph-separate)
1279 (outline-resumptions (if (string-match "^18" emacs-version)
1280 'auto-fill-hook
1281 'auto-fill-function))
1282 (outline-resumptions 'outline-former-auto-filler)
1283 (setq outline-mode nil))
1285 ;; Activation:
1286 ((not active)
1287 (setq outline-explicitly-deactivated nil)
1288 (if outline-old-style-prefixes
1289 (progn ; Inhibit all the fancy formatting:
1290 (outline-resumptions 'outline-primary-bullet '("*"))
1291 (outline-resumptions 'outline-old-style-prefixes '(()))))
1293 (outline-infer-header-lead)
1294 (outline-infer-body-reindent)
1296 (set-outline-regexp)
1298 ; Produce map from current version
1299 ; of outline-keybindings-list:
1300 (if (boundp 'minor-mode-map-alist)
1302 (progn ; V19, and maybe lucid and
1303 ; epoch, minor-mode key bindings:
1304 (setq outline-mode-map
1305 (produce-outline-mode-map outline-keybindings-list))
1306 (produce-outline-mode-menubar-entries)
1307 (fset 'outline-mode-map outline-mode-map)
1308 ; Include on minor-mode-map-alist,
1309 ; if not already there:
1310 (if (not (member '(outline-mode . outline-mode-map)
1311 minor-mode-map-alist))
1312 (setq minor-mode-map-alist
1313 (cons '(outline-mode . outline-mode-map)
1314 minor-mode-map-alist))))
1316 ; V18 minor-mode key bindings:
1317 ; Stash record of added bindings
1318 ; for later revocation:
1319 (outline-resumptions 'outline-added-bindings
1320 (list outline-keybindings-list))
1321 (outline-resumptions 'outline-prior-bindings
1322 (list (current-local-map)))
1323 ; and add them:
1324 (use-local-map (produce-outline-mode-map outline-keybindings-list
1325 (current-local-map)))
1328 ; selective-display is the
1329 ; emacs conditional exposure
1330 ; mechanism:
1331 (outline-resumptions 'selective-display '(t))
1332 (if outline-inhibit-protection
1334 (outline-resumptions 'before-change-functions
1335 '(outline-before-change-protect)))
1336 (add-hook 'pre-command-hook 'outline-pre-command-business)
1337 (add-hook 'post-command-hook 'outline-post-command-business)
1338 ; Temporarily set by any outline
1339 ; functions that can be trusted to
1340 ; deal properly with concealed text.
1341 (add-hook 'local-write-file-hooks 'outline-write-file-hook)
1342 ; Custom auto-fill func, to support
1343 ; respect for topic headline,
1344 ; hanging-indents, etc:
1345 (let* ((fill-func-var (if (string-match "^18" emacs-version)
1346 'auto-fill-hook
1347 'auto-fill-function))
1348 (fill-func (symbol-value fill-func-var)))
1349 ;; Register prevailing fill func for use by outline-auto-fill:
1350 (outline-resumptions 'outline-former-auto-filler (list fill-func))
1351 ;; Register outline-auto-fill to be used if filling is active:
1352 (outline-resumptions fill-func-var '(outline-auto-fill)))
1353 ;; Paragraphs are broken by topic headlines.
1354 (make-local-variable 'paragraph-start)
1355 (outline-resumptions 'paragraph-start
1356 (list (concat paragraph-start "\\|^\\("
1357 outline-regexp "\\)")))
1358 (make-local-variable 'paragraph-separate)
1359 (outline-resumptions 'paragraph-separate
1360 (list (concat paragraph-separate "\\|^\\("
1361 outline-regexp "\\)")))
1363 (or (assq 'outline-mode minor-mode-alist)
1364 (setq minor-mode-alist
1365 (cons '(outline-mode " Outl") minor-mode-alist)))
1367 (outline-setup-menubar)
1369 (if outline-layout
1370 (setq do-layout t))
1372 (if (and outline-isearch-dynamic-expose
1373 (not (fboundp 'outline-real-isearch-abort)))
1374 (outline-enwrap-isearch))
1376 (run-hooks 'outline-mode-hook)
1377 (setq outline-mode t))
1379 ;; Reactivation:
1380 ((setq do-layout t)
1381 (outline-infer-body-reindent))
1382 ) ; cond
1384 (if (and do-layout
1385 outline-auto-activation
1386 (listp outline-layout)
1387 (and (not (eq outline-auto-activation 'activate))
1388 (if (eq outline-auto-activation 'ask)
1389 (if (y-or-n-p (format "Expose %s with layout '%s'? "
1390 (buffer-name)
1391 outline-layout))
1393 (message "Skipped %s layout." (buffer-name))
1394 nil)
1395 t)))
1396 (save-excursion
1397 (message "Adjusting '%s' exposure..." (buffer-name))
1398 (goto-char 0)
1399 (outline-this-or-next-heading)
1400 (condition-case err
1401 (progn
1402 (apply 'outline-expose-topic (list outline-layout))
1403 (message "Adjusting '%s' exposure... done." (buffer-name)))
1404 ;; Problem applying exposure - notify user, but don't
1405 ;; interrupt, eg, file visit:
1406 (error (message "%s" (car (cdr err)))
1407 (sit-for 1)))))
1408 outline-mode
1409 ) ; let*
1410 ) ; defun
1411 ;;;_ > outline-minor-mode
1412 ;;; XXX released verion doesn't do this?
1413 (defalias 'outline-minor-mode 'outline-mode)
1415 ;;;_ #3 Internal Position State-Tracking - "outline-recent-*" funcs
1416 ;;; All the basic outline functions that directly do string matches to
1417 ;;; evaluate heading prefix location set the variables
1418 ;;; `outline-recent-prefix-beginning' and `outline-recent-prefix-end'
1419 ;;; when successful. Functions starting with `outline-recent-' all
1420 ;;; use this state, providing the means to avoid redundant searches
1421 ;;; for just-established data. This optimization can provide
1422 ;;; significant speed improvement, but it must be employed carefully.
1423 ;;;_ = outline-recent-prefix-beginning
1424 (defvar outline-recent-prefix-beginning 0
1425 "Buffer point of the start of the last topic prefix encountered.")
1426 (make-variable-buffer-local 'outline-recent-prefix-beginning)
1427 ;;;_ = outline-recent-prefix-end
1428 (defvar outline-recent-prefix-end 0
1429 "Buffer point of the end of the last topic prefix encountered.")
1430 (make-variable-buffer-local 'outline-recent-prefix-end)
1431 ;;;_ = outline-recent-end-of-subtree
1432 (defvar outline-recent-end-of-subtree 0
1433 "Buffer point last returned by outline-end-of-current-subtree.")
1434 (make-variable-buffer-local 'outline-recent-end-of-subtree)
1435 ;;;_ > outline-prefix-data (beg end)
1436 (defmacro outline-prefix-data (beg end)
1437 "Register outline-prefix state data - BEGINNING and END of prefix.
1439 For reference by `outline-recent' funcs. Returns BEGINNING."
1440 `(setq outline-recent-prefix-end ,end
1441 outline-recent-prefix-beginning ,beg))
1442 ;;;_ > outline-recent-depth ()
1443 (defmacro outline-recent-depth ()
1444 "Return depth of last heading encountered by an outline maneuvering function.
1446 All outline functions which directly do string matches to assess
1447 headings set the variables outline-recent-prefix-beginning and
1448 outline-recent-prefix-end if successful. This function uses those settings
1449 to return the current depth."
1451 '(max 1 (- outline-recent-prefix-end
1452 outline-recent-prefix-beginning
1453 outline-header-subtraction)))
1454 ;;;_ > outline-recent-prefix ()
1455 (defmacro outline-recent-prefix ()
1456 "Like outline-recent-depth, but returns text of last encountered prefix.
1458 All outline functions which directly do string matches to assess
1459 headings set the variables outline-recent-prefix-beginning and
1460 outline-recent-prefix-end if successful. This function uses those settings
1461 to return the current depth."
1462 '(buffer-substring outline-recent-prefix-beginning
1463 outline-recent-prefix-end))
1464 ;;;_ > outline-recent-bullet ()
1465 (defmacro outline-recent-bullet ()
1466 "Like outline-recent-prefix, but returns bullet of last encountered prefix.
1468 All outline functions which directly do string matches to assess
1469 headings set the variables outline-recent-prefix-beginning and
1470 outline-recent-prefix-end if successful. This function uses those settings
1471 to return the current depth of the most recently matched topic."
1472 '(buffer-substring (1- outline-recent-prefix-end)
1473 outline-recent-prefix-end))
1475 ;;;_ #4 Navigation
1477 ;;;_ - Position Assessment
1478 ;;;_ : Location Predicates
1479 ;;;_ > outline-on-current-heading-p ()
1480 (defun outline-on-current-heading-p ()
1481 "Return non-nil if point is on current visible topics' header line.
1483 Actually, returns prefix beginning point."
1484 (save-excursion
1485 (beginning-of-line)
1486 (and (looking-at outline-regexp)
1487 (outline-prefix-data (match-beginning 0) (match-end 0)))))
1488 ;;;_ > outline-on-heading-p ()
1489 (defalias 'outline-on-heading-p 'outline-on-current-heading-p)
1490 ;;;_ > outline-e-o-prefix-p ()
1491 (defun outline-e-o-prefix-p ()
1492 "True if point is located where current topic prefix ends, heading begins."
1493 (and (save-excursion (beginning-of-line)
1494 (looking-at outline-regexp))
1495 (= (point)(save-excursion (outline-end-of-prefix)(point)))))
1496 ;;;_ > outline-hidden-p ()
1497 (defmacro outline-hidden-p ()
1498 "True if point is in hidden text."
1499 '(save-excursion
1500 (and (re-search-backward "[\n\r]" () t)
1501 (= ?\r (following-char)))))
1502 ;;;_ > outline-visible-p ()
1503 (defmacro outline-visible-p ()
1504 "True if point is not in hidden text."
1505 (interactive)
1506 '(not (outline-hidden-p)))
1507 ;;;_ : Location attributes
1508 ;;;_ > outline-depth ()
1509 (defsubst outline-depth ()
1510 "Like outline-current-depth, but respects hidden as well as visible topics."
1511 (save-excursion
1512 (if (outline-goto-prefix)
1513 (outline-recent-depth)
1514 (progn
1515 ;; Oops, no prefix, zero prefix data:
1516 (outline-prefix-data (point)(point))
1517 ;; ... and return 0:
1518 0))))
1519 ;;;_ > outline-current-depth ()
1520 (defmacro outline-current-depth ()
1521 "Return nesting depth of visible topic most immediately containing point."
1522 '(save-excursion
1523 (if (outline-back-to-current-heading)
1524 (max 1
1525 (- outline-recent-prefix-end
1526 outline-recent-prefix-beginning
1527 outline-header-subtraction))
1528 0)))
1529 ;;;_ > outline-get-current-prefix ()
1530 (defun outline-get-current-prefix ()
1531 "Topic prefix of the current topic."
1532 (save-excursion
1533 (if (outline-goto-prefix)
1534 (outline-recent-prefix))))
1535 ;;;_ > outline-get-bullet ()
1536 (defun outline-get-bullet ()
1537 "Return bullet of containing topic (visible or not)."
1538 (save-excursion
1539 (and (outline-goto-prefix)
1540 (outline-recent-bullet))))
1541 ;;;_ > outline-current-bullet ()
1542 (defun outline-current-bullet ()
1543 "Return bullet of current (visible) topic heading, or none if none found."
1544 (condition-case err
1545 (save-excursion
1546 (outline-back-to-current-heading)
1547 (buffer-substring (- outline-recent-prefix-end 1)
1548 outline-recent-prefix-end))
1549 ;; Quick and dirty provision, ostensibly for missing bullet:
1550 ('args-out-of-range nil))
1552 ;;;_ > outline-get-prefix-bullet (prefix)
1553 (defun outline-get-prefix-bullet (prefix)
1554 "Return the bullet of the header prefix string PREFIX."
1555 ;; Doesn't make sense if we're old-style prefixes, but this just
1556 ;; oughtn't be called then, so forget about it...
1557 (if (string-match outline-regexp prefix)
1558 (substring prefix (1- (match-end 0)) (match-end 0))))
1559 ;;;_ > outline-sibling-index (&optional depth)
1560 (defun outline-sibling-index (&optional depth)
1561 "Item number of this prospective topic among its siblings.
1563 If optional arg depth is greater than current depth, then we're
1564 opening a new level, and return 0.
1566 If less than this depth, ascend to that depth and count..."
1568 (save-excursion
1569 (cond ((and depth (<= depth 0) 0))
1570 ((or (not depth) (= depth (outline-depth)))
1571 (let ((index 1))
1572 (while (outline-previous-sibling (outline-recent-depth) nil)
1573 (setq index (1+ index)))
1574 index))
1575 ((< depth (outline-recent-depth))
1576 (outline-ascend-to-depth depth)
1577 (outline-sibling-index))
1578 (0))))
1579 ;;;_ > outline-topic-flat-index ()
1580 (defun outline-topic-flat-index ()
1581 "Return a list indicating point's numeric section.subsect.subsubsect...
1582 Outermost is first."
1583 (let* ((depth (outline-depth))
1584 (next-index (outline-sibling-index depth))
1585 (rev-sibls nil))
1586 (while (> next-index 0)
1587 (setq rev-sibls (cons next-index rev-sibls))
1588 (setq depth (1- depth))
1589 (setq next-index (outline-sibling-index depth)))
1590 rev-sibls)
1593 ;;;_ - Navigation macros
1594 ;;;_ > outline-next-heading ()
1595 (defsubst outline-next-heading ()
1596 "Move to the heading for the topic \(possibly invisible) before this one.
1598 Returns the location of the heading, or nil if none found."
1600 (if (and (bobp) (not (eobp)))
1601 (forward-char 1))
1603 (if (re-search-forward outline-line-boundary-regexp nil 0)
1604 (outline-prefix-data ; Got valid location state - set vars:
1605 (goto-char (or (match-beginning 2)
1606 outline-recent-prefix-beginning))
1607 (or (match-end 2) outline-recent-prefix-end))))
1608 ;;;_ : outline-this-or-next-heading
1609 (defun outline-this-or-next-heading ()
1610 "Position cursor on current or next heading."
1611 ;; A throwaway non-macro that is defined after outline-next-heading
1612 ;; and usable by outline-mode.
1613 (if (not (outline-goto-prefix)) (outline-next-heading)))
1614 ;;;_ > outline-previous-heading ()
1615 (defmacro outline-previous-heading ()
1616 "Move to the prior \(possibly invisible) heading line.
1618 Return the location of the beginning of the heading, or nil if not found."
1620 '(if (bobp)
1622 (outline-goto-prefix)
1624 ;; searches are unbounded and return nil if failed:
1625 (or (re-search-backward outline-line-boundary-regexp nil 0)
1626 (looking-at outline-bob-regexp))
1627 (progn ; Got valid location state - set vars:
1628 (outline-prefix-data
1629 (goto-char (or (match-beginning 2)
1630 outline-recent-prefix-beginning))
1631 (or (match-end 2) outline-recent-prefix-end))))))
1633 ;;;_ - Subtree Charting
1634 ;;;_ " These routines either produce or assess charts, which are
1635 ;;; nested lists of the locations of topics within a subtree.
1637 ;;; Use of charts enables efficient navigation of subtrees, by
1638 ;;; requiring only a single regexp-search based traversal, to scope
1639 ;;; out the subtopic locations. The chart then serves as the basis
1640 ;;; for assessment or adjustment of the subtree, without redundant
1641 ;;; traversal of the structure.
1643 ;;;_ > outline-chart-subtree (&optional levels orig-depth prev-depth)
1644 (defun outline-chart-subtree (&optional levels orig-depth prev-depth)
1645 "Produce a location \"chart\" of subtopics of the containing topic.
1647 Optional argument LEVELS specifies the depth \(relative to start
1648 depth) for the chart. Subsequent optional args are not for public
1649 use.
1651 Charts are used to capture outline structure, so that outline-altering
1652 routines need assess the structure only once, and then use the chart
1653 for their elaborate manipulations.
1655 Topics are entered in the chart so the last one is at the car.
1656 The entry for each topic consists of an integer indicating the point
1657 at the beginning of the topic. Charts for offspring consists of a
1658 list containing, recursively, the charts for the respective subtopics.
1659 The chart for a topics' offspring precedes the entry for the topic
1660 itself.
1662 The other function parameters are for internal recursion, and should
1663 not be specified by external callers. ORIG-DEPTH is depth of topic at
1664 starting point, and PREV-DEPTH is depth of prior topic."
1666 (let ((original (not orig-depth)) ; `orig-depth' set only in recursion.
1667 chart curr-depth)
1669 (if original ; Just starting?
1670 ; Register initial settings and
1671 ; position to first offspring:
1672 (progn (setq orig-depth (outline-depth))
1673 (or prev-depth (setq prev-depth (1+ orig-depth)))
1674 (outline-next-heading)))
1676 ;; Loop over the current levels' siblings. Besides being more
1677 ;; efficient than tail-recursing over a level, it avoids exceeding
1678 ;; the typically quite constrained emacs max-lisp-eval-depth.
1680 ;; Probably would speed things up to implement loop-based stack
1681 ;; operation rather than recursing for lower levels. Bah.
1683 (while (and (not (eobp))
1684 ; Still within original topic?
1685 (< orig-depth (setq curr-depth (outline-recent-depth)))
1686 (cond ((= prev-depth curr-depth)
1687 ;; Register this one and move on:
1688 (setq chart (cons (point) chart))
1689 (if (and levels (<= levels 1))
1690 ;; At depth limit - skip sublevels:
1691 (or (outline-next-sibling curr-depth)
1692 ;; or no more siblings - proceed to
1693 ;; next heading at lesser depth:
1694 (while (and (<= curr-depth
1695 (outline-recent-depth))
1696 (outline-next-heading))))
1697 (outline-next-heading)))
1699 ((and (< prev-depth curr-depth)
1700 (or (not levels)
1701 (> levels 0)))
1702 ;; Recurse on deeper level of curr topic:
1703 (setq chart
1704 (cons (outline-chart-subtree (and levels
1705 (1- levels))
1706 orig-depth
1707 curr-depth)
1708 chart))
1709 ;; ... then continue with this one.
1712 ;; ... else nil if we've ascended back to prev-depth.
1716 (if original ; We're at the last sibling on
1717 ; the original level. Position
1718 ; to the end of it:
1719 (progn (and (not (eobp)) (forward-char -1))
1720 (and (memq (preceding-char) '(?\n ?\r))
1721 (memq (aref (buffer-substring (max 1 (- (point) 3))
1722 (point))
1724 '(?\n ?\r))
1725 (forward-char -1))
1726 (setq outline-recent-end-of-subtree (point))))
1728 chart ; (nreverse chart) not necessary,
1729 ; and maybe not preferable.
1731 ;;;_ > outline-chart-siblings (&optional start end)
1732 (defun outline-chart-siblings (&optional start end)
1733 "Produce a list of locations of this and succeeding sibling topics.
1734 Effectively a top-level chart of siblings. See `outline-chart-subtree'
1735 for an explanation of charts."
1736 (save-excursion
1737 (if (outline-goto-prefix)
1738 (let ((chart (list (point))))
1739 (while (outline-next-sibling)
1740 (setq chart (cons (point) chart)))
1741 (if chart (setq chart (nreverse chart)))))))
1742 ;;;_ > outline-chart-to-reveal (chart depth)
1743 (defun outline-chart-to-reveal (chart depth)
1745 "Return a flat list of hidden points in subtree CHART, up to DEPTH.
1747 Note that point can be left at any of the points on chart, or at the
1748 start point."
1750 (let (result here)
1751 (while (and (or (eq depth t) (> depth 0))
1752 chart)
1753 (setq here (car chart))
1754 (if (listp here)
1755 (let ((further (outline-chart-to-reveal here (or (eq depth t)
1756 (1- depth)))))
1757 ;; We're on the start of a subtree - recurse with it, if there's
1758 ;; more depth to go:
1759 (if further (setq result (append further result)))
1760 (setq chart (cdr chart)))
1761 (goto-char here)
1762 (if (= (preceding-char) ?\r)
1763 (setq result (cons here result)))
1764 (setq chart (cdr chart))))
1765 result))
1766 ;;;_ X outline-chart-spec (chart spec &optional exposing)
1767 (defun outline-chart-spec (chart spec &optional exposing)
1768 "Not yet \(if ever) implemented.
1770 Produce exposure directives given topic/subtree CHART and an exposure SPEC.
1772 Exposure spec indicates the locations to be exposed and the prescribed
1773 exposure status. Optional arg EXPOSING is an integer, with 0
1774 indicating pending concealment, anything higher indicating depth to
1775 which subtopic headers should be exposed, and negative numbers
1776 indicating (negative of) the depth to which subtopic headers and
1777 bodies should be exposed.
1779 The produced list can have two types of entries. Bare numbers
1780 indicate points in the buffer where topic headers that should be
1781 exposed reside.
1783 - bare negative numbers indicates that the topic starting at the
1784 point which is the negative of the number should be opened,
1785 including their entries.
1786 - bare positive values indicate that this topic header should be
1787 opened.
1788 - Lists signify the beginning and end points of regions that should
1789 be flagged, and the flag to employ. (For concealment: `\(\?r\)', and
1790 exposure:"
1791 (while spec
1792 (cond ((listp spec)
1795 (setq spec (cdr spec)))
1798 ;;;_ - Within Topic
1799 ;;;_ > outline-goto-prefix ()
1800 (defun outline-goto-prefix ()
1801 "Put point at beginning of immediately containing outline topic.
1803 Goes to most immediate subsequent topic if none immediately containing.
1805 Not sensitive to topic visibility.
1807 Returns a the point at the beginning of the prefix, or nil if none."
1809 (let (done)
1810 (while (and (not done)
1811 (re-search-backward "[\n\r]" nil 1))
1812 (forward-char 1)
1813 (if (looking-at outline-regexp)
1814 (setq done (outline-prefix-data (match-beginning 0)
1815 (match-end 0)))
1816 (forward-char -1)))
1817 (if (bobp)
1818 (cond ((looking-at outline-regexp)
1819 (outline-prefix-data (match-beginning 0)(match-end 0)))
1820 ((outline-next-heading))
1821 (done))
1822 done)))
1823 ;;;_ > outline-end-of-prefix ()
1824 (defun outline-end-of-prefix (&optional ignore-decorations)
1825 "Position cursor at beginning of header text.
1827 If optional IGNORE-DECORATIONS is non-nil, put just after bullet,
1828 otherwise skip white space between bullet and ensuing text."
1830 (if (not (outline-goto-prefix))
1832 (let ((match-data (match-data)))
1833 (goto-char (match-end 0))
1834 (if ignore-decorations
1836 (while (looking-at "[0-9]") (forward-char 1))
1837 (if (and (not (eolp)) (looking-at "\\s-")) (forward-char 1)))
1838 (store-match-data match-data))
1839 ;; Reestablish where we are:
1840 (outline-current-depth)))
1841 ;;;_ > outline-current-bullet-pos ()
1842 (defun outline-current-bullet-pos ()
1843 "Return position of current \(visible) topic's bullet."
1845 (if (not (outline-current-depth))
1847 (1- (match-end 0))))
1848 ;;;_ > outline-back-to-current-heading ()
1849 (defun outline-back-to-current-heading ()
1850 "Move to heading line of current topic, or beginning if already on the line."
1852 (beginning-of-line)
1853 (prog1 (or (outline-on-current-heading-p)
1854 (and (re-search-backward (concat "^\\(" outline-regexp "\\)")
1856 'move)
1857 (outline-prefix-data (match-beginning 1)(match-end 1))))
1858 (if (interactive-p) (outline-end-of-prefix))))
1859 ;;;_ > outline-back-to-heading ()
1860 (defalias 'outline-back-to-heading 'outline-back-to-current-heading)
1861 ;;;_ > outline-pre-next-preface ()
1862 (defun outline-pre-next-preface ()
1863 "Skip forward to just before the next heading line.
1865 Returns that character position."
1867 (if (re-search-forward outline-line-boundary-regexp nil 'move)
1868 (prog1 (goto-char (match-beginning 0))
1869 (outline-prefix-data (match-beginning 2)(match-end 2)))))
1870 ;;;_ > outline-end-of-current-subtree ()
1871 (defun outline-end-of-current-subtree ()
1872 "Put point at the end of the last leaf in the currently visible topic."
1873 (interactive)
1874 (outline-back-to-current-heading)
1875 (let ((level (outline-recent-depth)))
1876 (outline-next-heading)
1877 (while (and (not (eobp))
1878 (> (outline-recent-depth) level))
1879 (outline-next-heading))
1880 (and (not (eobp)) (forward-char -1))
1881 (and (memq (preceding-char) '(?\n ?\r))
1882 (memq (aref (buffer-substring (max 1 (- (point) 3)) (point)) 1)
1883 '(?\n ?\r))
1884 (forward-char -1))
1885 (setq outline-recent-end-of-subtree (point))))
1886 ;;;_ > outline-beginning-of-current-entry ()
1887 (defun outline-beginning-of-current-entry ()
1888 "When not already there, position point at beginning of current topic's body.
1890 If already there, move cursor to bullet for hot-spot operation.
1891 \(See outline-mode doc string for details on hot-spot operation.)"
1892 (interactive)
1893 (let ((start-point (point)))
1894 (outline-end-of-prefix)
1895 (if (and (interactive-p)
1896 (= (point) start-point))
1897 (goto-char (outline-current-bullet-pos)))))
1898 ;;;_ > outline-end-of-current-entry ()
1899 (defun outline-end-of-current-entry ()
1900 "Position the point at the end of the current topics' entry."
1901 (interactive)
1902 (outline-show-entry)
1903 (prog1 (outline-pre-next-preface)
1904 (if (and (not (bobp))(looking-at "^$"))
1905 (forward-char -1))))
1906 ;;;_ > outline-end-of-current-heading ()
1907 (defun outline-end-of-current-heading ()
1908 (interactive)
1909 (outline-beginning-of-current-entry)
1910 (forward-line -1)
1911 (end-of-line))
1912 (defalias 'outline-end-of-heading 'outline-end-of-current-heading)
1914 ;;;_ - Depth-wise
1915 ;;;_ > outline-ascend-to-depth (depth)
1916 (defun outline-ascend-to-depth (depth)
1917 "Ascend to depth DEPTH, returning depth if successful, nil if not."
1918 (if (and (> depth 0)(<= depth (outline-depth)))
1919 (let ((last-good (point)))
1920 (while (and (< depth (outline-depth))
1921 (setq last-good (point))
1922 (outline-beginning-of-level)
1923 (outline-previous-heading)))
1924 (if (= (outline-recent-depth) depth)
1925 (progn (goto-char outline-recent-prefix-beginning)
1926 depth)
1927 (goto-char last-good)
1928 nil))
1929 (if (interactive-p) (outline-end-of-prefix))))
1930 ;;;_ > outline-ascend ()
1931 (defun outline-ascend ()
1932 "Ascend one level, returning t if successful, nil if not."
1933 (prog1
1934 (if (outline-beginning-of-level)
1935 (outline-previous-heading))
1936 (if (interactive-p) (outline-end-of-prefix))))
1937 ;;;_ > outline-descend-to-depth (depth)
1938 (defun outline-descend-to-depth (depth)
1939 "Descend to depth DEPTH within current topic.
1941 Returning depth if successful, nil if not."
1942 (let ((start-point (point))
1943 (start-depth (outline-depth)))
1944 (while
1945 (and (> (outline-depth) 0)
1946 (not (= depth (outline-recent-depth))) ; ... not there yet
1947 (outline-next-heading) ; ... go further
1948 (< start-depth (outline-recent-depth)))) ; ... still in topic
1949 (if (and (> (outline-depth) 0)
1950 (= (outline-recent-depth) depth))
1951 depth
1952 (goto-char start-point)
1953 nil))
1955 ;;;_ > outline-up-current-level (arg &optional dont-complain)
1956 (defun outline-up-current-level (arg &optional dont-complain)
1957 "Move out ARG levels from current visible topic.
1959 Positions on heading line of containing topic. Error if unable to
1960 ascend that far, or nil if unable to ascend but optional arg
1961 DONT-COMPLAIN is non-nil."
1962 (interactive "p")
1963 (outline-back-to-current-heading)
1964 (let ((present-level (outline-recent-depth))
1965 (last-good (point))
1966 failed
1967 return)
1968 ;; Loop for iterating arg:
1969 (while (and (> (outline-recent-depth) 1)
1970 (> arg 0)
1971 (not (bobp))
1972 (not failed))
1973 (setq last-good (point))
1974 ;; Loop for going back over current or greater depth:
1975 (while (and (not (< (outline-recent-depth) present-level))
1976 (or (outline-previous-visible-heading 1)
1977 (not (setq failed present-level)))))
1978 (setq present-level (outline-current-depth))
1979 (setq arg (- arg 1)))
1980 (if (or failed
1981 (> arg 0))
1982 (progn (goto-char last-good)
1983 (if (interactive-p) (outline-end-of-prefix))
1984 (if (not dont-complain)
1985 (error "Can't ascend past outermost level.")
1986 (if (interactive-p) (outline-end-of-prefix))
1987 nil))
1988 (if (interactive-p) (outline-end-of-prefix))
1989 outline-recent-prefix-beginning)))
1991 ;;;_ - Linear
1992 ;;;_ > outline-next-sibling (&optional depth backward)
1993 (defun outline-next-sibling (&optional depth backward)
1994 "Like outline-forward-current-level, but respects invisible topics.
1996 Traverse at optional DEPTH, or current depth if none specified.
1998 Go backward if optional arg BACKWARD is non-nil.
2000 Return depth if successful, nil otherwise."
2002 (if (and backward (bobp))
2004 (let ((start-depth (or depth (outline-depth)))
2005 (start-point (point))
2006 last-depth)
2007 (while (and (not (if backward (bobp) (eobp)))
2008 (if backward (outline-previous-heading)
2009 (outline-next-heading))
2010 (> (setq last-depth (outline-recent-depth)) start-depth)))
2011 (if (and (not (eobp))
2012 (and (> (or last-depth (outline-depth)) 0)
2013 (= (outline-recent-depth) start-depth)))
2014 outline-recent-prefix-beginning
2015 (goto-char start-point)
2016 (if depth (outline-depth) start-depth)
2017 nil))))
2018 ;;;_ > outline-previous-sibling (&optional depth backward)
2019 (defun outline-previous-sibling (&optional depth backward)
2020 "Like outline-forward-current-level,but backwards & respect invisible topics.
2022 Optional DEPTH specifies depth to traverse, default current depth.
2024 Optional BACKWARD reverses direction.
2026 Return depth if successful, nil otherwise."
2027 (outline-next-sibling depth (not backward))
2029 ;;;_ > outline-snug-back ()
2030 (defun outline-snug-back ()
2031 "Position cursor at end of previous topic
2033 Presumes point is at the start of a topic prefix."
2034 (if (or (bobp) (eobp))
2036 (forward-char -1))
2037 (if (or (bobp) (not (memq (preceding-char) '(?\n ?\r))))
2039 (forward-char -1)
2040 (if (or (bobp) (not (memq (preceding-char) '(?\n ?\r))))
2041 (forward-char -1)))
2042 (point))
2043 ;;;_ > outline-beginning-of-level ()
2044 (defun outline-beginning-of-level ()
2045 "Go back to the first sibling at this level, visible or not."
2046 (outline-end-of-level 'backward))
2047 ;;;_ > outline-end-of-level (&optional backward)
2048 (defun outline-end-of-level (&optional backward)
2049 "Go to the last sibling at this level, visible or not."
2051 (let ((depth (outline-depth)))
2052 (while (outline-previous-sibling depth nil))
2053 (prog1 (outline-recent-depth)
2054 (if (interactive-p) (outline-end-of-prefix)))))
2055 ;;;_ > outline-next-visible-heading (arg)
2056 (defun outline-next-visible-heading (arg)
2057 "Move to the next ARG'th visible heading line, backward if arg is negative.
2059 Move as far as possible in indicated direction \(beginning or end of
2060 buffer) if headings are exhausted."
2062 (interactive "p")
2063 (let* ((backward (if (< arg 0) (setq arg (* -1 arg))))
2064 (step (if backward -1 1))
2065 (start-point (point))
2066 prev got)
2068 (while (> arg 0) ; limit condition
2069 (while (and (not (if backward (bobp)(eobp))) ; boundary condition
2070 ;; Move, skipping over all those concealed lines:
2071 (< -1 (forward-line step))
2072 (not (setq got (looking-at outline-regexp)))))
2073 ;; Register this got, it may be the last:
2074 (if got (setq prev got))
2075 (setq arg (1- arg)))
2076 (cond (got ; Last move was to a prefix:
2077 (outline-prefix-data (match-beginning 0) (match-end 0))
2078 (outline-end-of-prefix))
2079 (prev ; Last move wasn't, but prev was:
2080 (outline-prefix-data (match-beginning 0) (match-end 0)))
2081 ((not backward) (end-of-line) nil))))
2082 ;;;_ > outline-previous-visible-heading (arg)
2083 (defun outline-previous-visible-heading (arg)
2084 "Move to the previous heading line.
2086 With argument, repeats or can move forward if negative.
2087 A heading line is one that starts with a `*' (or that outline-regexp
2088 matches)."
2089 (interactive "p")
2090 (outline-next-visible-heading (- arg)))
2091 ;;;_ > outline-forward-current-level (arg)
2092 (defun outline-forward-current-level (arg)
2093 "Position point at the next heading of the same level.
2095 Takes optional repeat-count, goes backward if count is negative.
2097 Returns resulting position, else nil if none found."
2098 (interactive "p")
2099 (let ((start-depth (outline-current-depth))
2100 (start-point (point))
2101 (start-arg arg)
2102 (backward (> 0 arg))
2103 last-depth
2104 (last-good (point))
2105 at-boundary)
2106 (if (= 0 start-depth)
2107 (error "No siblings, not in a topic..."))
2108 (if backward (setq arg (* -1 arg)))
2109 (while (not (or (zerop arg)
2110 at-boundary))
2111 (while (and (not (if backward (bobp) (eobp)))
2112 (if backward (outline-previous-visible-heading 1)
2113 (outline-next-visible-heading 1))
2114 (> (setq last-depth (outline-recent-depth)) start-depth)))
2115 (if (and last-depth (= last-depth start-depth)
2116 (not (if backward (bobp) (eobp))))
2117 (setq last-good (point)
2118 arg (1- arg))
2119 (setq at-boundary t)))
2120 (if (and (not (eobp))
2121 (= arg 0)
2122 (and (> (or last-depth (outline-depth)) 0)
2123 (= (outline-recent-depth) start-depth)))
2124 outline-recent-prefix-beginning
2125 (goto-char last-good)
2126 (if (not (interactive-p))
2128 (outline-end-of-prefix)
2129 (error "Hit %s level %d topic, traversed %d of %d requested."
2130 (if backward "first" "last")
2131 (outline-recent-depth)
2132 (- (abs start-arg) arg)
2133 (abs start-arg))))))
2134 ;;;_ > outline-backward-current-level (arg)
2135 (defun outline-backward-current-level (arg)
2136 "Inverse of `outline-forward-current-level'."
2137 (interactive "p")
2138 (if (interactive-p)
2139 (let ((current-prefix-arg (* -1 arg)))
2140 (call-interactively 'outline-forward-current-level))
2141 (outline-forward-current-level (* -1 arg))))
2143 ;;;_ #5 Alteration
2145 ;;;_ - Fundamental
2146 ;;;_ > outline-before-change-protect (beg end)
2147 (defun outline-before-change-protect (beg end)
2148 "Outline before-change hook, regulates changes to concealed text.
2150 Reveal concealed text that would be changed by current command, and
2151 offer user choice to commit or forego the change. Unchanged text is
2152 reconcealed. User has option to have changed text reconcealed.
2154 Undo commands are specially treated - the user is not prompted for
2155 choice, the undoes are always committed (based on presumption that the
2156 things being undone were already subject to this regulation routine),
2157 and undoes always leave the changed stuff exposed.
2159 Changes to concealed regions are ignored while file is being written.
2160 \(This is for the sake of functions that do change the file during
2161 writes, like crypt and zip modes.)
2163 Locally bound in outline buffers to `before-change-functions', which
2164 in emacs 19 is run before any change to the buffer.
2166 Any functions which set [`this-command' to `undo', or which set]
2167 `outline-override-protect' non-nil (as does, eg, outline-flag-chars)
2168 are exempt from this restriction."
2169 (if (and (outline-mode-p)
2170 ; outline-override-protect
2171 ; set by functions that know what
2172 ; they're doing, eg outline internals:
2173 (not outline-override-protect)
2174 (not outline-during-write-cue)
2175 (save-match-data ; Preserve operation position state.
2176 ; Both beginning and end chars must
2177 ; be exposed:
2178 (save-excursion (if (memq this-command '(newline open-line))
2179 ;; Compensate for stupid emacs {new,
2180 ;; open-}line display optimization:
2181 (setq beg (1+ beg)
2182 end (1+ end)))
2183 (goto-char beg)
2184 (or (outline-hidden-p)
2185 (and (not (= beg end))
2186 (goto-char end)
2187 (outline-hidden-p))))))
2188 (save-match-data
2189 (if (equal this-command 'undo)
2190 ;; Allow undo without inhibition.
2191 ;; - Undoing new and open-line hits stupid emacs redisplay
2192 ;; optimization (em 19 cmds.c, ~ line 200).
2193 ;; - Presumably, undoing what was properly protected when
2194 ;; done.
2195 ;; - Undo may be users' only recourse in protection faults.
2196 ;; So, expose what getting changed:
2197 (progn (message "Undo! - exposing concealed target...")
2198 (if (outline-hidden-p)
2199 (outline-show-children))
2200 (message "Undo!"))
2201 (let (response
2202 (rehide-completely (save-excursion (outline-goto-prefix)
2203 (outline-hidden-p)))
2204 rehide-place)
2206 (save-excursion
2207 (if (condition-case err
2208 ;; Condition case to catch keyboard quits during reads.
2209 (progn
2210 ; Give them a peek where
2211 (save-excursion
2212 (if (eolp) (setq rehide-place
2213 (outline-goto-prefix)))
2214 (outline-show-entry))
2215 ; Present the message, but...
2216 ; leave the cursor at the location
2217 ; until they respond:
2218 ; Then interpret the response:
2219 (while
2220 (progn
2221 (message (concat "Change inside concealed"
2222 " region - do it? "
2223 "(n or 'y'/'r'eclose)"))
2224 (setq response (read-char))
2225 (not
2226 (cond ((memq response '(?r ?R))
2227 (setq response 'reclose))
2228 ((memq response '(?y ?Y ? ))
2229 (setq response t))
2230 ((memq response '(?n ?N 127))
2231 (setq response nil)
2233 ((eq response ??)
2234 (message
2235 "`r' means `yes, then reclose'")
2236 nil)
2237 (t (message "Please answer y, n, or r")
2238 (sit-for 1)
2239 nil)))))
2240 response)
2241 ('quit nil))
2242 ; Continue:
2243 (if (eq response 'reclose)
2244 (save-excursion
2245 (if rehide-place (goto-char rehide-place))
2246 (if rehide-completely
2247 (outline-hide-current-entry-completely)
2248 (outline-hide-current-entry)))
2249 (if (outline-ascend-to-depth (1- (outline-recent-depth)))
2250 (outline-show-children)
2251 (outline-show-to-offshoot)))
2252 ; Prevent:
2253 (if rehide-completely
2254 (save-excursion
2255 (if rehide-place (goto-char rehide-place))
2256 (outline-hide-current-entry-completely))
2257 (outline-hide-current-entry))
2258 (error (concat
2259 "Change within concealed region prevented.")))))))
2260 ) ; if
2261 ) ; defun
2262 ;;;_ = outline-post-goto-bullet
2263 (defvar outline-post-goto-bullet nil
2264 "Outline internal var, for `outline-pre-command-business' hot-spot operation.
2266 When set, tells post-processing to reposition on topic bullet, and
2267 then unset it. Set by outline-pre-command-business when implementing
2268 hot-spot operation, where literal characters typed over a topic bullet
2269 are mapped to the command of the corresponding control-key on the
2270 outline-mode-map.")
2271 (make-variable-buffer-local 'outline-post-goto-bullet)
2272 ;;;_ > outline-post-command-business ()
2273 (defun outline-post-command-business ()
2274 "Outline post-command-hook function.
2276 - Null outline-override-protect, so it's not left open.
2278 - Implement (and clear) outline-post-goto-bullet, for hot-spot
2279 outline commands.
2281 - Massages buffer-undo-list so successive, standard character self-inserts are
2282 aggregated. This kludge compensates for lack of undo bunching when
2283 before-change-functions is used."
2285 ; Apply any external change func:
2286 (if (not (outline-mode-p)) ; In outline-mode.
2288 (setq outline-override-protect nil)
2289 (if outline-isearch-dynamic-expose
2290 (outline-isearch-rectification))
2291 (if outline-during-write-cue
2292 ;; Was used by outline-before-change-protect, done with it now:
2293 (setq outline-during-write-cue nil))
2294 ;; Undo bunching business:
2295 (if (and (listp buffer-undo-list) ; Undo history being kept.
2296 (equal this-command 'self-insert-command)
2297 (equal last-command 'self-insert-command))
2298 (let* ((prev-stuff (cdr buffer-undo-list))
2299 (before-prev-stuff (cdr (cdr prev-stuff)))
2300 cur-cell cur-from cur-to
2301 prev-cell prev-from prev-to)
2302 (if (and before-prev-stuff ; Goes back far enough to bother,
2303 (not (car prev-stuff)) ; and break before current,
2304 (not (car before-prev-stuff)) ; !and break before prev!
2305 (setq prev-cell (car (cdr prev-stuff))) ; contents now,
2306 (setq cur-cell (car buffer-undo-list)) ; contents prev.
2308 ;; cur contents denote a single char insertion:
2309 (numberp (setq cur-from (car cur-cell)))
2310 (numberp (setq cur-to (cdr cur-cell)))
2311 (= 1 (- cur-to cur-from))
2313 ;; prev contents denote fewer than aggregate-limit
2314 ;; insertions:
2315 (numberp (setq prev-from (car prev-cell)))
2316 (numberp (setq prev-to (cdr prev-cell)))
2317 ; Below threshold:
2318 (> outline-undo-aggregation (- prev-to prev-from)))
2319 (setq buffer-undo-list
2320 (cons (cons prev-from cur-to)
2321 (cdr (cdr (cdr buffer-undo-list))))))))
2322 ;; Implement -post-goto-bullet, if set: (must be after undo business)
2323 (if (and outline-post-goto-bullet
2324 (outline-current-bullet-pos))
2325 (progn (goto-char (outline-current-bullet-pos))
2326 (setq outline-post-goto-bullet nil)))
2328 ;;;_ > outline-pre-command-business ()
2329 (defun outline-pre-command-business ()
2330 "Outline pre-command-hook function for outline buffers.
2331 Implements special behavior when cursor is on bullet char.
2333 Self-insert characters are reinterpreted control-character references
2334 into the outline-mode-map. The outline-mode post-command hook will
2335 position a cursor that has moved as a result of such reinterpretation,
2336 on the destination topic's bullet, when the cursor wound up in the
2338 The upshot is that you can get easy, single (ie, unmodified) key
2339 outline maneuvering operations by positioning the cursor on the bullet
2340 char. You stay in this mode until you use some regular
2341 cursor-positioning command to relocate the cursor off of a bullet
2342 char."
2344 (if (not (outline-mode-p))
2345 ;; Shouldn't be invoked if not in allout outline-mode, but just in case:
2347 ;; Register isearch status:
2348 (if (and (boundp 'isearch-mode) isearch-mode)
2349 (setq outline-pre-was-isearching t)
2350 (setq outline-pre-was-isearching nil))
2351 ;; Hot-spot navigation provisions:
2352 (if (and (eq this-command 'self-insert-command)
2353 (eq (point)(outline-current-bullet-pos)))
2354 (let* ((this-key-num (cond
2355 ((numberp last-command-char)
2356 last-command-char)
2357 ;; XXX Only xemacs has characterp.
2358 ((and (fboundp 'characterp)
2359 (characterp last-command-char))
2360 (char-to-int last-command-char))
2361 (t 0)))
2362 mapped-binding)
2363 (if (zerop this-key-num)
2365 ; Map upper-register literals
2366 ; to lower register:
2367 (if (<= 96 this-key-num)
2368 (setq this-key-num (- this-key-num 32)))
2369 ; Check if we have a literal:
2370 (if (and (<= 64 this-key-num)
2371 (>= 96 this-key-num))
2372 (setq mapped-binding
2373 (lookup-key 'outline-mode-map
2374 (concat outline-command-prefix
2375 (char-to-string (- this-key-num
2376 64))))))
2377 (if mapped-binding
2378 (setq outline-post-goto-bullet t
2379 this-command mapped-binding)))))))
2380 ;;;_ > outline-find-file-hook ()
2381 (defun outline-find-file-hook ()
2382 "Activate outline-mode when `outline-auto-activation' & `outline-layout' are non-nil.
2384 See `outline-init' for setup instructions."
2385 (if (and outline-auto-activation
2386 (not (outline-mode-p))
2387 outline-layout)
2388 (outline-mode t)))
2389 ;;;_ > outline-isearch-rectification
2390 (defun outline-isearch-rectification ()
2391 "Rectify outline exposure before, during, or after isearch.
2393 Called as part of outline-post-command-business."
2395 (let ((isearching (and (boundp 'isearch-mode) isearch-mode)))
2396 (cond ((and isearching (not outline-pre-was-isearching))
2397 (outline-isearch-expose 'start))
2398 ((and isearching outline-pre-was-isearching)
2399 (outline-isearch-expose 'continue))
2400 ((and (not isearching) outline-pre-was-isearching)
2401 (outline-isearch-expose 'final))
2402 ;; Not and wasn't isearching:
2403 (t (setq outline-isearch-prior-pos nil)
2404 (setq outline-isearch-did-quit nil)))))
2405 ;;;_ = outline-isearch-was-font-lock
2406 (defvar outline-isearch-was-font-lock
2407 (and (boundp 'font-lock-mode) font-lock-mode))
2408 ;;;_ > outline-isearch-expose (mode)
2409 (defun outline-isearch-expose (mode)
2410 "Mode is either 'clear, 'start, 'continue, or 'final."
2411 ;; outline-isearch-prior-pos encodes exposure status of prior pos:
2412 ;; (pos was-vis header-pos end-pos)
2413 ;; pos - point of concern
2414 ;; was-vis - t, else 'topic if entire topic was exposed, 'entry otherwise
2415 ;; Do reclosure or prior pos, as necessary:
2416 (if (eq mode 'start)
2417 (setq outline-isearch-was-font-lock (and (boundp 'font-lock-mode)
2418 font-lock-mode)
2419 font-lock-mode nil)
2420 (if (eq mode 'final)
2421 (setq font-lock-mode outline-isearch-was-font-lock))
2422 (if (and outline-isearch-prior-pos
2423 (listp outline-isearch-prior-pos))
2424 ;; Conceal prior peek:
2425 (outline-flag-region (car (cdr outline-isearch-prior-pos))
2426 (car (cdr (cdr outline-isearch-prior-pos)))
2427 ?\r)))
2428 (if (outline-visible-p)
2429 (setq outline-isearch-prior-pos nil)
2430 (if (not (eq mode 'final))
2431 (setq outline-isearch-prior-pos (cons (point) (outline-show-entry)))
2432 (if outline-isearch-did-quit
2434 (setq outline-isearch-prior-pos nil)
2435 (outline-show-children))))
2436 (setq outline-isearch-did-quit nil))
2437 ;;;_ > outline-enwrap-isearch ()
2438 (defun outline-enwrap-isearch ()
2439 "Impose outline-mode isearch-abort wrapper for dynamic exposure in isearch.
2441 The function checks to ensure that the rebinding is done only once."
2443 (add-hook 'isearch-mode-end-hook 'outline-isearch-rectification)
2444 (if (fboundp 'outline-real-isearch-abort)
2447 ; Ensure load of isearch-mode:
2448 (if (or (and (fboundp 'isearch-mode)
2449 (fboundp 'isearch-abort))
2450 (condition-case error
2451 (load-library "isearch-mode")
2452 ('file-error (message
2453 "Skipping isearch-mode provisions - %s '%s'"
2454 (car (cdr error))
2455 (car (cdr (cdr error))))
2456 (sit-for 1)
2457 ;; Inhibit subsequent tries and return nil:
2458 (setq outline-isearch-dynamic-expose nil))))
2459 ;; Isearch-mode loaded, encapsulate specific entry points for
2460 ;; outline dynamic-exposure business:
2461 (progn
2462 ;; stash crucial isearch-mode funcs under known, private
2463 ;; names, then register wrapper functions under the old
2464 ;; names, in their stead:
2465 (fset 'outline-real-isearch-abort (symbol-function 'isearch-abort))
2466 (fset 'isearch-abort 'outline-isearch-abort)))))
2467 ;;;_ > outline-isearch-abort ()
2468 (defun outline-isearch-abort ()
2469 "Wrapper for outline-real-isearch-abort \(which see), to register
2470 actual quits."
2471 (interactive)
2472 (setq outline-isearch-did-quit nil)
2473 (condition-case what
2474 (outline-real-isearch-abort)
2475 ('quit (setq outline-isearch-did-quit t)
2476 (signal 'quit nil))))
2478 ;;; Prevent unnecessary font-lock while isearching!
2479 (defvar isearch-was-font-locking nil)
2480 (defun isearch-inhibit-font-lock ()
2481 "Inhibit font-lock while isearching - for use on isearch-mode-hook."
2482 (if (and (outline-mode-p) (boundp 'font-lock-mode) font-lock-mode)
2483 (setq isearch-was-font-locking t
2484 font-lock-mode nil)))
2485 (add-hook 'isearch-mode-hook 'isearch-inhibit-font-lock)
2486 (defun isearch-reenable-font-lock ()
2487 "Reenable font-lock after isearching - for use on isearch-mode-end-hook."
2488 (if (and (boundp 'font-lock-mode) font-lock-mode)
2489 (if (and (outline-mode-p) isearch-was-font-locking)
2490 (setq isearch-was-font-locking nil
2491 font-lock-mode t))))
2492 (add-hook 'isearch-mode-end-hook 'isearch-reenable-font-lock)
2494 ;;;_ - Topic Format Assessment
2495 ;;;_ > outline-solicit-alternate-bullet (depth &optional current-bullet)
2496 (defun outline-solicit-alternate-bullet (depth &optional current-bullet)
2498 "Prompt for and return a bullet char as an alternative to the current one.
2500 Offer one suitable for current depth DEPTH as default."
2502 (let* ((default-bullet (or (and (stringp current-bullet) current-bullet)
2503 (outline-bullet-for-depth depth)))
2504 (sans-escapes (regexp-sans-escapes outline-bullets-string))
2505 choice)
2506 (save-excursion
2507 (goto-char (outline-current-bullet-pos))
2508 (setq choice (solicit-char-in-string
2509 (format "Select bullet: %s ('%s' default): "
2510 sans-escapes
2511 default-bullet)
2512 sans-escapes
2513 t)))
2514 (message "")
2515 (if (string= choice "") default-bullet choice))
2517 ;;;_ > outline-distinctive-bullet (bullet)
2518 (defun outline-distinctive-bullet (bullet)
2519 "True if bullet is one of those on outline-distinctive-bullets-string."
2520 (string-match (regexp-quote bullet) outline-distinctive-bullets-string))
2521 ;;;_ > outline-numbered-type-prefix (&optional prefix)
2522 (defun outline-numbered-type-prefix (&optional prefix)
2523 "True if current header prefix bullet is numbered bullet."
2524 (and outline-numbered-bullet
2525 (string= outline-numbered-bullet
2526 (if prefix
2527 (outline-get-prefix-bullet prefix)
2528 (outline-get-bullet)))))
2529 ;;;_ > outline-bullet-for-depth (&optional depth)
2530 (defun outline-bullet-for-depth (&optional depth)
2531 "Return outline topic bullet suited to optional DEPTH, or current depth."
2532 ;; Find bullet in plain-bullets-string modulo DEPTH.
2533 (if outline-stylish-prefixes
2534 (char-to-string (aref outline-plain-bullets-string
2535 (% (max 0 (- depth 2))
2536 outline-plain-bullets-string-len)))
2537 outline-primary-bullet)
2540 ;;;_ - Topic Production
2541 ;;;_ > outline-make-topic-prefix (&optional prior-bullet
2542 (defun outline-make-topic-prefix (&optional prior-bullet
2544 depth
2545 solicit
2546 number-control
2547 index)
2548 ;; Depth null means use current depth, non-null means we're either
2549 ;; opening a new topic after current topic, lower or higher, or we're
2550 ;; changing level of current topic.
2551 ;; Solicit dominates specified bullet-char.
2552 ;;;_ . Doc string:
2553 "Generate a topic prefix suitable for optional arg DEPTH, or current depth.
2555 All the arguments are optional.
2557 PRIOR-BULLET indicates the bullet of the prefix being changed, or
2558 nil if none. This bullet may be preserved (other options
2559 notwithstanding) if it is on the outline-distinctive-bullets-string,
2560 for instance.
2562 Second arg NEW indicates that a new topic is being opened after the
2563 topic at point, if non-nil. Default bullet for new topics, eg, may
2564 be set (contingent to other args) to numbered bullets if previous
2565 sibling is one. The implication otherwise is that the current topic
2566 is being adjusted - shifted or rebulleted - and we don't consider
2567 bullet or previous sibling.
2569 Third arg DEPTH forces the topic prefix to that depth, regardless of
2570 the current topics' depth.
2572 If SOLICIT is non-nil, then the choice of bullet is solicited from
2573 user. If it's a character, then that character is offered as the
2574 default, otherwise the one suited to the context \(according to
2575 distinction or depth) is offered. \(This overrides other options,
2576 including, eg, a distinctive PRIOR-BULLET.) If non-nil, then the
2577 context-specific bullet is used.
2579 Fifth arg, NUMBER-CONTROL, matters only if `outline-numbered-bullet'
2580 is non-nil *and* soliciting was not explicitly invoked. Then
2581 NUMBER-CONTROL non-nil forces prefix to either numbered or
2582 denumbered format, depending on the value of the sixth arg, INDEX.
2584 \(Note that NUMBER-CONTROL does *not* apply to level 1 topics. Sorry...)
2586 If NUMBER-CONTROL is non-nil and sixth arg INDEX is non-nil then
2587 the prefix of the topic is forced to be numbered. Non-nil
2588 NUMBER-CONTROL and nil INDEX forces non-numbered format on the
2589 bullet. Non-nil NUMBER-CONTROL and non-nil, non-number INDEX means
2590 that the index for the numbered prefix will be derived, by counting
2591 siblings back to start of level. If INDEX is a number, then that
2592 number is used as the index for the numbered prefix (allowing, eg,
2593 sequential renumbering to not require this function counting back the
2594 index for each successive sibling)."
2595 ;;;_ . Code:
2596 ;; The options are ordered in likely frequence of use, most common
2597 ;; highest, least lowest. Ie, more likely to be doing prefix
2598 ;; adjustments than soliciting, and yet more than numbering.
2599 ;; Current prefix is least dominant, but most likely to be commonly
2600 ;; specified...
2602 (let* (body
2603 numbering
2604 denumbering
2605 (depth (or depth (outline-depth)))
2606 (header-lead outline-header-prefix)
2607 (bullet-char
2609 ;; Getting value for bullet char is practically the whole job:
2611 (cond
2612 ; Simplest situation - level 1:
2613 ((<= depth 1) (setq header-lead "") outline-primary-bullet)
2614 ; Simple, too: all asterisks:
2615 (outline-old-style-prefixes
2616 ;; Cheat - make body the whole thing, null out header-lead and
2617 ;; bullet-char:
2618 (setq body (make-string depth
2619 (string-to-char outline-primary-bullet)))
2620 (setq header-lead "")
2623 ;; (Neither level 1 nor old-style, so we're space padding.
2624 ;; Sneak it in the condition of the next case, whatever it is.)
2626 ;; Solicitation overrides numbering and other cases:
2627 ((progn (setq body (make-string (- depth 2) ?\ ))
2628 ;; The actual condition:
2629 solicit)
2630 (let* ((got (outline-solicit-alternate-bullet depth solicit)))
2631 ;; Gotta check whether we're numbering and got a numbered bullet:
2632 (setq numbering (and outline-numbered-bullet
2633 (not (and number-control (not index)))
2634 (string= got outline-numbered-bullet)))
2635 ;; Now return what we got, regardless:
2636 got))
2638 ;; Numbering invoked through args:
2639 ((and outline-numbered-bullet number-control)
2640 (if (setq numbering (not (setq denumbering (not index))))
2641 outline-numbered-bullet
2642 (if (and prior-bullet
2643 (not (string= outline-numbered-bullet
2644 prior-bullet)))
2645 prior-bullet
2646 (outline-bullet-for-depth depth))))
2648 ;;; Neither soliciting nor controlled numbering ;;;
2649 ;;; (may be controlled denumbering, tho) ;;;
2651 ;; Check wrt previous sibling:
2652 ((and new ; only check for new prefixes
2653 (<= depth (outline-depth))
2654 outline-numbered-bullet ; ... & numbering enabled
2655 (not denumbering)
2656 (let ((sibling-bullet
2657 (save-excursion
2658 ;; Locate correct sibling:
2659 (or (>= depth (outline-depth))
2660 (outline-ascend-to-depth depth))
2661 (outline-get-bullet))))
2662 (if (and sibling-bullet
2663 (string= outline-numbered-bullet sibling-bullet))
2664 (setq numbering sibling-bullet)))))
2666 ;; Distinctive prior bullet?
2667 ((and prior-bullet
2668 (outline-distinctive-bullet prior-bullet)
2669 ;; Either non-numbered:
2670 (or (not (and outline-numbered-bullet
2671 (string= prior-bullet outline-numbered-bullet)))
2672 ;; or numbered, and not denumbering:
2673 (setq numbering (not denumbering)))
2674 ;; Here 'tis:
2675 prior-bullet))
2677 ;; Else, standard bullet per depth:
2678 ((outline-bullet-for-depth depth)))))
2680 (concat header-lead
2681 body
2682 bullet-char
2683 (if numbering
2684 (format "%d" (cond ((and index (numberp index)) index)
2685 (new (1+ (outline-sibling-index depth)))
2686 ((outline-sibling-index))))))
2689 ;;;_ > outline-open-topic (relative-depth &optional before use_sib_bullet)
2690 (defun outline-open-topic (relative-depth &optional before use_sib_bullet)
2691 "Open a new topic at depth DEPTH.
2693 New topic is situated after current one, unless optional flag BEFORE
2694 is non-nil, or unless current line is complete empty (not even
2695 whitespace), in which case open is done on current line.
2697 If USE_SIB_BULLET is true, use the bullet of the prior sibling.
2699 Nuances:
2701 - Creation of new topics is with respect to the visible topic
2702 containing the cursor, regardless of intervening concealed ones.
2704 - New headers are generally created after/before the body of a
2705 topic. However, they are created right at cursor location if the
2706 cursor is on a blank line, even if that breaks the current topic
2707 body. This is intentional, to provide a simple means for
2708 deliberately dividing topic bodies.
2710 - Double spacing of topic lists is preserved. Also, the first
2711 level two topic is created double-spaced (and so would be
2712 subsequent siblings, if that's left intact). Otherwise,
2713 single-spacing is used.
2715 - Creation of sibling or nested topics is with respect to the topic
2716 you're starting from, even when creating backwards. This way you
2717 can easily create a sibling in front of the current topic without
2718 having to go to its preceding sibling, and then open forward
2719 from there."
2721 (let* ((depth (+ (outline-current-depth) relative-depth))
2722 (opening-on-blank (if (looking-at "^\$")
2723 (not (setq before nil))))
2724 opening-numbered ; Will get while computing ref-topic, below
2725 ref-depth ; Will get while computing ref-topic, below
2726 ref-bullet ; Will get while computing ref-topic, next
2727 (ref-topic (save-excursion
2728 (cond ((< relative-depth 0)
2729 (outline-ascend-to-depth depth))
2730 ((>= relative-depth 1) nil)
2731 (t (outline-back-to-current-heading)))
2732 (setq ref-depth (outline-recent-depth))
2733 (setq ref-bullet
2734 (if (> outline-recent-prefix-end 1)
2735 (outline-recent-bullet)
2736 ""))
2737 (setq opening-numbered
2738 (save-excursion
2739 (and outline-numbered-bullet
2740 (or (<= relative-depth 0)
2741 (outline-descend-to-depth depth))
2742 (if (outline-numbered-type-prefix)
2743 outline-numbered-bullet))))
2744 (point)))
2745 dbl-space
2746 doing-beginning)
2748 (if (not opening-on-blank)
2749 ; Positioning and vertical
2750 ; padding - only if not
2751 ; opening-on-blank:
2752 (progn
2753 (goto-char ref-topic)
2754 (setq dbl-space ; Determine double space action:
2755 (or (and (<= relative-depth 0) ; not descending;
2756 (save-excursion
2757 ;; at b-o-b or preceded by a blank line?
2758 (or (> 0 (forward-line -1))
2759 (looking-at "^\\s-*$")
2760 (bobp)))
2761 (save-excursion
2762 ;; succeeded by a blank line?
2763 (outline-end-of-current-subtree)
2764 (bolp)))
2765 (and (= ref-depth 1)
2766 (or before
2767 (= depth 1)
2768 (save-excursion
2769 ;; Don't already have following
2770 ;; vertical padding:
2771 (not (outline-pre-next-preface)))))))
2773 ; Position to prior heading,
2774 ; if inserting backwards, and
2775 ; not going outwards:
2776 (if (and before (>= relative-depth 0))
2777 (progn (outline-back-to-current-heading)
2778 (setq doing-beginning (bobp))
2779 (if (not (bobp))
2780 (outline-previous-heading)))
2781 (if (and before (bobp))
2782 (outline-unprotected (open-line 1))))
2784 (if (<= relative-depth 0)
2785 ;; Not going inwards, don't snug up:
2786 (if doing-beginning
2787 (outline-unprotected (open-line (if dbl-space 2 1)))
2788 (if before
2789 (progn (end-of-line)
2790 (outline-pre-next-preface)
2791 (while (= ?\r (following-char))
2792 (forward-char 1))
2793 (if (not (looking-at "^$"))
2794 (outline-unprotected (open-line 1))))
2795 (outline-end-of-current-subtree)))
2796 ;; Going inwards - double-space if first offspring is,
2797 ;; otherwise snug up.
2798 (end-of-line) ; So we skip any concealed progeny.
2799 (outline-pre-next-preface)
2800 (if (bolp)
2801 ;; Blank lines between current header body and next
2802 ;; header - get to last substantive (non-white-space)
2803 ;; line in body:
2804 (re-search-backward "[^ \t\n]" nil t))
2805 (if (save-excursion
2806 (outline-next-heading)
2807 (if (> (outline-recent-depth) ref-depth)
2808 ;; This is an offspring.
2809 (progn (forward-line -1)
2810 (looking-at "^\\s-*$"))))
2811 (progn (forward-line 1)
2812 (outline-unprotected (open-line 1))))
2813 (end-of-line))
2814 ;;(if doing-beginning (goto-char doing-beginning))
2815 (if (not (bobp))
2816 (progn (if (and (not (> depth ref-depth))
2817 (not before))
2818 (outline-unprotected (open-line 1))
2819 (if (> depth ref-depth)
2820 (outline-unprotected (newline 1))
2821 (if dbl-space
2822 (outline-unprotected (open-line 1))
2823 (if (not before)
2824 (outline-unprotected (newline 1))))))
2825 (if dbl-space
2826 (outline-unprotected (newline 1)))
2827 (if (and (not (eobp))
2828 (not (bolp)))
2829 (forward-char 1))))
2831 (insert-string (concat (outline-make-topic-prefix opening-numbered
2833 depth)
2834 " "))
2836 ;;(if doing-beginning (save-excursion (newline (if dbl-space 2 1))))
2839 (outline-rebullet-heading (and use_sib_bullet ref-bullet);;; solicit
2840 depth ;;; depth
2841 nil ;;; number-control
2842 nil ;;; index
2843 t) (end-of-line)
2846 ;;;_ . open-topic contingencies
2847 ;;;_ ; base topic - one from which open was issued
2848 ;;;_ , beginning char
2849 ;;;_ , amount of space before will be used, unless opening in place
2850 ;;;_ , end char will be used, unless opening before (and it still may)
2851 ;;;_ ; absolute depth of new topic
2852 ;;;_ ! insert in place - overrides most stuff
2853 ;;;_ ; relative depth of new re base
2854 ;;;_ ; before or after base topic
2855 ;;;_ ; spacing around topic, if any, prior to new topic and at same depth
2856 ;;;_ ; buffer boundaries - special provisions for beginning and end ob
2857 ;;;_ ; level 1 topics have special provisions also - double space.
2858 ;;;_ ; location of new topic
2859 ;;;_ > outline-open-subtopic (arg)
2860 (defun outline-open-subtopic (arg)
2861 "Open new topic header at deeper level than the current one.
2863 Negative universal arg means to open deeper, but place the new topic
2864 prior to the current one."
2865 (interactive "p")
2866 (outline-open-topic 1 (> 0 arg)))
2867 ;;;_ > outline-open-sibtopic (arg)
2868 (defun outline-open-sibtopic (arg)
2869 "Open new topic header at same level as the current one.
2871 Positive universal arg means to use the bullet of the prior sibling.
2873 Negative universal arg means to place the new topic prior to the current
2874 one."
2875 (interactive "p")
2876 (outline-open-topic 0 (> 0 arg) (< 1 arg)))
2877 ;;;_ > outline-open-supertopic (arg)
2878 (defun outline-open-supertopic (arg)
2879 "Open new topic header at shallower level than the current one.
2881 Negative universal arg means to open shallower, but place the new
2882 topic prior to the current one."
2884 (interactive "p")
2885 (outline-open-topic -1 (> 0 arg)))
2887 ;;;_ - Outline Alteration
2888 ;;;_ : Topic Modification
2889 ;;;_ = outline-former-auto-filler
2890 (defvar outline-former-auto-filler nil
2891 "Name of modal fill function being wrapped by outline-auto-fill.")
2892 ;;;_ > outline-auto-fill ()
2893 (defun outline-auto-fill ()
2894 "Outline-mode autofill function.
2896 Maintains outline hanging topic indentation if
2897 `outline-use-hanging-indents' is set."
2898 (let ((fill-prefix (if outline-use-hanging-indents
2899 ;; Check for topic header indentation:
2900 (save-excursion
2901 (beginning-of-line)
2902 (if (looking-at outline-regexp)
2903 ;; ... construct indentation to account for
2904 ;; length of topic prefix:
2905 (make-string (progn (outline-end-of-prefix)
2906 (current-column))
2907 ?\ ))))))
2908 (if (or outline-former-auto-filler outline-use-hanging-indents)
2909 (do-auto-fill))))
2910 ;;;_ > outline-reindent-body (old-depth new-depth &optional number)
2911 (defun outline-reindent-body (old-depth new-depth &optional number)
2912 "Reindent body lines which were indented at old-depth to new-depth.
2914 Optional arg NUMBER indicates numbering is being added, and it must
2915 be accommodated.
2917 Note that refill of indented paragraphs is not done."
2919 (save-excursion
2920 (outline-end-of-prefix)
2921 (let* ((new-margin (current-column))
2922 excess old-indent-begin old-indent-end
2923 curr-ind
2924 ;; We want the column where the header-prefix text started
2925 ;; *before* the prefix was changed, so we infer it relative
2926 ;; to the new margin and the shift in depth:
2927 (old-margin (+ old-depth (- new-margin new-depth))))
2929 ;; Process lines up to (but excluding) next topic header:
2930 (outline-unprotected
2931 (save-match-data
2932 (while
2933 (and (re-search-forward "[\n\r]\\(\\s-*\\)"
2936 ;; Register the indent data, before we reset the
2937 ;; match data with a subsequent `looking-at':
2938 (setq old-indent-begin (match-beginning 1)
2939 old-indent-end (match-end 1))
2940 (not (looking-at outline-regexp)))
2941 (if (> 0 (setq excess (- (current-column)
2942 old-margin)))
2943 ;; Text starts left of old margin - don't adjust:
2945 ;; Text was hanging at or right of old left margin -
2946 ;; reindent it, preserving its existing indentation
2947 ;; beyond the old margin:
2948 (delete-region old-indent-begin old-indent-end)
2949 (indent-to (+ new-margin excess)))))))))
2950 ;;;_ > outline-rebullet-current-heading (arg)
2951 (defun outline-rebullet-current-heading (arg)
2952 "Solicit new bullet for current visible heading."
2953 (interactive "p")
2954 (let ((initial-col (current-column))
2955 (on-bullet (eq (point)(outline-current-bullet-pos)))
2956 (backwards (if (< arg 0)
2957 (setq arg (* arg -1)))))
2958 (while (> arg 0)
2959 (save-excursion (outline-back-to-current-heading)
2960 (outline-end-of-prefix)
2961 (outline-rebullet-heading t ;;; solicit
2962 nil ;;; depth
2963 nil ;;; number-control
2964 nil ;;; index
2965 t)) ;;; do-successors
2966 (setq arg (1- arg))
2967 (if (<= arg 0)
2969 (setq initial-col nil) ; Override positioning back to init col
2970 (if (not backwards)
2971 (outline-next-visible-heading 1)
2972 (outline-goto-prefix)
2973 (outline-next-visible-heading -1))))
2974 (message "Done.")
2975 (cond (on-bullet (goto-char (outline-current-bullet-pos)))
2976 (initial-col (move-to-column initial-col)))))
2977 ;;;_ > outline-rebullet-heading (&optional solicit ...)
2978 (defun outline-rebullet-heading (&optional solicit
2979 new-depth
2980 number-control
2981 index
2982 do-successors)
2984 "Adjust bullet of current topic prefix.
2986 All args are optional.
2988 If SOLICIT is non-nil, then the choice of bullet is solicited from
2989 user. If it's a character, then that character is offered as the
2990 default, otherwise the one suited to the context \(according to
2991 distinction or depth) is offered. If non-nil, then the
2992 context-specific bullet is just used.
2994 Second arg DEPTH forces the topic prefix to that depth, regardless
2995 of the topic's current depth.
2997 Third arg NUMBER-CONTROL can force the prefix to or away from
2998 numbered form. It has effect only if `outline-numbered-bullet' is
2999 non-nil and soliciting was not explicitly invoked (via first arg).
3000 Its effect, numbering or denumbering, then depends on the setting
3001 of the forth arg, INDEX.
3003 If NUMBER-CONTROL is non-nil and forth arg INDEX is nil, then the
3004 prefix of the topic is forced to be non-numbered. Null index and
3005 non-nil NUMBER-CONTROL forces denumbering. Non-nil INDEX (and
3006 non-nil NUMBER-CONTROL) forces a numbered-prefix form. If non-nil
3007 INDEX is a number, then that number is used for the numbered
3008 prefix. Non-nil and non-number means that the index for the
3009 numbered prefix will be derived by outline-make-topic-prefix.
3011 Fifth arg DO-SUCCESSORS t means re-resolve count on succeeding
3012 siblings.
3014 Cf vars `outline-stylish-prefixes', `outline-old-style-prefixes',
3015 and `outline-numbered-bullet', which all affect the behavior of
3016 this function."
3018 (let* ((current-depth (outline-depth))
3019 (new-depth (or new-depth current-depth))
3020 (mb outline-recent-prefix-beginning)
3021 (me outline-recent-prefix-end)
3022 (current-bullet (buffer-substring (- me 1) me))
3023 (new-prefix (outline-make-topic-prefix current-bullet
3025 new-depth
3026 solicit
3027 number-control
3028 index)))
3030 ;; Is new one is identical to old?
3031 (if (and (= current-depth new-depth)
3032 (string= current-bullet
3033 (substring new-prefix (1- (length new-prefix)))))
3034 ;; Nothing to do:
3037 ;; New prefix probably different from old:
3038 ; get rid of old one:
3039 (outline-unprotected (delete-region mb me))
3040 (goto-char mb)
3041 ; Dispense with number if
3042 ; numbered-bullet prefix:
3043 (if (and outline-numbered-bullet
3044 (string= outline-numbered-bullet current-bullet)
3045 (looking-at "[0-9]+"))
3046 (outline-unprotected
3047 (delete-region (match-beginning 0)(match-end 0))))
3049 ; Put in new prefix:
3050 (outline-unprotected (insert-string new-prefix))
3052 ;; Reindent the body if elected and margin changed:
3053 (if (and outline-reindent-bodies
3054 (not (= new-depth current-depth)))
3055 (outline-reindent-body current-depth new-depth))
3057 ;; Recursively rectify successive siblings of orig topic if
3058 ;; caller elected for it:
3059 (if do-successors
3060 (save-excursion
3061 (while (outline-next-sibling new-depth nil)
3062 (setq index
3063 (cond ((numberp index) (1+ index))
3064 ((not number-control) (outline-sibling-index))))
3065 (if (outline-numbered-type-prefix)
3066 (outline-rebullet-heading nil ;;; solicit
3067 new-depth ;;; new-depth
3068 number-control;;; number-control
3069 index ;;; index
3070 nil))))) ;;;(dont!)do-successors
3071 ) ; (if (and (= current-depth new-depth)...))
3072 ) ; let* ((current-depth (outline-depth))...)
3073 ) ; defun
3074 ;;;_ > outline-rebullet-topic (arg)
3075 (defun outline-rebullet-topic (arg)
3076 "Like outline-rebullet-topic-grunt, but start from topic visible at point.
3078 Descends into invisible as well as visible topics, however.
3080 With repeat count, shift topic depth by that amount."
3081 (interactive "P")
3082 (let ((start-col (current-column))
3083 (was-eol (eolp)))
3084 (save-excursion
3085 ;; Normalize arg:
3086 (cond ((null arg) (setq arg 0))
3087 ((listp arg) (setq arg (car arg))))
3088 ;; Fill the user in, in case we're shifting a big topic:
3089 (if (not (zerop arg)) (message "Shifting..."))
3090 (outline-back-to-current-heading)
3091 (if (<= (+ (outline-recent-depth) arg) 0)
3092 (error "Attempt to shift topic below level 1"))
3093 (outline-rebullet-topic-grunt arg)
3094 (if (not (zerop arg)) (message "Shifting... done.")))
3095 (move-to-column (max 0 (+ start-col arg)))))
3096 ;;;_ > outline-rebullet-topic-grunt (&optional relative-depth ...)
3097 (defun outline-rebullet-topic-grunt (&optional relative-depth
3098 starting-depth
3099 starting-point
3100 index
3101 do-successors)
3103 "Rebullet the topic at point, visible or invisible, and all
3104 contained subtopics. See outline-rebullet-heading for rebulleting
3105 behavior.
3107 All arguments are optional.
3109 First arg RELATIVE-DEPTH means to shift the depth of the entire
3110 topic that amount.
3112 The rest of the args are for internal recursive use by the function
3113 itself. The are STARTING-DEPTH, STARTING-POINT, and INDEX."
3115 (let* ((relative-depth (or relative-depth 0))
3116 (new-depth (outline-depth))
3117 (starting-depth (or starting-depth new-depth))
3118 (on-starting-call (null starting-point))
3119 (index (or index
3120 ;; Leave index null on starting call, so rebullet-heading
3121 ;; calculates it at what might be new depth:
3122 (and (or (zerop relative-depth)
3123 (not on-starting-call))
3124 (outline-sibling-index))))
3125 (moving-outwards (< 0 relative-depth))
3126 (starting-point (or starting-point (point))))
3128 ;; Sanity check for excessive promotion done only on starting call:
3129 (and on-starting-call
3130 moving-outwards
3131 (> 0 (+ starting-depth relative-depth))
3132 (error "Attempt to shift topic out beyond level 1.")) ;;; ====>
3134 (cond ((= starting-depth new-depth)
3135 ;; We're at depth to work on this one:
3136 (outline-rebullet-heading nil ;;; solicit
3137 (+ starting-depth ;;; starting-depth
3138 relative-depth)
3139 nil ;;; number
3140 index ;;; index
3141 ;; Every contained topic will get hit,
3142 ;; and we have to get to outside ones
3143 ;; deliberately:
3144 nil) ;;; do-successors
3145 ;; ... and work on subsequent ones which are at greater depth:
3146 (setq index 0)
3147 (outline-next-heading)
3148 (while (and (not (eobp))
3149 (< starting-depth (outline-recent-depth)))
3150 (setq index (1+ index))
3151 (outline-rebullet-topic-grunt relative-depth ;;; relative-depth
3152 (1+ starting-depth);;;starting-depth
3153 starting-point ;;; starting-point
3154 index))) ;;; index
3156 ((< starting-depth new-depth)
3157 ;; Rare case - subtopic more than one level deeper than parent.
3158 ;; Treat this one at an even deeper level:
3159 (outline-rebullet-topic-grunt relative-depth ;;; relative-depth
3160 new-depth ;;; starting-depth
3161 starting-point ;;; starting-point
3162 index))) ;;; index
3164 (if on-starting-call
3165 (progn
3166 ;; Rectify numbering of former siblings of the adjusted topic,
3167 ;; if topic has changed depth
3168 (if (or do-successors
3169 (and (not (zerop relative-depth))
3170 (or (= (outline-recent-depth) starting-depth)
3171 (= (outline-recent-depth) (+ starting-depth
3172 relative-depth)))))
3173 (outline-rebullet-heading nil nil nil nil t))
3174 ;; Now rectify numbering of new siblings of the adjusted topic,
3175 ;; if depth has been changed:
3176 (progn (goto-char starting-point)
3177 (if (not (zerop relative-depth))
3178 (outline-rebullet-heading nil nil nil nil t)))))
3181 ;;;_ > outline-renumber-to-depth (&optional depth)
3182 (defun outline-renumber-to-depth (&optional depth)
3183 "Renumber siblings at current depth.
3185 Affects superior topics if optional arg DEPTH is less than current depth.
3187 Returns final depth."
3189 ;; Proceed by level, processing subsequent siblings on each,
3190 ;; ascending until we get shallower than the start depth:
3192 (let ((ascender (outline-depth))
3193 was-eobp)
3194 (while (and (not (eobp))
3195 (outline-depth)
3196 (>= (outline-recent-depth) depth)
3197 (>= ascender depth))
3198 ; Skip over all topics at
3199 ; lesser depths, which can not
3200 ; have been disturbed:
3201 (while (and (not (setq was-eobp (eobp)))
3202 (> (outline-recent-depth) ascender))
3203 (outline-next-heading))
3204 ; Prime ascender for ascension:
3205 (setq ascender (1- (outline-recent-depth)))
3206 (if (>= (outline-recent-depth) depth)
3207 (outline-rebullet-heading nil ;;; solicit
3208 nil ;;; depth
3209 nil ;;; number-control
3210 nil ;;; index
3211 t)) ;;; do-successors
3212 (if was-eobp (goto-char (point-max)))))
3213 (outline-recent-depth))
3214 ;;;_ > outline-number-siblings (&optional denumber)
3215 (defun outline-number-siblings (&optional denumber)
3216 "Assign numbered topic prefix to this topic and its siblings.
3218 With universal argument, denumber - assign default bullet to this
3219 topic and its siblings.
3221 With repeated universal argument (`^U^U'), solicit bullet for each
3222 rebulleting each topic at this level."
3224 (interactive "P")
3226 (save-excursion
3227 (outline-back-to-current-heading)
3228 (outline-beginning-of-level)
3229 (let ((depth (outline-recent-depth))
3230 (index (if (not denumber) 1))
3231 (use-bullet (equal '(16) denumber))
3232 (more t))
3233 (while more
3234 (outline-rebullet-heading use-bullet ;;; solicit
3235 depth ;;; depth
3236 t ;;; number-control
3237 index ;;; index
3238 nil) ;;; do-successors
3239 (if index (setq index (1+ index)))
3240 (setq more (outline-next-sibling depth nil))))))
3241 ;;;_ > outline-shift-in (arg)
3242 (defun outline-shift-in (arg)
3243 "Increase depth of current heading and any topics collapsed within it."
3244 (interactive "p")
3245 (outline-rebullet-topic arg))
3246 ;;;_ > outline-shift-out (arg)
3247 (defun outline-shift-out (arg)
3248 "Decrease depth of current heading and any topics collapsed within it."
3249 (interactive "p")
3250 (outline-rebullet-topic (* arg -1)))
3251 ;;;_ : Surgery (kill-ring) functions with special provisions for outlines:
3252 ;;;_ > outline-kill-line (&optional arg)
3253 (defun outline-kill-line (&optional arg)
3254 "Kill line, adjusting subsequent lines suitably for outline mode."
3256 (interactive "*P")
3257 (if (not (and (outline-mode-p) ; active outline mode,
3258 outline-numbered-bullet ; numbers may need adjustment,
3259 (bolp) ; may be clipping topic head,
3260 (looking-at outline-regexp))) ; are clipping topic head.
3261 ;; Above conditions do not obtain - just do a regular kill:
3262 (kill-line arg)
3263 ;; Ah, have to watch out for adjustments:
3264 (let* ((depth (outline-depth)))
3265 ; Do the kill:
3266 (kill-line arg)
3267 ; Provide some feedback:
3268 (sit-for 0)
3269 (save-excursion
3270 ; Start with the topic
3271 ; following killed line:
3272 (if (not (looking-at outline-regexp))
3273 (outline-next-heading))
3274 (outline-renumber-to-depth depth)))))
3275 ;;;_ > outline-kill-topic ()
3276 (defun outline-kill-topic ()
3277 "Kill topic together with subtopics.
3279 Leaves primary topic's trailing vertical whitespace, if any."
3281 ;; Some finagling is done to make complex topic kills appear faster
3282 ;; than they actually are. A redisplay is performed immediately
3283 ;; after the region is disposed of, though the renumbering process
3284 ;; has yet to be performed. This means that there may appear to be
3285 ;; a lag *after* the kill has been performed.
3287 (interactive)
3288 (let* ((beg (prog1 (outline-back-to-current-heading)(beginning-of-line)))
3289 (depth (outline-recent-depth)))
3290 (outline-end-of-current-subtree)
3291 (if (not (eobp))
3292 (if (or (not (looking-at "^$"))
3293 ;; A blank line - cut it with this topic *unless* this
3294 ;; is the last topic at this level, in which case
3295 ;; we'll leave the blank line as part of the
3296 ;; containing topic:
3297 (save-excursion
3298 (and (outline-next-heading)
3299 (>= (outline-recent-depth) depth))))
3300 (forward-char 1)))
3302 (kill-region beg (point))
3303 (sit-for 0)
3304 (save-excursion
3305 (outline-renumber-to-depth depth))))
3306 ;;;_ > outline-yank-processing ()
3307 (defun outline-yank-processing (&optional arg)
3309 "Incidental outline-specific business to be done just after text yanks.
3311 Does depth adjustment of yanked topics, when:
3313 1 the stuff being yanked starts with a valid outline header prefix, and
3314 2 it is being yanked at the end of a line which consists of only a valid
3315 topic prefix.
3317 Also, adjusts numbering of subsequent siblings when appropriate.
3319 Depth adjustment alters the depth of all the topics being yanked
3320 the amount it takes to make the first topic have the depth of the
3321 header into which it's being yanked.
3323 The point is left in front of yanked, adjusted topics, rather than
3324 at the end (and vice-versa with the mark). Non-adjusted yanks,
3325 however, are left exactly like normal, non-outline-specific yanks."
3327 (interactive "*P")
3328 ; Get to beginning, leaving
3329 ; region around subject:
3330 (if (< (my-mark-marker t) (point))
3331 (exchange-point-and-mark))
3332 (let* ((subj-beg (point))
3333 (subj-end (my-mark-marker t))
3334 ;; 'resituate' if yanking an entire topic into topic header:
3335 (resituate (and (outline-e-o-prefix-p)
3336 (looking-at (concat "\\(" outline-regexp "\\)"))
3337 (outline-prefix-data (match-beginning 1)
3338 (match-end 1))))
3339 ;; `rectify-numbering' if resituating (where several topics may
3340 ;; be resituating) or yanking a topic into a topic slot (bol):
3341 (rectify-numbering (or resituate
3342 (and (bolp) (looking-at outline-regexp)))))
3343 (if resituate
3344 ; The yanked stuff is a topic:
3345 (let* ((prefix-len (- (match-end 1) subj-beg))
3346 (subj-depth (outline-recent-depth))
3347 (prefix-bullet (outline-recent-bullet))
3348 (adjust-to-depth
3349 ;; Nil if adjustment unnecessary, otherwise depth to which
3350 ;; adjustment should be made:
3351 (save-excursion
3352 (and (goto-char subj-end)
3353 (eolp)
3354 (goto-char subj-beg)
3355 (and (looking-at outline-regexp)
3356 (progn
3357 (beginning-of-line)
3358 (not (= (point) subj-beg)))
3359 (looking-at outline-regexp)
3360 (outline-prefix-data (match-beginning 0)
3361 (match-end 0)))
3362 (outline-recent-depth))))
3363 done
3364 (more t))
3365 (setq rectify-numbering outline-numbered-bullet)
3366 (if adjust-to-depth
3367 ; Do the adjustment:
3368 (progn
3369 (message "... yanking") (sit-for 0)
3370 (save-restriction
3371 (narrow-to-region subj-beg subj-end)
3372 ; Trim off excessive blank
3373 ; line at end, if any:
3374 (goto-char (point-max))
3375 (if (looking-at "^$")
3376 (outline-unprotected (delete-char -1)))
3377 ; Work backwards, with each
3378 ; shallowest level,
3379 ; successively excluding the
3380 ; last processed topic from
3381 ; the narrow region:
3382 (while more
3383 (outline-back-to-current-heading)
3384 ; go as high as we can in each bunch:
3385 (while (outline-ascend-to-depth (1- (outline-depth))))
3386 (save-excursion
3387 (outline-rebullet-topic-grunt (- adjust-to-depth
3388 subj-depth))
3389 (outline-depth))
3390 (if (setq more (not (bobp)))
3391 (progn (widen)
3392 (forward-char -1)
3393 (narrow-to-region subj-beg (point))))))
3394 (message "")
3395 ;; Preserve new bullet if it's a distinctive one, otherwise
3396 ;; use old one:
3397 (if (string-match (regexp-quote prefix-bullet)
3398 outline-distinctive-bullets-string)
3399 ; Delete from bullet of old to
3400 ; before bullet of new:
3401 (progn
3402 (beginning-of-line)
3403 (delete-region (point) subj-beg)
3404 (set-marker (my-mark-marker t) subj-end)
3405 (goto-char subj-beg)
3406 (outline-end-of-prefix))
3407 ; Delete base subj prefix,
3408 ; leaving old one:
3409 (delete-region (point) (+ (point)
3410 prefix-len
3411 (- adjust-to-depth subj-depth)))
3412 ; and delete residual subj
3413 ; prefix digits and space:
3414 (while (looking-at "[0-9]") (delete-char 1))
3415 (if (looking-at " ") (delete-char 1))))
3416 (exchange-point-and-mark))))
3417 (if rectify-numbering
3418 (progn
3419 (save-excursion
3420 ; Give some preliminary feedback:
3421 (message "... reconciling numbers") (sit-for 0)
3422 ; ... and renumber, in case necessary:
3423 (goto-char subj-beg)
3424 (if (outline-goto-prefix)
3425 (outline-rebullet-heading nil ;;; solicit
3426 (outline-depth) ;;; depth
3427 nil ;;; number-control
3428 nil ;;; index
3430 (message ""))))
3431 (if (not resituate)
3432 (exchange-point-and-mark))))
3433 ;;;_ > outline-yank (&optional arg)
3434 (defun outline-yank (&optional arg)
3435 "Outline-mode yank, with depth and numbering adjustment of yanked topics.
3437 Non-topic yanks work no differently than normal yanks.
3439 If a topic is being yanked into a bare topic prefix, the depth of the
3440 yanked topic is adjusted to the depth of the topic prefix.
3442 1 we're yanking in an outline-mode buffer
3443 2 the stuff being yanked starts with a valid outline header prefix, and
3444 3 it is being yanked at the end of a line which consists of only a valid
3445 topic prefix.
3447 If these conditions hold then the depth of the yanked topics are all
3448 adjusted the amount it takes to make the first one at the depth of the
3449 header into which it's being yanked.
3451 The point is left in front of yanked, adjusted topics, rather than
3452 at the end (and vice-versa with the mark). Non-adjusted yanks,
3453 however, (ones that don't qualify for adjustment) are handled
3454 exactly like normal yanks.
3456 Numbering of yanked topics, and the successive siblings at the depth
3457 into which they're being yanked, is adjusted.
3459 Outline-yank-pop works with outline-yank just like normal yank-pop
3460 works with normal yank in non-outline buffers."
3462 (interactive "*P")
3463 (setq this-command 'yank)
3464 (yank arg)
3465 (if (outline-mode-p)
3466 (outline-yank-processing)))
3467 ;;;_ > outline-yank-pop (&optional arg)
3468 (defun outline-yank-pop (&optional arg)
3469 "Yank-pop like outline-yank when popping to bare outline prefixes.
3471 Adapts level of popped topics to level of fresh prefix.
3473 Note - prefix changes to distinctive bullets will stick, if followed
3474 by pops to non-distinctive yanks. Bug..."
3476 (interactive "*p")
3477 (setq this-command 'yank)
3478 (yank-pop arg)
3479 (if (outline-mode-p)
3480 (outline-yank-processing)))
3482 ;;;_ - Specialty bullet functions
3483 ;;;_ : File Cross references
3484 ;;;_ > outline-resolve-xref ()
3485 (defun outline-resolve-xref ()
3486 "Pop to file associated with current heading, if it has an xref bullet.
3488 \(Works according to setting of `outline-file-xref-bullet')."
3489 (interactive)
3490 (if (not outline-file-xref-bullet)
3491 (error
3492 "outline cross references disabled - no `outline-file-xref-bullet'")
3493 (if (not (string= (outline-current-bullet) outline-file-xref-bullet))
3494 (error "current heading lacks cross-reference bullet `%s'"
3495 outline-file-xref-bullet)
3496 (let (file-name)
3497 (save-excursion
3498 (let* ((text-start outline-recent-prefix-end)
3499 (heading-end (progn (end-of-line) (point))))
3500 (goto-char text-start)
3501 (setq file-name
3502 (if (re-search-forward "\\s-\\(\\S-*\\)" heading-end t)
3503 (buffer-substring (match-beginning 1) (match-end 1))))))
3504 (setq file-name
3505 (if (not (= (aref file-name 0) ?:))
3506 (expand-file-name file-name)
3507 ; A registry-files ref, strip the `:'
3508 ; and try to follow it:
3509 (let ((reg-ref (reference-registered-file
3510 (substring file-name 1) nil t)))
3511 (if reg-ref (car (cdr reg-ref))))))
3512 (if (or (file-exists-p file-name)
3513 (if (file-writable-p file-name)
3514 (y-or-n-p (format "%s not there, create one? "
3515 file-name))
3516 (error "%s not found and can't be created" file-name)))
3517 (condition-case failure
3518 (find-file-other-window file-name)
3519 ('error failure))
3520 (error "%s not found" file-name))
3526 ;;;_ #6 Exposure Control
3528 ;;;_ - Fundamental
3529 ;;;_ > outline-flag-region (from to flag)
3530 (defmacro outline-flag-region (from to flag)
3531 "Hide or show lines from FROM to TO, via emacs selective-display FLAG char.
3532 Ie, text following flag C-m \(carriage-return) is hidden until the
3533 next C-j (newline) char.
3535 Returns the endpoint of the region."
3536 `(let ((buffer-read-only nil)
3537 (outline-override-protect t))
3538 (subst-char-in-region ,from ,to
3539 (if (= ,flag ?\n) ?\r ?\n)
3540 ,flag t)))
3541 ;;;_ > outline-flag-current-subtree (flag)
3542 (defun outline-flag-current-subtree (flag)
3543 "Hide or show subtree of currently-visible topic.
3545 See `outline-flag-region' for more details."
3547 (save-excursion
3548 (outline-back-to-current-heading)
3549 (outline-flag-region (point)
3550 (progn (outline-end-of-current-subtree) (1- (point)))
3551 flag)))
3553 ;;;_ - Topic-specific
3554 ;;;_ > outline-show-entry ()
3555 (defun outline-show-entry ()
3556 "Like `outline-show-current-entry', reveals entries nested in hidden topics.
3558 This is a way to give restricted peek at a concealed locality without the
3559 expense of exposing its context, but can leave the outline with aberrant
3560 exposure. outline-hide-current-entry-completely or outline-show-offshoot
3561 should be used after the peek to rectify the exposure."
3563 (interactive)
3564 (save-excursion
3565 (let ((at (point))
3566 beg end)
3567 (outline-goto-prefix)
3568 (setq beg (if (= (preceding-char) ?\r) (1- (point)) (point)))
3569 (re-search-forward "[\n\r]" nil t)
3570 (setq end (1- (if (< at (point))
3571 ;; We're on topic head line - show only it:
3572 (point)
3573 ;; or we're in body - include it:
3574 (max beg (or (outline-pre-next-preface) (point))))))
3575 (outline-flag-region beg end ?\n)
3576 (list beg end))))
3577 ;;;_ > outline-show-children (&optional level strict)
3578 (defun outline-show-children (&optional level strict)
3580 "If point is visible, show all direct subheadings of this heading.
3582 Otherwise, do outline-show-to-offshoot, and then show subheadings.
3584 Optional LEVEL specifies how many levels below the current level
3585 should be shown, or all levels if t. Default is 1.
3587 Optional STRICT means don't resort to -show-to-offshoot, no matter
3588 what. This is basically so -show-to-offshoot, which is called by
3589 this function, can employ the pure offspring-revealing capabilities of
3592 Returns point at end of subtree that was opened, if any. (May get a
3593 point of non-opened subtree?)"
3595 (interactive "p")
3596 (let (max-pos)
3597 (if (and (not strict)
3598 (outline-hidden-p))
3600 (progn (outline-show-to-offshoot) ; Point's concealed, open to
3601 ; expose it.
3602 ;; Then recurse, but with "strict" set so we don't
3603 ;; infinite regress:
3604 (setq max-pos (outline-show-children level t)))
3606 (save-excursion
3607 (save-restriction
3608 (let* ((start-pt (point))
3609 (chart (outline-chart-subtree (or level 1)))
3610 (to-reveal (outline-chart-to-reveal chart (or level 1))))
3611 (goto-char start-pt)
3612 (if (and strict (= (preceding-char) ?\r))
3613 ;; Concealed root would already have been taken care of,
3614 ;; unless strict was set.
3615 (progn
3616 (outline-flag-region (point) (outline-snug-back) ?\n)
3617 (if outline-show-bodies
3618 (progn (goto-char (car to-reveal))
3619 (outline-show-current-entry)))))
3620 (while to-reveal
3621 (goto-char (car to-reveal))
3622 (outline-flag-region (point) (outline-snug-back) ?\n)
3623 (if outline-show-bodies
3624 (progn (goto-char (car to-reveal))
3625 (outline-show-current-entry)))
3626 (setq to-reveal (cdr to-reveal)))))))))
3627 ;;;_ > outline-hide-point-reconcile ()
3628 (defun outline-hide-reconcile ()
3629 "Like `outline-hide-current-entry'; hides completely if within hidden region.
3631 Specifically intended for aberrant exposure states, like entries that were
3632 exposed by outline-show-entry but are within otherwise concealed regions."
3633 (interactive)
3634 (save-excursion
3635 (outline-goto-prefix)
3636 (outline-flag-region (if (not (bobp)) (1- (point)) (point))
3637 (progn (outline-pre-next-preface)
3638 (if (= ?\r (following-char))
3639 (point)
3640 (1- (point))))
3641 ?\r)))
3642 ;;;_ > outline-show-to-offshoot ()
3643 (defun outline-show-to-offshoot ()
3644 "Like outline-show-entry, but reveals all concealed ancestors, as well.
3646 As with outline-hide-current-entry-completely, useful for rectifying
3647 aberrant exposure states produced by outline-show-entry."
3649 (interactive)
3650 (save-excursion
3651 (let ((orig-pt (point))
3652 (orig-pref (outline-goto-prefix))
3653 (last-at (point))
3654 bag-it)
3655 (while (or bag-it (= (preceding-char) ?\r))
3656 (beginning-of-line)
3657 (if (= last-at (setq last-at (point)))
3658 ;; Oops, we're not making any progress! Show the current
3659 ;; topic completely, and bag this try.
3660 (progn (beginning-of-line)
3661 (outline-show-current-subtree)
3662 (goto-char orig-pt)
3663 (setq bag-it t)
3664 (beep)
3665 (message "%s: %s"
3666 "outline-show-to-offshoot: "
3667 "Aberrant nesting encountered.")))
3668 (outline-show-children)
3669 (goto-char orig-pref))
3670 (goto-char orig-pt)))
3671 (if (outline-hidden-p)
3672 (outline-show-entry)))
3673 ;;;_ > outline-hide-current-entry ()
3674 (defun outline-hide-current-entry ()
3675 "Hide the body directly following this heading."
3676 (interactive)
3677 (outline-back-to-current-heading)
3678 (save-excursion
3679 (outline-flag-region (point)
3680 (progn (outline-end-of-current-entry) (point))
3681 ?\r)))
3682 ;;;_ > outline-show-current-entry (&optional arg)
3683 (defun outline-show-current-entry (&optional arg)
3685 "Show body following current heading, or hide the entry if repeat count."
3687 (interactive "P")
3688 (if arg
3689 (outline-hide-current-entry)
3690 (save-excursion
3691 (outline-flag-region (point)
3692 (progn (outline-end-of-current-entry) (point))
3693 ?\n))))
3694 ;;;_ > outline-hide-current-entry-completely ()
3695 ; ... outline-hide-current-entry-completely also for isearch dynamic exposure:
3696 (defun outline-hide-current-entry-completely ()
3697 "Like outline-hide-current-entry, but conceal topic completely.
3699 Specifically intended for aberrant exposure states, like entries that were
3700 exposed by outline-show-entry but are within otherwise concealed regions."
3701 (interactive)
3702 (save-excursion
3703 (outline-goto-prefix)
3704 (outline-flag-region (if (not (bobp)) (1- (point)) (point))
3705 (progn (outline-pre-next-preface)
3706 (if (= ?\r (following-char))
3707 (point)
3708 (1- (point))))
3709 ?\r)))
3710 ;;;_ > outline-show-current-subtree (&optional arg)
3711 (defun outline-show-current-subtree (&optional arg)
3712 "Show everything within the current topic. With a repeat-count,
3713 expose this topic and its siblings."
3714 (interactive "P")
3715 (save-excursion
3716 (if (<= (outline-current-depth) 0)
3717 ;; Outside any topics - try to get to the first:
3718 (if (not (outline-next-heading))
3719 (error "No topics.")
3720 ;; got to first, outermost topic - set to expose it and siblings:
3721 (message "Above outermost topic - exposing all.")
3722 (outline-flag-region (point-min)(point-max) ?\n))
3723 (if (not arg)
3724 (outline-flag-current-subtree ?\n)
3725 (outline-beginning-of-level)
3726 (outline-expose-topic '(* :))))))
3727 ;;;_ > outline-hide-current-subtree (&optional just-close)
3728 (defun outline-hide-current-subtree (&optional just-close)
3729 "Close the current topic, or containing topic if this one is already closed.
3731 If this topic is closed and it's a top level topic, close this topic
3732 and its siblings.
3734 If optional arg JUST-CLOSE is non-nil, do not treat the parent or
3735 siblings, even if the target topic is already closed."
3737 (interactive)
3738 (let ((from (point))
3739 (orig-eol (progn (end-of-line)
3740 (if (not (outline-goto-prefix))
3741 (error "No topics found.")
3742 (end-of-line)(point)))))
3743 (outline-flag-current-subtree ?\r)
3744 (goto-char from)
3745 (if (and (= orig-eol (progn (goto-char orig-eol)
3746 (end-of-line)
3747 (point)))
3748 (not just-close)
3749 ;; Structure didn't change - try hiding current level:
3750 (goto-char from)
3751 (if (outline-up-current-level 1 t)
3753 (goto-char 0)
3754 (let ((msg
3755 "Top-level topic already closed - closing siblings..."))
3756 (message msg)
3757 (outline-expose-topic '(0 :))
3758 (message (concat msg " Done.")))
3759 nil)
3760 (/= (outline-recent-depth) 0))
3761 (outline-hide-current-subtree))
3762 (goto-char from)))
3763 ;;;_ > outline-show-current-branches ()
3764 (defun outline-show-current-branches ()
3765 "Show all subheadings of this heading, but not their bodies."
3766 (interactive)
3767 (beginning-of-line)
3768 (outline-show-children t))
3769 ;;;_ > outline-hide-current-leaves ()
3770 (defun outline-hide-current-leaves ()
3771 "Hide the bodies of the current topic and all its offspring."
3772 (interactive)
3773 (outline-back-to-current-heading)
3774 (outline-hide-region-body (point) (progn (outline-end-of-current-subtree)
3775 (point))))
3777 ;;;_ - Region and beyond
3778 ;;;_ > outline-show-all ()
3779 (defun outline-show-all ()
3780 "Show all of the text in the buffer."
3781 (interactive)
3782 (message "Exposing entire buffer...")
3783 (outline-flag-region (point-min) (point-max) ?\n)
3784 (message "Exposing entire buffer... Done."))
3785 ;;;_ > outline-hide-bodies ()
3786 (defun outline-hide-bodies ()
3787 "Hide all of buffer except headings."
3788 (interactive)
3789 (outline-hide-region-body (point-min) (point-max)))
3790 ;;;_ > outline-hide-region-body (start end)
3791 (defun outline-hide-region-body (start end)
3792 "Hide all body lines in the region, but not headings."
3793 (save-excursion
3794 (save-restriction
3795 (narrow-to-region start end)
3796 (goto-char (point-min))
3797 (while (not (eobp))
3798 (outline-flag-region (point)
3799 (progn (outline-pre-next-preface) (point)) ?\r)
3800 (if (not (eobp))
3801 (forward-char
3802 (if (looking-at "[\n\r][\n\r]")
3803 2 1)))))))
3805 ;;;_ > outline-expose-topic (spec)
3806 (defun outline-expose-topic (spec)
3807 "Apply exposure specs to successive outline topic items.
3809 Use the more convenient frontend, `outline-new-exposure', if you don't
3810 need evaluation of the arguments, or even better, the `outline-layout'
3811 variable-keyed mode-activation/auto-exposure feature of allout outline
3812 mode. See the respective documentation strings for more details.
3814 Cursor is left at start position.
3816 SPEC is either a number or a list.
3818 Successive specs on a list are applied to successive sibling topics.
3820 A simple spec \(either a number, one of a few symbols, or the null
3821 list) dictates the exposure for the corresponding topic.
3823 Non-null lists recursively designate exposure specs for respective
3824 subtopics of the current topic.
3826 The `:' repeat spec is used to specify exposure for any number of
3827 successive siblings, up to the trailing ones for which there are
3828 explicit specs following the `:'.
3830 Simple (numeric and null-list) specs are interpreted as follows:
3832 Numbers indicate the relative depth to open the corresponding topic.
3833 - negative numbers force the topic to be closed before opening to the
3834 absolute value of the number, so all siblings are open only to
3835 that level.
3836 - positive numbers open to the relative depth indicated by the
3837 number, but do not force already opened subtopics to be closed.
3838 - 0 means to close topic - hide all offspring.
3839 : - `repeat'
3840 apply prior element to all siblings at current level, *up to*
3841 those siblings that would be covered by specs following the `:'
3842 on the list. Ie, apply to all topics at level but the last
3843 ones. \(Only first of multiple colons at same level is
3844 respected - subsequent ones are discarded.)
3845 * - completely opens the topic, including bodies.
3846 + - shows all the sub headers, but not the bodies
3847 - - exposes the body of the corresponding topic.
3849 Examples:
3850 \(outline-expose-topic '(-1 : 0))
3851 Close this and all following topics at current level, exposing
3852 only their immediate children, but close down the last topic
3853 at this current level completely.
3854 \(outline-expose-topic '(-1 () : 1 0))
3855 Close current topic so only the immediate subtopics are shown;
3856 show the children in the second to last topic, and completely
3857 close the last one.
3858 \(outline-expose-topic '(-2 : -1 *))
3859 Expose children and grandchildren of all topics at current
3860 level except the last two; expose children of the second to
3861 last and completely open the last one."
3863 (interactive "xExposure spec: ")
3864 (if (not (listp spec))
3866 (let ((depth (outline-depth))
3867 (max-pos 0)
3868 prev-elem curr-elem
3869 stay done
3870 snug-back
3872 (while spec
3873 (setq prev-elem curr-elem
3874 curr-elem (car spec)
3875 spec (cdr spec))
3876 (cond ; Do current element:
3877 ((null curr-elem) nil)
3878 ((symbolp curr-elem)
3879 (cond ((eq curr-elem '*) (outline-show-current-subtree)
3880 (if (> outline-recent-end-of-subtree max-pos)
3881 (setq max-pos outline-recent-end-of-subtree)))
3882 ((eq curr-elem '+) (outline-show-current-branches)
3883 (if (> outline-recent-end-of-subtree max-pos)
3884 (setq max-pos outline-recent-end-of-subtree)))
3885 ((eq curr-elem '-) (outline-show-current-entry))
3886 ((eq curr-elem ':)
3887 (setq stay t)
3888 ;; Expand the `repeat' spec to an explicit version,
3889 ;; w.r.t. remaining siblings:
3890 (let ((residue ; = # of sibs not covered by remaining spec
3891 ;; Dang - could be nice to make use of the chart, sigh:
3892 (- (length (outline-chart-siblings))
3893 (length spec))))
3894 (if (< 0 residue)
3895 ;; Some residue - cover it with prev-elem:
3896 (setq spec (append (make-list residue prev-elem)
3897 spec)))))))
3898 ((numberp curr-elem)
3899 (if (and (>= 0 curr-elem) (outline-visible-p))
3900 (save-excursion (outline-hide-current-subtree t)
3901 (if (> 0 curr-elem)
3903 (if (> outline-recent-end-of-subtree max-pos)
3904 (setq max-pos
3905 outline-recent-end-of-subtree)))))
3906 (if (> (abs curr-elem) 0)
3907 (progn (outline-show-children (abs curr-elem))
3908 (if (> outline-recent-end-of-subtree max-pos)
3909 (setq max-pos outline-recent-end-of-subtree)))))
3910 ((listp curr-elem)
3911 (if (outline-descend-to-depth (1+ depth))
3912 (let ((got (outline-expose-topic curr-elem)))
3913 (if (and got (> got max-pos)) (setq max-pos got))))))
3914 (cond (stay (setq stay nil))
3915 ((listp (car spec)) nil)
3916 ((> max-pos (point))
3917 ;; Capitalize on max-pos state to get us nearer next sibling:
3918 (progn (goto-char (min (point-max) max-pos))
3919 (outline-next-heading)))
3920 ((outline-next-sibling depth))))
3921 max-pos)))
3922 ;;;_ > outline-old-expose-topic (spec &rest followers)
3923 (defun outline-old-expose-topic (spec &rest followers)
3925 "Deprecated. Use outline-expose-topic \(with different schema
3926 format) instead.
3928 Dictate wholesale exposure scheme for current topic, according to SPEC.
3930 SPEC is either a number or a list. Optional successive args
3931 dictate exposure for subsequent siblings of current topic.
3933 A simple spec (either a number, a special symbol, or the null list)
3934 dictates the overall exposure for a topic. Non null lists are
3935 composite specs whose first element dictates the overall exposure for
3936 a topic, with the subsequent elements in the list interpreted as specs
3937 that dictate the exposure for the successive offspring of the topic.
3939 Simple (numeric and null-list) specs are interpreted as follows:
3941 - Numbers indicate the relative depth to open the corresponding topic:
3942 - negative numbers force the topic to be close before opening to the
3943 absolute value of the number.
3944 - positive numbers just open to the relative depth indicated by the number.
3945 - 0 just closes
3946 - `*' completely opens the topic, including bodies.
3947 - `+' shows all the sub headers, but not the bodies
3948 - `-' exposes the body and immediate offspring of the corresponding topic.
3950 If the spec is a list, the first element must be a number, which
3951 dictates the exposure depth of the topic as a whole. Subsequent
3952 elements of the list are nested SPECs, dictating the specific exposure
3953 for the corresponding offspring of the topic.
3955 Optional FOLLOWER arguments dictate exposure for succeeding siblings."
3957 (interactive "xExposure spec: ")
3958 (let ((depth (outline-current-depth))
3959 done
3960 max-pos)
3961 (cond ((null spec) nil)
3962 ((symbolp spec)
3963 (if (eq spec '*) (outline-show-current-subtree))
3964 (if (eq spec '+) (outline-show-current-branches))
3965 (if (eq spec '-) (outline-show-current-entry)))
3966 ((numberp spec)
3967 (if (>= 0 spec)
3968 (save-excursion (outline-hide-current-subtree t)
3969 (end-of-line)
3970 (if (or (not max-pos)
3971 (> (point) max-pos))
3972 (setq max-pos (point)))
3973 (if (> 0 spec)
3974 (setq spec (* -1 spec)))))
3975 (if (> spec 0)
3976 (outline-show-children spec)))
3977 ((listp spec)
3978 ;(let ((got (outline-old-expose-topic (car spec))))
3979 ; (if (and got (or (not max-pos) (> got max-pos)))
3980 ; (setq max-pos got)))
3981 (let ((new-depth (+ (outline-current-depth) 1))
3982 got)
3983 (setq max-pos (outline-old-expose-topic (car spec)))
3984 (setq spec (cdr spec))
3985 (if (and spec
3986 (outline-descend-to-depth new-depth)
3987 (not (outline-hidden-p)))
3988 (progn (setq got (apply 'outline-old-expose-topic spec))
3989 (if (and got (or (not max-pos) (> got max-pos)))
3990 (setq max-pos got)))))))
3991 (while (and followers
3992 (progn (if (and max-pos (< (point) max-pos))
3993 (progn (goto-char max-pos)
3994 (setq max-pos nil)))
3995 (end-of-line)
3996 (outline-next-sibling depth)))
3997 (outline-old-expose-topic (car followers))
3998 (setq followers (cdr followers)))
3999 max-pos))
4000 ;;;_ > outline-new-exposure '()
4001 (defmacro outline-new-exposure (&rest spec)
4002 "Literal frontend for `outline-expose-topic', doesn't evaluate arguments.
4003 Some arguments that would need to be quoted in outline-expose-topic
4004 need not be quoted in outline-new-exposure.
4006 Cursor is left at start position.
4008 Use this instead of obsolete `outline-exposure'.
4010 Examples:
4011 \(outline-exposure (-1 () () () 1) 0)
4012 Close current topic at current level so only the immediate
4013 subtopics are shown, except also show the children of the
4014 third subtopic; and close the next topic at the current level.
4015 \(outline-exposure : -1 0)
4016 Close all topics at current level to expose only their
4017 immediate children, except for the last topic at the current
4018 level, in which even its immediate children are hidden.
4019 \(outline-exposure -2 : -1 *)
4020 Expose children and grandchildren of first topic at current
4021 level, and expose children of subsequent topics at current
4022 level *except* for the last, which should be opened completely."
4023 (list 'save-excursion
4024 '(if (not (or (outline-goto-prefix)
4025 (outline-next-heading)))
4026 (error "outline-new-exposure: Can't find any outline topics."))
4027 (list 'outline-expose-topic (list 'quote spec))))
4028 ;;;_ > outline-exposure '()
4029 (defmacro outline-exposure (&rest spec)
4030 "Being deprecated - use more recent `outline-new-exposure' instead.
4032 Literal frontend for `outline-old-expose-topic', doesn't evaluate arguments
4033 and retains start position."
4034 (list 'save-excursion
4035 '(if (not (or (outline-goto-prefix)
4036 (outline-next-heading)))
4037 (error "Can't find any outline topics."))
4038 (cons 'outline-old-expose-topic
4039 (mapcar (function (lambda (x) (list 'quote x))) spec))))
4041 ;;;_ #7 Systematic outline presentation - copying, printing, flattening
4043 ;;;_ - Mapping and processing of topics
4044 ;;;_ ( See also Subtree Charting, in Navigation code.)
4045 ;;;_ > outline-stringify-flat-index (flat-index)
4046 (defun outline-stringify-flat-index (flat-index &optional context)
4047 "Convert list representing section/subsection/... to document string.
4049 Optional arg CONTEXT indicates interior levels to include."
4050 (let ((delim ".")
4051 result
4052 numstr
4053 (context-depth (or (and context 2) 1)))
4054 ;; Take care of the explicit context:
4055 (while (> context-depth 0)
4056 (setq numstr (int-to-string (car flat-index))
4057 flat-index (cdr flat-index)
4058 result (if flat-index
4059 (cons delim (cons numstr result))
4060 (cons numstr result))
4061 context-depth (if flat-index (1- context-depth) 0)))
4062 (setq delim " ")
4063 ;; Take care of the indentation:
4064 (if flat-index
4065 (progn
4066 (while flat-index
4067 (setq result
4068 (cons delim
4069 (cons (make-string
4070 (1+ (truncate (if (zerop (car flat-index))
4072 (log10 (car flat-index)))))
4074 result)))
4075 (setq flat-index (cdr flat-index)))
4076 ;; Dispose of single extra delim:
4077 (setq result (cdr result))))
4078 (apply 'concat result)))
4079 ;;;_ > outline-stringify-flat-index-plain (flat-index)
4080 (defun outline-stringify-flat-index-plain (flat-index)
4081 "Convert list representing section/subsection/... to document string."
4082 (let ((delim ".")
4083 result)
4084 (while flat-index
4085 (setq result (cons (int-to-string (car flat-index))
4086 (if result
4087 (cons delim result))))
4088 (setq flat-index (cdr flat-index)))
4089 (apply 'concat result)))
4090 ;;;_ > outline-stringify-flat-index-indented (flat-index)
4091 (defun outline-stringify-flat-index-indented (flat-index)
4092 "Convert list representing section/subsection/... to document string."
4093 (let ((delim ".")
4094 result
4095 numstr)
4096 ;; Take care of the explicit context:
4097 (setq numstr (int-to-string (car flat-index))
4098 flat-index (cdr flat-index)
4099 result (if flat-index
4100 (cons delim (cons numstr result))
4101 (cons numstr result)))
4102 (setq delim " ")
4103 ;; Take care of the indentation:
4104 (if flat-index
4105 (progn
4106 (while flat-index
4107 (setq result
4108 (cons delim
4109 (cons (make-string
4110 (1+ (truncate (if (zerop (car flat-index))
4112 (log10 (car flat-index)))))
4114 result)))
4115 (setq flat-index (cdr flat-index)))
4116 ;; Dispose of single extra delim:
4117 (setq result (cdr result))))
4118 (apply 'concat result)))
4119 ;;;_ > outline-listify-exposed (&optional start end format)
4120 (defun outline-listify-exposed (&optional start end format)
4122 "Produce a list representing exposed topics in current region.
4124 This list can then be used by `outline-process-exposed' to manipulate
4125 the subject region.
4127 Optional START and END indicate bounds of region.
4129 optional arg, FORMAT, designates an alternate presentation form for
4130 the prefix:
4132 list - Present prefix as numeric section.subsection..., starting with
4133 section indicated by the list, innermost nesting first.
4134 `indent' \(symbol) - Convert header prefixes to all white space,
4135 except for distinctive bullets.
4137 The elements of the list produced are lists that represents a topic
4138 header and body. The elements of that list are:
4140 - a number representing the depth of the topic,
4141 - a string representing the header-prefix, including trailing whitespace and
4142 bullet.
4143 - a string representing the bullet character,
4144 - and a series of strings, each containing one line of the exposed
4145 portion of the topic entry."
4147 (interactive "r")
4148 (save-excursion
4149 (let*
4150 ;; state vars:
4151 (strings prefix pad result depth new-depth out gone-out bullet beg
4152 next done)
4154 (goto-char start)
4155 (beginning-of-line)
4156 ;; Goto initial topic, and register preceeding stuff, if any:
4157 (if (> (outline-goto-prefix) start)
4158 ;; First topic follows beginning point - register preliminary stuff:
4159 (setq result (list (list 0 "" nil
4160 (buffer-substring start (1- (point)))))))
4161 (while (and (not done)
4162 (not (eobp)) ; Loop until we've covered the region.
4163 (not (> (point) end)))
4164 (setq depth (outline-recent-depth) ; Current topics depth,
4165 bullet (outline-recent-bullet) ; ... bullet,
4166 prefix (outline-recent-prefix)
4167 beg (progn (outline-end-of-prefix t) (point))) ; and beginning.
4168 (setq done ; The boundary for the current topic:
4169 (not (outline-next-visible-heading 1)))
4170 (setq new-depth (outline-recent-depth))
4171 (setq gone-out out
4172 out (< new-depth depth))
4173 (beginning-of-line)
4174 (setq next (point))
4175 (goto-char beg)
4176 (setq strings nil)
4177 (while (> next (point)) ; Get all the exposed text in
4178 (setq strings
4179 (cons (buffer-substring
4181 ;To hidden text or end of line:
4182 (progn
4183 (search-forward "\r"
4184 (save-excursion (end-of-line)
4185 (point))
4187 (if (= (preceding-char) ?\r)
4188 (1- (point))
4189 (point))))
4190 strings))
4191 (if (< (point) next) ; Resume from after hid text, if any.
4192 (forward-line 1))
4193 (setq beg (point)))
4194 ;; Accumulate list for this topic:
4195 (setq strings (nreverse strings))
4196 (setq result
4197 (cons
4198 (if format
4199 (let ((special (if (string-match
4200 (regexp-quote bullet)
4201 outline-distinctive-bullets-string)
4202 bullet)))
4203 (cond ((listp format)
4204 (list depth
4205 (if outline-abbreviate-flattened-numbering
4206 (outline-stringify-flat-index format
4207 gone-out)
4208 (outline-stringify-flat-index-plain
4209 format))
4210 strings
4211 special))
4212 ((eq format 'indent)
4213 (if special
4214 (list depth
4215 (concat (make-string (1+ depth) ? )
4216 (substring prefix -1))
4217 strings)
4218 (list depth
4219 (make-string depth ? )
4220 strings)))
4221 (t (error "outline-listify-exposed: %s %s"
4222 "invalid format" format))))
4223 (list depth prefix strings))
4224 result))
4225 ;; Reasses format, if any:
4226 (if (and format (listp format))
4227 (cond ((= new-depth depth)
4228 (setq format (cons (1+ (car format))
4229 (cdr format))))
4230 ((> new-depth depth) ; descending - assume by 1:
4231 (setq format (cons 1 format)))
4233 ; Pop the residue:
4234 (while (< new-depth depth)
4235 (setq format (cdr format))
4236 (setq depth (1- depth)))
4237 ; And increment the current one:
4238 (setq format
4239 (cons (1+ (or (car format)
4240 -1))
4241 (cdr format)))))))
4242 ;; Put the list with first at front, to last at back:
4243 (nreverse result))))
4244 ;;;_ > outline-process-exposed (&optional func from to frombuf
4245 ;;; tobuf format)
4246 (defun outline-process-exposed (&optional func from to frombuf tobuf
4247 format &optional start-num)
4248 "Map function on exposed parts of current topic; results to another buffer.
4250 All args are options; default values itemized below.
4252 Apply FUNCTION to exposed portions FROM position TO position in buffer
4253 FROMBUF to buffer TOBUF. Sixth optional arg, FORMAT, designates an
4254 alternate presentation form:
4256 `flat' - Present prefix as numeric section.subsection..., starting with
4257 section indicated by the start-num, innermost nesting first.
4258 X`flat-indented' - Prefix is like `flat' for first topic at each
4259 X level, but subsequent topics have only leaf topic
4260 X number, padded with blanks to line up with first.
4261 `indent' \(symbol) - Convert header prefixes to all white space,
4262 except for distinctive bullets.
4264 Defaults:
4265 FUNCTION: `outline-insert-listified'
4266 FROM: region start, if region active, else start of buffer
4267 TO: region end, if region active, else end of buffer
4268 FROMBUF: current buffer
4269 TOBUF: buffer name derived: \"*current-buffer-name exposed*\"
4270 FORMAT: nil"
4272 ; Resolve arguments,
4273 ; defaulting if necessary:
4274 (if (not func) (setq func 'outline-insert-listified))
4275 (if (not (and from to))
4276 (if (my-region-active-p)
4277 (setq from (region-beginning) to (region-end))
4278 (setq from (point-min) to (point-max))))
4279 (if frombuf
4280 (if (not (bufferp frombuf))
4281 ;; Specified but not a buffer - get it:
4282 (let ((got (get-buffer frombuf)))
4283 (if (not got)
4284 (error (concat "outline-process-exposed: source buffer "
4285 frombuf
4286 " not found."))
4287 (setq frombuf got))))
4288 ;; not specified - default it:
4289 (setq frombuf (current-buffer)))
4290 (if tobuf
4291 (if (not (bufferp tobuf))
4292 (setq tobuf (get-buffer-create tobuf)))
4293 ;; not specified - default it:
4294 (setq tobuf (concat "*" (buffer-name frombuf) " exposed*")))
4295 (if (listp format)
4296 (nreverse format))
4298 (let* ((listified
4299 (progn (set-buffer frombuf)
4300 (outline-listify-exposed from to format))))
4301 (set-buffer tobuf)
4302 (mapcar func listified)
4303 (pop-to-buffer tobuf)))
4305 ;;;_ - Copy exposed
4306 ;;;_ > outline-insert-listified (listified)
4307 (defun outline-insert-listified (listified)
4308 "Insert contents of listified outline portion in current buffer.
4310 Listified is a list representing each topic header and body:
4312 \`(depth prefix text)'
4314 or \`(depth prefix text bullet-plus)'
4316 If `bullet-plus' is specified, it is inserted just after the entire prefix."
4317 (setq listified (cdr listified))
4318 (let ((prefix (prog1
4319 (car listified)
4320 (setq listified (cdr listified))))
4321 (text (prog1
4322 (car listified)
4323 (setq listified (cdr listified))))
4324 (bullet-plus (car listified)))
4325 (insert-string prefix)
4326 (if bullet-plus (insert-string (concat " " bullet-plus)))
4327 (while text
4328 (insert-string (car text))
4329 (if (setq text (cdr text))
4330 (insert-string "\n")))
4331 (insert-string "\n")))
4332 ;;;_ > outline-copy-exposed-to-buffer (&optional arg tobuf format)
4333 (defun outline-copy-exposed-to-buffer (&optional arg tobuf format)
4334 "Duplicate exposed portions of current outline to another buffer.
4336 Other buffer has current buffers name with \" exposed\" appended to it.
4338 With repeat count, copy the exposed parts of only the current topic.
4340 Optional second arg TOBUF is target buffer name.
4342 Optional third arg FORMAT, if non-nil, symbolically designates an
4343 alternate presentation format for the outline:
4345 `flat' - Convert topic header prefixes to numeric
4346 section.subsection... identifiers.
4347 `indent' - Convert header prefixes to all white space, except for
4348 distinctive bullets.
4349 `indent-flat' - The best of both - only the first of each level has
4350 the full path, the rest have only the section number
4351 of the leaf, preceded by the right amount of indentation."
4353 (interactive "P")
4354 (if (not tobuf)
4355 (setq tobuf (get-buffer-create (concat "*" (buffer-name) " exposed*"))))
4356 (let* ((start-pt (point))
4357 (beg (if arg (outline-back-to-current-heading) (point-min)))
4358 (end (if arg (outline-end-of-current-subtree) (point-max)))
4359 (buf (current-buffer))
4360 (start-list ()))
4361 (if (eq format 'flat)
4362 (setq format (if arg (save-excursion
4363 (goto-char beg)
4364 (outline-topic-flat-index))
4365 '(1))))
4366 (save-excursion (set-buffer tobuf)(erase-buffer))
4367 (outline-process-exposed 'outline-insert-listified
4370 (current-buffer)
4371 tobuf
4372 format start-list)
4373 (goto-char (point-min))
4374 (pop-to-buffer buf)
4375 (goto-char start-pt)))
4376 ;;;_ > outline-flatten-exposed-to-buffer (&optional arg tobuf)
4377 (defun outline-flatten-exposed-to-buffer (&optional arg tobuf)
4378 "Present numeric outline of outline's exposed portions in another buffer.
4380 The resulting outline is not compatable with outline mode - use
4381 `outline-copy-exposed-to-buffer' if you want that.
4383 Use `outline-indented-exposed-to-buffer' for indented presentation.
4385 With repeat count, copy the exposed portions of only current topic.
4387 Other buffer has current buffers name with \" exposed\" appended to
4388 it, unless optional second arg TOBUF is specified, in which case it is
4389 used verbatim."
4390 (interactive "P")
4391 (outline-copy-exposed-to-buffer arg tobuf 'flat))
4392 ;;;_ > outline-indented-exposed-to-buffer (&optional arg tobuf)
4393 (defun outline-indented-exposed-to-buffer (&optional arg tobuf)
4394 "Present indented outline of outline's exposed portions in another buffer.
4396 The resulting outline is not compatable with outline mode - use
4397 `outline-copy-exposed-to-buffer' if you want that.
4399 Use `outline-flatten-exposed-to-buffer' for numeric sectional presentation.
4401 With repeat count, copy the exposed portions of only current topic.
4403 Other buffer has current buffers name with \" exposed\" appended to
4404 it, unless optional second arg TOBUF is specified, in which case it is
4405 used verbatim."
4406 (interactive "P")
4407 (outline-copy-exposed-to-buffer arg tobuf 'indent))
4409 ;;;_ - LaTeX formatting
4410 ;;;_ > outline-latex-verb-quote (str &optional flow)
4411 (defun outline-latex-verb-quote (str &optional flow)
4412 "Return copy of STRING for literal reproduction across latex processing.
4413 Expresses the original characters \(including carriage returns) of the
4414 string across latex processing."
4415 (mapconcat (function
4416 (lambda (char)
4417 (cond ((memq char '(?\\ ?$ ?% ?# ?& ?{ ?} ?_ ?^ ?- ?*))
4418 (concat "\\char" (number-to-string char) "{}"))
4419 ((= char ?\n) "\\\\")
4420 (t (char-to-string char)))))
4422 ""))
4423 ;;;_ > outline-latex-verbatim-quote-curr-line ()
4424 (defun outline-latex-verbatim-quote-curr-line ()
4425 "Express line for exact \(literal) representation across latex processing.
4427 Adjust line contents so it is unaltered \(from the original line)
4428 across latex processing, within the context of a `verbatim'
4429 environment. Leaves point at the end of the line."
4430 (beginning-of-line)
4431 (let ((beg (point))
4432 (end (progn (end-of-line)(point))))
4433 (goto-char beg)
4434 (while (re-search-forward "\\\\"
4435 ;;"\\\\\\|\\{\\|\\}\\|\\_\\|\\$\\|\\\"\\|\\&\\|\\^\\|\\-\\|\\*\\|#"
4436 end ; bounded by end-of-line
4437 1) ; no matches, move to end & return nil
4438 (goto-char (match-beginning 0))
4439 (insert-string "\\")
4440 (setq end (1+ end))
4441 (goto-char (1+ (match-end 0))))))
4442 ;;;_ > outline-insert-latex-header (buf)
4443 (defun outline-insert-latex-header (buf)
4444 "Insert initial latex commands at point in BUFFER."
4445 ;; Much of this is being derived from the stuff in appendix of E in
4446 ;; the TeXBook, pg 421.
4447 (set-buffer buf)
4448 (let ((doc-style (format "\n\\documentstyle{%s}\n"
4449 "report"))
4450 (page-numbering (if outline-number-pages
4451 "\\pagestyle{empty}\n"
4452 ""))
4453 (linesdef (concat "\\def\\beginlines{"
4454 "\\par\\begingroup\\nobreak\\medskip"
4455 "\\parindent=0pt\n"
4456 " \\kern1pt\\nobreak \\obeylines \\obeyspaces "
4457 "\\everypar{\\strut}}\n"
4458 "\\def\\endlines{"
4459 "\\kern1pt\\endgroup\\medbreak\\noindent}\n"))
4460 (titlecmd (format "\\newcommand{\\titlecmd}[1]{{%s #1}}\n"
4461 outline-title-style))
4462 (labelcmd (format "\\newcommand{\\labelcmd}[1]{{%s #1}}\n"
4463 outline-label-style))
4464 (headlinecmd (format "\\newcommand{\\headlinecmd}[1]{{%s #1}}\n"
4465 outline-head-line-style))
4466 (bodylinecmd (format "\\newcommand{\\bodylinecmd}[1]{{%s #1}}\n"
4467 outline-body-line-style))
4468 (setlength (format "%s%s%s%s"
4469 "\\newlength{\\stepsize}\n"
4470 "\\setlength{\\stepsize}{"
4471 outline-indent
4472 "}\n"))
4473 (oneheadline (format "%s%s%s%s%s%s%s"
4474 "\\newcommand{\\OneHeadLine}[3]{%\n"
4475 "\\noindent%\n"
4476 "\\hspace*{#2\\stepsize}%\n"
4477 "\\labelcmd{#1}\\hspace*{.2cm}"
4478 "\\headlinecmd{#3}\\\\["
4479 outline-line-skip
4480 "]\n}\n"))
4481 (onebodyline (format "%s%s%s%s%s%s"
4482 "\\newcommand{\\OneBodyLine}[2]{%\n"
4483 "\\noindent%\n"
4484 "\\hspace*{#1\\stepsize}%\n"
4485 "\\bodylinecmd{#2}\\\\["
4486 outline-line-skip
4487 "]\n}\n"))
4488 (begindoc "\\begin{document}\n\\begin{center}\n")
4489 (title (format "%s%s%s%s"
4490 "\\titlecmd{"
4491 (outline-latex-verb-quote (if outline-title
4492 (condition-case err
4493 (eval outline-title)
4494 ('error "<unnamed buffer>"))
4495 "Unnamed Outline"))
4496 "}\n"
4497 "\\end{center}\n\n"))
4498 (hsize "\\hsize = 7.5 true in\n")
4499 (hoffset "\\hoffset = -1.5 true in\n")
4500 (vspace "\\vspace{.1cm}\n\n"))
4501 (insert (concat doc-style
4502 page-numbering
4503 titlecmd
4504 labelcmd
4505 headlinecmd
4506 bodylinecmd
4507 setlength
4508 oneheadline
4509 onebodyline
4510 begindoc
4511 title
4512 hsize
4513 hoffset
4514 vspace)
4516 ;;;_ > outline-insert-latex-trailer (buf)
4517 (defun outline-insert-latex-trailer (buf)
4518 "Insert concluding latex commands at point in BUFFER."
4519 (set-buffer buf)
4520 (insert "\n\\end{document}\n"))
4521 ;;;_ > outline-latexify-one-item (depth prefix bullet text)
4522 (defun outline-latexify-one-item (depth prefix bullet text)
4523 "Insert LaTeX commands for formatting one outline item.
4525 Args are the topics numeric DEPTH, the header PREFIX lead string, the
4526 BULLET string, and a list of TEXT strings for the body."
4527 (let* ((head-line (if text (car text)))
4528 (body-lines (cdr text))
4529 (curr-line)
4530 body-content bop)
4531 ; Do the head line:
4532 (insert-string (concat "\\OneHeadLine{\\verb\1 "
4533 (outline-latex-verb-quote bullet)
4534 "\1}{"
4535 depth
4536 "}{\\verb\1 "
4537 (if head-line
4538 (outline-latex-verb-quote head-line)
4540 "\1}\n"))
4541 (if (not body-lines)
4543 ;;(insert-string "\\beginlines\n")
4544 (insert-string "\\begin{verbatim}\n")
4545 (while body-lines
4546 (setq curr-line (car body-lines))
4547 (if (and (not body-content)
4548 (not (string-match "^\\s-*$" curr-line)))
4549 (setq body-content t))
4550 ; Mangle any occurrences of
4551 ; "\end{verbatim}" in text,
4552 ; it's special:
4553 (if (and body-content
4554 (setq bop (string-match "\\end{verbatim}" curr-line)))
4555 (setq curr-line (concat (substring curr-line 0 bop)
4557 (substring curr-line bop))))
4558 ;;(insert-string "|" (car body-lines) "|")
4559 (insert-string curr-line)
4560 (outline-latex-verbatim-quote-curr-line)
4561 (insert-string "\n")
4562 (setq body-lines (cdr body-lines)))
4563 (if body-content
4564 (setq body-content nil)
4565 (forward-char -1)
4566 (insert-string "\\ ")
4567 (forward-char 1))
4568 ;;(insert-string "\\endlines\n")
4569 (insert-string "\\end{verbatim}\n")
4571 ;;;_ > outline-latexify-exposed (arg &optional tobuf)
4572 (defun outline-latexify-exposed (arg &optional tobuf)
4573 "Format current topics exposed portions to TOBUF for latex processing.
4574 TOBUF defaults to a buffer named the same as the current buffer, but
4575 with \"*\" prepended and \" latex-formed*\" appended.
4577 With repeat count, copy the exposed portions of entire buffer."
4579 (interactive "P")
4580 (if (not tobuf)
4581 (setq tobuf
4582 (get-buffer-create (concat "*" (buffer-name) " latexified*"))))
4583 (let* ((start-pt (point))
4584 (beg (if arg (point-min) (outline-back-to-current-heading)))
4585 (end (if arg (point-max) (outline-end-of-current-subtree)))
4586 (buf (current-buffer)))
4587 (set-buffer tobuf)
4588 (erase-buffer)
4589 (outline-insert-latex-header tobuf)
4590 (goto-char (point-max))
4591 (outline-process-exposed 'outline-latexify-one-item
4595 tobuf)
4596 (goto-char (point-max))
4597 (outline-insert-latex-trailer tobuf)
4598 (goto-char (point-min))
4599 (pop-to-buffer buf)
4600 (goto-char start-pt)))
4602 ;;;_ #8 miscellaneous
4603 ;;;_ > outline-mark-topic ()
4604 (defun outline-mark-topic ()
4605 "Put the region around topic currently containing point."
4606 (interactive)
4607 (beginning-of-line)
4608 (outline-goto-prefix)
4609 (push-mark (point))
4610 (outline-end-of-current-subtree)
4611 (exchange-point-and-mark))
4612 ;;;_ > outlineify-sticky ()
4613 ;; outlinify-sticky is correct spelling; provide this alias for sticklers:
4614 (defalias 'outlinify-sticky 'outlineify-sticky)
4615 (defun outlineify-sticky (&optional arg)
4616 "Activate outline mode and establish file var so it is started subsequently.
4618 See doc-string for `outline-layout' and `outline-init' for details on
4619 setup for auto-startup."
4621 (interactive "P")
4623 (outline-mode t)
4625 (save-excursion
4626 (goto-char (point-min))
4627 (if (looking-at outline-regexp)
4629 (outline-open-topic 2)
4630 (insert-string (concat "Dummy outline topic header - see"
4631 "`outline-mode' docstring: `^Hm'."))
4632 (forward-line 1)
4633 (goto-char (point-max))
4634 (open-line 1)
4635 (outline-open-topic 0)
4636 (insert-string "Local emacs vars.\n")
4637 (outline-open-topic 1)
4638 (insert-string "(`outline-layout' is for allout.el outline-mode)\n")
4639 (outline-open-topic 0)
4640 (insert-string "Local variables:\n")
4641 (outline-open-topic 0)
4642 (insert-string (format "outline-layout: %s\n"
4643 (or outline-layout
4644 '(-1 : 0))))
4645 (outline-open-topic 0)
4646 (insert-string "End:\n"))))
4647 ;;;_ > solicit-char-in-string (prompt string &optional do-defaulting)
4648 (defun solicit-char-in-string (prompt string &optional do-defaulting)
4649 "Solicit (with first arg PROMPT) choice of a character from string STRING.
4651 Optional arg DO-DEFAULTING indicates to accept empty input (CR)."
4653 (let ((new-prompt prompt)
4654 got)
4656 (while (not got)
4657 (message "%s" new-prompt)
4659 ;; We do our own reading here, so we can circumvent, eg, special
4660 ;; treatment for `?' character. (Oughta use minibuffer keymap instead.)
4661 (setq got
4662 (char-to-string (let ((cursor-in-echo-area nil)) (read-char))))
4664 (setq got
4665 (cond ((string-match (regexp-quote got) string) got)
4666 ((and do-defaulting (string= got "\r"))
4667 ;; Return empty string to default:
4669 ((string= got "\C-g") (signal 'quit nil))
4671 (setq new-prompt (concat prompt
4673 " ...pick from: "
4674 string
4675 ""))
4676 nil))))
4677 ;; got something out of loop - return it:
4678 got)
4680 ;;;_ > regexp-sans-escapes (string)
4681 (defun regexp-sans-escapes (regexp &optional successive-backslashes)
4682 "Return a copy of REGEXP with all character escapes stripped out.
4684 Representations of actual backslashes - '\\\\\\\\' - are left as a
4685 single backslash.
4687 Optional arg SUCCESSIVE-BACKSLASHES is used internally for recursion."
4689 (if (string= regexp "")
4691 ;; Set successive-backslashes to number if current char is
4692 ;; backslash, or else to nil:
4693 (setq successive-backslashes
4694 (if (= (aref regexp 0) ?\\)
4695 (if successive-backslashes (1+ successive-backslashes) 1)
4696 nil))
4697 (if (or (not successive-backslashes) (= 2 successive-backslashes))
4698 ;; Include first char:
4699 (concat (substring regexp 0 1)
4700 (regexp-sans-escapes (substring regexp 1)))
4701 ;; Exclude first char, but maintain count:
4702 (regexp-sans-escapes (substring regexp 1) successive-backslashes))))
4703 ;;;_ > my-region-active-p ()
4704 (defmacro my-region-active-p ()
4705 (if (fboundp 'region-active-p)
4706 '(region-active-p)
4707 'mark-active))
4708 ;;;_ - add-hook definition for divergent emacsen
4709 ;;;_ > add-hook (hook function &optional append)
4710 (if (not (fboundp 'add-hook))
4711 (defun add-hook (hook function &optional append)
4712 "Add to the value of HOOK the function FUNCTION unless already present.
4713 \(It becomes the first hook on the list unless optional APPEND is non-nil, in
4714 which case it becomes the last). HOOK should be a symbol, and FUNCTION may be
4715 any valid function. HOOK's value should be a list of functions, not a single
4716 function. If HOOK is void, it is first set to nil."
4717 (or (boundp hook) (set hook nil))
4718 (or (if (consp function)
4719 ;; Clever way to tell whether a given lambda-expression
4720 ;; is equal to anything in the hook.
4721 (let ((tail (assoc (cdr function) (symbol-value hook))))
4722 (equal function tail))
4723 (memq function (symbol-value hook)))
4724 (set hook
4725 (if append
4726 (nconc (symbol-value hook) (list function))
4727 (cons function (symbol-value hook)))))))
4728 ;;;_ : my-mark-marker to accomodate divergent emacsen:
4729 (defun my-mark-marker (&optional force buffer)
4730 "Accomodate the different signature for mark-marker across emacsen.
4732 GNU XEmacs takes two optional args, while mainline GNU Emacs does not,
4733 so pass them along when appropriate."
4734 (if (string-match " XEmacs " emacs-version)
4735 (mark-marker force buffer)
4736 (mark-marker)))
4738 ;;;_ #9 Under development
4739 ;;;_ > outline-bullet-isearch (&optional bullet)
4740 (defun outline-bullet-isearch (&optional bullet)
4741 "Isearch \(regexp) for topic with bullet BULLET."
4742 (interactive)
4743 (if (not bullet)
4744 (setq bullet (solicit-char-in-string
4745 "ISearch for topic with bullet: "
4746 (regexp-sans-escapes outline-bullets-string))))
4748 (let ((isearch-regexp t)
4749 (isearch-string (concat "^"
4750 outline-header-prefix
4751 "[ \t]*"
4752 bullet)))
4753 (isearch-repeat 'forward)
4754 (isearch-mode t)))
4755 ;;;_ ? Re hooking up with isearch - use isearch-op-fun rather than
4756 ;;; wrapping the isearch functions.
4758 ;;;_* Local emacs vars.
4759 ;;; The following `outline-layout' local variable setting:
4760 ;;; - closes all topics from the first topic to just before the third-to-last,
4761 ;;; - shows the children of the third to last (config vars)
4762 ;;; - and the second to last (code section),
4763 ;;; - and closes the last topic (this local-variables section).
4764 ;;;Local variables:
4765 ;;;outline-layout: (0 : -1 -1 0)
4766 ;;;End:
4768 ;; allout.el ends here