| blob | 805b3cc288c909a2336c496857f818a277802a35 |
1 ;;; allout.el --- extensive outline mode for use alone and with other modes
3 ;; Copyright (C) 1992, 1993, 1994, 2001, 2002, 2003, 2004,
4 ;; 2005 Free Software Foundation, Inc.
6 ;; Author: Ken Manheimer <ken dot manheimer at gmail dot com>
7 ;; Maintainer: Ken Manheimer <ken dot manheimer at gmail dot com>
8 ;; Created: Dec 1991 - first release to usenet
9 ;; Version: 2.1
10 ;; Keywords: outlines wp languages
12 ;; This file is part of GNU Emacs.
14 ;; GNU Emacs is free software; you can redistribute it and/or modify
15 ;; it under the terms of the GNU General Public License as published by
16 ;; the Free Software Foundation; either version 2, or (at your option)
17 ;; any later version.
19 ;; GNU Emacs is distributed in the hope that it will be useful,
20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 ;; GNU General Public License for more details.
24 ;; You should have received a copy of the GNU General Public License
25 ;; along with GNU Emacs; see the file COPYING. If not, write to the
26 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
27 ;; Boston, MA 02110-1301, USA.
29 ;;; Commentary:
31 ;; Allout outline mode provides extensive outline formatting and
32 ;; and manipulation beyond standard emacs outline mode. It provides
33 ;; for structured editing of outlines, as well as navigation and
34 ;; exposure. It also provides for syntax-sensitive text like
35 ;; programming languages. (For an example, see the allout code
36 ;; itself, which is organized in ;; an outline framework.)
37 ;;
38 ;; Some features:
39 ;;
40 ;; - classic outline-mode topic-oriented navigation and exposure adjustment
41 ;; - topic-oriented editing including coherent topic and subtopic
42 ;; creation, promotion, demotion, cut/paste across depths, etc
43 ;; - incremental search with dynamic exposure and reconcealment of text
44 ;; - customizable bullet format enbles programming-language specific
45 ;; outlining, for ultimate code-folding editing. (allout code itself is
46 ;; formatted as an outline - do ESC-x eval-current-buffer in allout.el
47 ;; to try it out.)
48 ;; - configurable per-file initial exposure settings
49 ;; - symmetric-key and key-pair topic encryption, plus symmetric passphrase
50 ;; mnemonic support, with verification against an established passphrase
51 ;; (using a stashed encrypted dummy string) and user-supplied hint
52 ;; maintenance. (see allout-toggle-current-subtree-encryption docstring.)
53 ;; - automatic topic-number maintenance
54 ;; - "hot-spot" operation, for single-keystroke maneuvering and
55 ;; exposure control (see the allout-mode docstring)
56 ;; - easy rendering of exposed portions into numbered, latex, indented, etc
57 ;; outline styles
58 ;;
59 ;; and more.
60 ;;
61 ;; The outline menubar additions provide quick reference to many of
62 ;; the features, and see the docstring of the variable `allout-init'
63 ;; for instructions on priming your emacs session for automatic
64 ;; activation of allout-mode.
65 ;;
66 ;; See the docstring of the variables `allout-layout' and
67 ;; `allout-auto-activation' for details on automatic activation of
68 ;; `allout-mode' as a minor mode. (It has changed since allout
69 ;; 3.x, for those of you that depend on the old method.)
70 ;;
71 ;; Note - the lines beginning with `;;;_' are outline topic headers.
72 ;; Just `ESC-x eval-current-buffer' to give it a whirl.
74 ;; ken manheimer (ken dot manheimer at gmail dot com)
76 ;;; Code:
78 ;;;_* Provide
79 ;(provide 'outline)
82 ;;;_* Dependency autoloads
89 ;;;_* USER CUSTOMIZATION VARIABLES:
91 "Extensive outline mode for use alone and with other modes."
95 ;;;_ + Layout, Mode, and Topic Header Configuration
97 ;;;_ = allout-auto-activation
99 "*Regulates auto-activation modality of allout outlines - see `allout-init'.
101 Setq-default by `allout-init' to regulate whether or not allout
102 outline mode is automatically activated when the buffer-specific
103 variable `allout-layout' is non-nil, and whether or not the layout
104 dictated by `allout-layout' should be imposed on mode activation.
106 With value t, auto-mode-activation and auto-layout are enabled.
107 \(This also depends on `allout-find-file-hook' being installed in
108 `find-file-hook', which is also done by `allout-init'.)
110 With value `ask', auto-mode-activation is enabled, and endorsement for
111 performing auto-layout is asked of the user each time.
113 With value `activate', only auto-mode-activation is enabled,
114 auto-layout is not.
116 With value nil, neither auto-mode-activation nor auto-layout are
117 enabled.
119 See the docstring for `allout-init' for the proper interface to
120 this variable."
126 ;;;_ = allout-layout
128 "*Layout specification and provisional mode trigger for allout outlines.
130 Buffer-specific.
132 A list value specifies a default layout for the current buffer, to be
133 applied upon activation of `allout-mode'. Any non-nil value will
134 automatically trigger `allout-mode' \(provided `allout-init' has been called
135 to enable this behavior).
137 See the docstring for `allout-init' for details on setting up for
138 auto-mode-activation, and for `allout-expose-topic' for the format of
139 the layout specification.
141 You can associate a particular outline layout with a file by setting
142 this var via the file's local variables. For example, the following
143 lines at the bottom of an Emacs Lisp file:
145 ;;;Local variables:
146 ;;;allout-layout: \(0 : -1 -1 0)
147 ;;;End:
149 will, modulo the above-mentioned conditions, cause the mode to be
150 activated when the file is visited, followed by the equivalent of
151 `\(allout-expose-topic 0 : -1 -1 0)'. \(This is the layout used for
152 the allout.el, itself.)
154 Also, allout's mode-specific provisions will make topic prefixes default
155 to the comment-start string, if any, of the language of the file. This
158 ;;;_ = allout-show-bodies
160 "*If non-nil, show entire body when exposing a topic, rather than
161 just the header."
166 ;;;_ = allout-header-prefix
168 "*Leading string which helps distinguish topic headers.
170 Outline topic header lines are identified by a leading topic
171 header prefix, which mostly have the value of this var at their front.
172 \(Level 1 topics are exceptions. They consist of only a single
173 character, which is typically set to the `allout-primary-bullet'. Many
174 outlines start at level 2 to avoid this discrepancy."
178 ;;;_ = allout-primary-bullet
180 "Bullet used for top-level outline topics.
182 Outline topic header lines are identified by a leading topic header
183 prefix, which is concluded by bullets that includes the value of this
184 var and the respective allout-*-bullets-string vars.
186 The value of an asterisk (`*') provides for backwards compatibility
187 with the original Emacs outline mode. See `allout-plain-bullets-string'
188 and `allout-distinctive-bullets-string' for the range of available
189 bullets."
193 ;;;_ = allout-plain-bullets-string
195 "*The bullets normally used in outline topic prefixes.
197 See `allout-distinctive-bullets-string' for the other kind of
198 bullets.
200 DO NOT include the close-square-bracket, `]', as a bullet.
202 Outline mode has to be reactivated in order for changes to the value
203 of this var to take effect."
207 ;;;_ = allout-distinctive-bullets-string
209 "*Persistent outline header bullets used to distinguish special topics.
211 These bullets are used to distinguish topics from the run-of-the-mill
212 ones. They are not used in the standard topic headers created by
213 the topic-opening, shifting, and rebulleting \(eg, on topic shift,
214 topic paste, blanket rebulleting) routines, but are offered among the
215 choices for rebulleting. They are not altered by the above automatic
216 rebulleting, so they can be used to characterize topics, eg:
218 `?' question topics
219 `\(' parenthetic comment \(with a matching close paren inside)
220 `[' meta-note \(with a matching close ] inside)
222 `=' value settings
224 `^' see above
226 ... for example. (`#' typically has a special meaning to the software,
227 according to the value of `allout-numbered-bullet'.)
229 See `allout-plain-bullets-string' for the selection of
230 alternating bullets.
232 You must run `set-allout-regexp' in order for outline mode to
233 reconcile to changes of this value.
235 DO NOT include the close-square-bracket, `]', on either of the bullet
236 strings."
241 ;;;_ = allout-use-mode-specific-leader
243 "*When non-nil, use mode-specific topic-header prefixes.
245 Allout outline mode will use the mode-specific `allout-mode-leaders'
246 and/or comment-start string, if any, to lead the topic prefix string,
247 so topic headers look like comments in the programming language.
249 String values are used as they stand.
251 Value t means to first check for assoc value in `allout-mode-leaders'
252 alist, then use comment-start string, if any, then use default \(`.').
253 \(See note about use of comment-start strings, below.)
255 Set to the symbol for either of `allout-mode-leaders' or
256 `comment-start' to use only one of them, respectively.
258 Value nil means to always use the default \(`.').
260 comment-start strings that do not end in spaces are tripled, and an
261 `_' underscore is tacked on the end, to distinguish them from regular
262 comment strings. comment-start strings that do end in spaces are not
263 tripled, but an underscore is substituted for the space. [This
264 presumes that the space is for appearance, not comment syntax. You
265 can use `allout-mode-leaders' to override this behavior, when
266 incorrect.]"
271 ;;;_ = allout-mode-leaders
273 "Specific allout-prefix leading strings per major modes.
275 Entries will be used instead or in lieu of mode-specific
276 comment-start strings. See also `allout-use-mode-specific-leader'.
278 If you're constructing a string that will comment-out outline
279 structuring so it can be included in program code, append an extra
283 ;;;_ = allout-old-style-prefixes
285 "*When non-nil, use only old-and-crusty `outline-mode' `*' topic prefixes.
287 Non-nil restricts the topic creation and modification
288 functions to asterix-padded prefixes, so they look exactly
289 like the original Emacs-outline style prefixes.
291 Whatever the setting of this variable, both old and new style prefixes
292 are always respected by the topic maneuvering functions."
296 ;;;_ = allout-stylish-prefixes - alternating bullets
298 "*Do fancy stuff with topic prefix bullets according to level, etc.
300 Non-nil enables topic creation, modification, and repositioning
301 functions to vary the topic bullet char (the char that marks the topic
302 depth) just preceding the start of the topic text) according to level.
303 Otherwise, only asterisks (`*') and distinctive bullets are used.
305 This is how an outline can look (but sans indentation) with stylish
306 prefixes:
308 * Top level
309 .* A topic
310 . + One level 3 subtopic
311 . . One level 4 subtopic
312 . . A second 4 subtopic
313 . + Another level 3 subtopic
314 . #1 A numbered level 4 subtopic
315 . #2 Another
316 . ! Another level 4 subtopic with a different distinctive bullet
317 . #4 And another numbered level 4 subtopic
319 This would be an outline with stylish prefixes inhibited (but the
320 numbered and other distinctive bullets retained):
322 * Top level
323 .* A topic
324 . * One level 3 subtopic
325 . * One level 4 subtopic
326 . * A second 4 subtopic
327 . * Another level 3 subtopic
328 . #1 A numbered level 4 subtopic
329 . #2 Another
330 . ! Another level 4 subtopic with a different distinctive bullet
331 . #4 And another numbered level 4 subtopic
333 Stylish and constant prefixes (as well as old-style prefixes) are
334 always respected by the topic maneuvering functions, regardless of
335 this variable setting.
337 The setting of this var is not relevant when `allout-old-style-prefixes'
338 is non-nil."
343 ;;;_ = allout-numbered-bullet
345 "*String designating bullet of topics that have auto-numbering; nil for none.
347 Topics having this bullet have automatic maintenance of a sibling
348 sequence-number tacked on, just after the bullet. Conventionally set
350 disables numbering maintenance."
354 ;;;_ = allout-file-xref-bullet
356 "*Bullet signifying file cross-references, for `allout-resolve-xref'.
358 Set this var to the bullet you want to use for file cross-references."
361 ;;;_ = allout-presentation-padding
363 "*Presentation-format white-space padding factor, for greater indent."
369 ;;;_ = allout-abbreviate-flattened-numbering
371 "*If non-nil, `allout-flatten-exposed-to-buffer' abbreviates topic
372 numbers to minimal amount with some context. Otherwise, entire
373 numbers are always used."
377 ;;;_ + LaTeX formatting
378 ;;;_ - allout-number-pages
380 "*Non-nil turns on page numbering for LaTeX formatting of an outline."
383 ;;;_ - allout-label-style
385 "*Font and size of labels for LaTeX formatting of an outline."
388 ;;;_ - allout-head-line-style
390 "*Font and size of entries for LaTeX formatting of an outline."
393 ;;;_ - allout-body-line-style
395 "*Font and size of entries for LaTeX formatting of an outline."
398 ;;;_ - allout-title-style
400 "*Font and size of titles for LaTeX formatting of an outline."
403 ;;;_ - allout-title
405 "*Expression to be evaluated to determine the title for LaTeX
406 formatted copy."
409 ;;;_ - allout-line-skip
411 "*Space between lines for LaTeX formatting of an outline."
414 ;;;_ - allout-indent
416 "*LaTeX formatted depth-indent spacing."
420 ;;;_ + Topic encryption
421 ;;;_ = allout-topic-encryption-bullet
423 "*Bullet signifying encryption of the entry's body."
426 ;;;_ = allout-passphrase-verifier-handling
428 "*Enable use of symmetric encryption passphrase verifier if non-nil.
430 See the docstring for the `allout-enable-file-variable-adjustment'
431 variable for details about allout ajustment of file variables."
435 ;;;_ = allout-passphrase-hint-handling
437 "*Dictate outline encryption passphrase reminder handling:
439 always - always show reminder when prompting
440 needed - show reminder on passphrase entry failure
441 disabled - never present or adjust reminder
443 See the docstring for the `allout-enable-file-variable-adjustment'
444 variable for details about allout ajustment of file variables."
450 ;;;_ = allout-encrypt-unencrypted-on-saves
452 "*When saving, should topics pending encryption be encrypted?
454 The idea is to prevent file-system exposure of any un-encrypted stuff, and
455 mostly covers both deliberate file writes and auto-saves.
457 - Yes: encrypt all topics pending encryption, even if it's the one
458 currently being edited. \(In that case, the currently edited topic
459 will be automatically decrypted before any user interaction, so they
460 can continue editing but the copy on the file system will be
461 encrypted.)
463 one is selected, to avoid practical difficulties - see below.
464 - All except current topic: skip the topic currently being edited, even if
465 it's pending encryption. This may expose the current topic on the
466 file sytem, but avoids the nuisance of prompts for the encryption
467 passphrase in the middle of editing for, eg, autosaves.
469 - No: leave it to the user to encrypt any unencrypted topics.
471 For practical reasons, auto-saves always use the 'except-current policy
472 when auto-encryption is enabled. \(Otherwise, spurious passphrase prompts
473 and unavoidable timing collisions are too disruptive.) If security for a
474 file requires that even the current topic is never auto-saved in the clear,
475 disable auto-saves for that file."
483 ;;;_ + Miscellaneous customization
485 ;;;_ = allout-command-prefix
487 "*Key sequence to be used as prefix for outline mode command key bindings."
491 ;;;_ = allout-keybindings-list
492 ;;; You have to reactivate allout-mode - `(allout-mode t)' - to
493 ;;; institute changes to this var.
495 "*List of `allout-mode' key / function bindings, for `allout-mode-map'.
497 String or vector key will be prefaced with `allout-command-prefix',
500 '(
501 ; Motion commands:
509 ; Exposure commands:
517 ; Alteration commands:
531 ; Miscellaneous commands:
532 ;([?\C-\ ] allout-mark-topic)
539 ;;;_ = allout-isearch-dynamic-expose
541 "*Non-nil enable dynamic exposure of hidden incremental-search
542 targets as they're encountered."
547 ;;;_ = allout-use-hanging-indents
549 "*If non-nil, topic body text auto-indent defaults to indent of the header.
550 Ie, it is indented to be just past the header prefix. This is
551 relevant mostly for use with indented-text-mode, or other situations
552 where auto-fill occurs.
554 \[This feature no longer depends in any way on the `filladapt.el'
555 lisp-archive package.\]"
560 ;;;_ = allout-reindent-bodies
563 "*Non-nil enables auto-adjust of topic body hanging indent with depth shifts.
565 When active, topic body lines that are indented even with or beyond
566 their topic header are reindented to correspond with depth shifts of
567 the header.
569 A value of t enables reindent in non-programming-code buffers, ie
570 those that do not have the variable `comment-start' set. A value of
571 `force' enables reindent whether or not `comment-start' is set."
577 ;;;_ = allout-enable-file-variable-adjustment
579 "*If non-nil, some allout outline actions edit Emacs local file var text.
581 This can range from changes to existing entries, addition of new ones,
582 and creation of a new local variables section when necessary.
584 Emacs file variables adjustments are also inhibited if `enable-local-variables'
585 is nil.
587 Operations potentially causing edits include allout encryption routines.
588 See the docstring for `allout-toggle-current-subtree-encryption' for
589 details."
594 ;;;_* CODE - no user customizations below.
596 ;;;_ #1 Internal Outline Formatting and Configuration
597 ;;;_ : Version
598 ;;;_ = allout-version
601 ;;;_ > allout-version
603 "Return string describing the loaded outline version."
608 msg))
609 ;;;_ : Topic header format
610 ;;;_ = allout-regexp
612 "*Regular expression to match the beginning of a heading line.
614 Any line whose beginning matches this regexp is considered a
615 heading. This var is set according to the user configuration vars
618 ;;;_ = allout-bullets-string
620 "A string dictating the valid set of outline topic bullets.
622 This var should *not* be set by the user - it is set by `set-allout-regexp',
623 and is produced from the elements of `allout-plain-bullets-string'
626 ;;;_ = allout-bullets-string-len
630 ;;;_ = allout-line-boundary-regexp
632 "`allout-regexp' with outline style beginning-of-line anchor.
634 \(Ie, C-j, *or* C-m, for prefixes of hidden topics). This is properly
635 set when `allout-regexp' is produced by `set-allout-regexp', so
638 ;;;_ = allout-bob-regexp
640 "Like `allout-line-boundary-regexp', for headers at beginning of buffer.
643 ;;;_ = allout-header-subtraction
647 ;;;_ = allout-plain-bullets-string-len
653 ;;;_ X allout-reset-header-lead (header-lead)
655 "*Reset the leading string used to identify topic headers."
660 ;;;_ X allout-lead-with-comment-string (header-lead)
662 "*Set the topic-header leading string to specified string.
664 Useful when for encapsulating outline structure in programming
665 language comments. Returns the leading string."
673 header-lead)
674 ;;;_ > allout-infer-header-lead ()
676 "Determine appropriate `allout-header-prefix'.
678 Works according to settings of:
680 `comment-start'
681 `allout-header-prefix' (default)
682 `allout-use-mode-specific-leader'
683 and `allout-mode-leaders'.
685 Apply this via \(re)activation of `allout-mode', rather than
686 invoking it directly."
691 comment-start
692 t)))
693 allout-use-mode-specific-leader
694 ;; Oops - garbled value, equate with effect of 't:
695 t)))
699 ;; Use the explicitly designated leader:
702 ;; Get it from outline mode leaders?
704 ;; ... didn't get from allout-mode-leaders...
706 comment-start
707 ;; Use comment-start, maybe tripled, and with
708 ;; underscore:
713 ;; Use comment-start, sans trailing space:
716 ;; ... and append underscore, whichever:
719 nil
721 nil ; no change, nothing to do.
723 allout-header-prefix))))
724 ;;;_ > allout-infer-body-reindent ()
726 "Determine proper setting for `allout-reindent-bodies'.
728 Depends on default setting of `allout-reindent-bodies' \(which see)
729 and presence of setting for `comment-start', to tell whether the
730 file is programming code."
732 comment-start
735 ;;;_ > set-allout-regexp ()
737 "Generate proper topic-header regexp form for outline functions.
739 Works with respect to `allout-plain-bullets-string' and
740 `allout-distinctive-bullets-string'."
743 ;; Derive allout-bullets-string from user configured components:
746 'allout-distinctive-bullets-string
748 cur-string
749 cur-len
750 cur-char
751 cur-char-string
752 index
753 new-string)
762 ; Single dash would denote a
763 ; sequence, repeated denotes
764 ; a dash:
766 ; literal close-square-bracket
767 ; doesn't work right in the
768 ; expr, exclude it:
773 )
774 ;; Derive next for repeated use in allout-pending-bullet:
777 ;; Produce the new allout-regexp:
779 allout-header-prefix
781 allout-bullets-string
783 allout-primary-bullet
789 )
790 ;;;_ : Key bindings
791 ;;;_ = allout-mode-map
793 ;;;_ > produce-allout-mode-map (keymap-alist &optional base-map)
795 "Produce keymap for use as allout-mode-map, from KEYMAP-LIST.
797 Built on top of optional BASE-MAP, or empty sparse map if none specified.
798 See doc string for allout-keybindings-list for format of binding list."
809 key-suff))
811 keymap-list)
812 map))
813 ;;;_ = allout-prior-bindings - being deprecated.
815 "Variable for use in V18, with allout-added-bindings, for
816 resurrecting, on mode deactivation, bindings that existed before
818 ;;;_ = allout-added-bindings - being deprecated
820 "Variable for use in V18, with allout-prior-bindings, for
821 resurrecting, on mode deactivation, bindings that existed before
823 ;;;_ : Menu bar
831 allout-mode-map
832 "Allout outline exposure menu."
839 "----"
842 allout-mode-map
843 "Allout outline editing menu."
848 "----"
854 "----"
856 allout-toggle-current-subtree-encryption
859 allout-mode-map
860 "Allout outline navigation menu."
864 allout-previous-visible-heading t]
865 "----"
869 allout-backward-current-level t]
870 "----"
872 allout-beginning-of-current-entry t]
876 allout-mode-map
877 "Allout outlines miscellaneous bindings."
880 "----"
883 allout-flatten-exposed-to-buffer t]
885 allout-indented-exposed-to-buffer t]
886 "----"
889 ;;;_ : Mode-Specific Variable Maintenance Utilities
890 ;;;_ = allout-mode-prior-settings
894 ;;;_ > allout-resumptions (name &optional value)
897 "Registers or resumes settings over `allout-mode' activation/deactivation.
899 First arg is NAME of variable affected. Optional second arg is list
900 containing allout-mode-specific VALUE to be imposed on named
901 variable, and to be registered. (It's a list so you can specify
902 registrations of null values.) If no value is specified, the
903 registered value is returned (encapsulated in the list, so the caller
904 can distinguish nil vs no value), and the registration is popped
905 from the list."
908 prior-capsule ; By `capsule' i mean a list
909 ; containing a value, so we can
910 ; distinguish nil from no value.
911 )
915 ;; Registering:
918 nil ; Already preserved prior value - don't mess with it.
919 ;; Register the old value, or nil if previously unbound:
923 allout-mode-prior-settings)))
924 ; And impose the new value, locally:
928 ;; Relinquishing:
931 ;; Oops, not registered - leave it be:
932 nil
934 ;; Some registration:
935 ; reestablish it:
940 ; Remove registration:
944 on-list))
947 rebuild)))
951 )
952 ;;;_ : Mode-specific incidentals
953 ;;;_ = allout-pre-was-isearching nil
955 "Cue for isearch-dynamic-exposure mechanism, implemented in
958 ;;;_ = allout-isearch-prior-pos nil
960 "Cue for isearch-dynamic-exposure tracking, used by
963 ;;;_ = allout-isearch-did-quit
965 "Distinguishes isearch conclusion and cancellation.
967 Maintained by allout-isearch-abort \(which is wrapped around the real
970 ;;;_ > allout-unprotected (expr)
972 "Enable internal outline operations to alter read-only text."
979 )
980 )
981 )
982 ;;;_ = allout-undo-aggregation
984 "Amount of successive self-insert actions to bunch together per undo.
986 This is purely a kludge variable, regulating the compensation for a bug in
989 ;;;_ = file-var-bug hack
991 "Horrible hack used to prevent invalid multiple triggering of outline
992 mode from prop-line file-var activation. Used by `allout-mode' function
994 ;;;_ = allout-file-passphrase-verifier-string
996 "Name for use as a file variable for verifying encryption passphrase
999 ;;;_ = allout-passphrase-verifier-string
1001 "Setting used to test solicited encryption passphrases against the one
1002 already associated with a file.
1004 It consists of an encrypted random string useful only to verify that a
1005 passphrase entered by the user is effective for decryption. The passphrase
1006 itself is \*not* recorded in the file anywhere, and the encrypted contents
1007 are random binary characters to avoid exposing greater susceptibility to
1008 search attacks.
1010 The verifier string is retained as an Emacs file variable, as well as in
1011 the emacs buffer state, if file variable adjustments are enabled. See
1014 ;;;_ = allout-passphrase-hint-string
1016 "Variable used to retain reminder string for file's encryption passphrase.
1018 See the description of `allout-passphrase-hint-handling' for details about how
1019 the reminder is deployed.
1021 The hint is retained as an Emacs file variable, as well as in the emacs buffer
1022 state, if file variable adjustments are enabled. See
1026 ;;;_ = allout-after-save-decrypt
1028 "Internal variable, is nil or has the value of two points:
1030 - the location of a topic to be decrypted after saving is done
1031 - where to situate the cursor after the decryption is performed
1033 This is used to decrypt the topic that was currently being edited, if it
1036 ;;;_ > allout-write-file-hook-handler ()
1038 "Implement `allout-encrypt-unencrypted-on-saves' policy for file writes."
1043 nil
1057 "allout-write-file-hook-handler suppressing error %s"
1058 failure)
1060 ))
1061 nil)
1062 ;;;_ > allout-auto-save-hook-handler ()
1064 "Implement `allout-encrypt-unencrypted-on-saves' policy for auto saves."
1067 ;; Always implement 'except-current policy when enabled.
1070 ;;;_ > allout-after-saves-handler ()
1072 "Decrypt topic encrypted for save, if it's currently being edited.
1074 Ie, if it was pending encryption and contained the point in its body before
1075 the save.
1077 We use values stored in `allout-after-save-decrypt' to locate the topic
1078 and the place for the cursor after the decryption is done."
1081 allout-after-save-decrypt))
1082 t
1090 )
1092 ;;;_ #2 Mode activation
1093 ;;;_ = allout-mode
1096 ;;;_ > allout-mode-p ()
1098 "Return t if `allout-mode' is active in current buffer."
1100 ;;;_ = allout-explicitly-deactivated
1102 "If t, `allout-mode's last deactivation was deliberate.
1105 ;;;_ > allout-init (&optional mode)
1107 "Prime `allout-mode' to enable/disable auto-activation, wrt `allout-layout'.
1109 MODE is one of the following symbols:
1111 - nil \(or no argument) deactivate auto-activation/layout;
1112 - `activate', enable auto-activation only;
1113 - `ask', enable auto-activation, and enable auto-layout but with
1114 confirmation for layout operation solicited from user each time;
1115 - `report', just report and return the current auto-activation state;
1116 - anything else \(eg, t) for auto-activation and auto-layout, without
1117 any confirmation check.
1119 Use this function to setup your Emacs session for automatic activation
1120 of allout outline mode, contingent to the buffer-specific setting of
1121 the `allout-layout' variable. (See `allout-layout' and
1122 `allout-expose-topic' docstrings for more details on auto layout).
1124 `allout-init' works by setting up (or removing) the `allout-mode'
1125 find-file-hook, and giving `allout-auto-activation' a suitable
1126 setting.
1128 To prime your Emacs session for full auto-outline operation, include
1129 the following two lines in your Emacs init file:
1131 \(require 'allout)
1132 \(allout-init t)"
1143 nil
1144 t))
1149 ;; convenience aliases, for consistent ref to respective vars:
1152 'find-file-hook
1164 ;; Just punt and use the reports from each of the modes:
1173 ;; Return the current mode setting:
1184 ;;;_ > allout-setup-menubar ()
1186 "Populate the current buffer's menubar with `allout-mode' stuff."
1188 allout-mode-editing-menu
1189 allout-mode-navigation-menu
1190 allout-mode-misc-menu))
1191 cur)
1196 ;;;_ > allout-mode (&optional toggle)
1197 ;;;_ : Defun:
1198 ;;;###autoload
1200 ;;;_ . Doc string:
1201 "Toggle minor mode for controlling exposure and editing of text outlines.
1203 Optional arg forces mode to re-initialize iff arg is positive num or
1204 symbol. Allout outline mode always runs as a minor mode.
1206 Allout outline mode provides extensive outline oriented formatting and
1207 manipulation. It enables structural editing of outlines, as well as
1208 navigation and exposure. It also is specifically aimed at
1209 accommodating syntax-sensitive text like programming languages. \(For
1210 an example, see the allout code itself, which is organized as an allout
1211 outline.)
1213 In addition to outline navigation and exposure, allout includes:
1215 - topic-oriented repositioning, promotion/demotion, cut, and paste
1216 - integral outline exposure-layout
1217 - incremental search with dynamic exposure and reconcealment of hidden text
1218 - automatic topic-number maintenance
1219 - easy topic encryption and decryption
1221 exposure control. \(See the allout-mode docstring.)
1223 and many other features.
1225 Below is a description of the bindings, and then explanation of
1226 special `allout-mode' features and terminology. See also the outline
1227 menubar additions for quick reference to many of the features, and see
1228 the docstring of the function `allout-init' for instructions on
1229 priming your emacs session for automatic activation of `allout-mode'.
1232 The bindings are dictated by the `allout-keybindings-list' and
1233 `allout-command-prefix' variables.
1235 Navigation: Exposure Control:
1236 ---------- ----------------
1237 \\[allout-next-visible-heading] allout-next-visible-heading | \\[allout-hide-current-subtree] allout-hide-current-subtree
1238 \\[allout-previous-visible-heading] allout-previous-visible-heading | \\[allout-show-children] allout-show-children
1239 \\[allout-up-current-level] allout-up-current-level | \\[allout-show-current-subtree] allout-show-current-subtree
1240 \\[allout-forward-current-level] allout-forward-current-level | \\[allout-show-current-entry] allout-show-current-entry
1241 \\[allout-backward-current-level] allout-backward-current-level | \\[allout-show-all] allout-show-all
1243 \\[allout-beginning-of-current-entry,] allout-beginning-of-current-entry, alternately, goes to hot-spot
1245 Topic Header Production:
1246 -----------------------
1251 Topic Level and Prefix Adjustment:
1252 ---------------------------------
1255 \\[allout-rebullet-current-heading] allout-rebullet-current-heading Prompt for alternate bullet for
1256 current topic.
1258 - distinctive bullets are not changed, others
1259 alternated according to nesting depth.
1261 offspring are not affected. With repeat
1262 count, revoke numbering.
1264 Topic-oriented Killing and Yanking:
1265 ----------------------------------
1269 depth of heading if yanking into bare topic
1270 heading (ie, prefix sans text).
1273 Misc commands:
1274 -------------
1275 M-x outlineify-sticky Activate outline mode for current buffer,
1276 and establish a default file-var setting
1277 for `allout-layout'.
1280 Duplicate outline, sans concealed text, to
1281 buffer with name derived from derived from that
1284 Like above 'copy-exposed', but convert topic
1285 prefixes to section.subsection... numeric
1286 format.
1287 ESC ESC (allout-init t) Setup Emacs session for outline mode
1288 auto-activation.
1290 Encrypted Entries
1292 Outline mode supports easily togglable gpg encryption of topics, with
1293 niceties like support for symmetric and key-pair modes, passphrase timeout,
1294 passphrase consistency checking, user-provided hinting for symmetric key
1295 mode, and auto-encryption of topics pending encryption on save. The aim is
1296 to enable reliable topic privacy while preventing accidents like neglected
1297 encryption, encryption with a mistaken passphrase, forgetting which
1298 passphrase was used, and other practical pitfalls.
1300 See the `allout-toggle-current-subtree-encryption' function and
1301 `allout-encrypt-unencrypted-on-saves' customization variable for details.
1303 HOT-SPOT Operation
1305 Hot-spot operation provides a means for easy, single-keystroke outline
1306 navigation and exposure control.
1309 When the text cursor is positioned directly on the bullet character of
1310 a topic, regular characters (a to z) invoke the commands of the
1315 Thus, by positioning the cursor on a topic bullet, you can execute
1316 the outline navigation and manipulation commands with a single
1317 keystroke. Non-literal chars never get this special translation, so
1318 you can use them to get away from the hot-spot, and back to normal
1319 operation.
1321 Note that the command `allout-beginning-of-current-entry' \(\\[allout-beginning-of-current-entry]\)
1322 will move to the hot-spot when the cursor is already located at the
1324 twice in a row to get to the hot-spot.
1326 Terminology
1328 Topic hierarchy constituents - TOPICS and SUBTOPICS:
1330 TOPIC: A basic, coherent component of an Emacs outline. It can
1331 contain other topics, and it can be subsumed by other topics,
1332 CURRENT topic:
1333 The visible topic most immediately containing the cursor.
1334 DEPTH: The degree of nesting of a topic; it increases with
1335 containment. Also called the:
1336 LEVEL: The same as DEPTH.
1338 ANCESTORS:
1339 The topics that contain a topic.
1340 PARENT: A topic's immediate ancestor. It has a depth one less than
1341 the topic.
1342 OFFSPRING:
1343 The topics contained by a topic;
1344 SUBTOPIC:
1345 An immediate offspring of a topic;
1346 CHILDREN:
1347 The immediate offspring of a topic.
1348 SIBLINGS:
1349 Topics having the same parent and depth.
1351 Topic text constituents:
1353 HEADER: The first line of a topic, include the topic PREFIX and header
1354 text.
1355 PREFIX: The leading text of a topic which distinguishes it from normal
1356 text. It has a strict form, which consists of a prefix-lead
1357 string, padding, and a bullet. The bullet may be followed by a
1358 number, indicating the ordinal number of the topic among its
1359 siblings, a space, and then the header text.
1361 The relative length of the PREFIX determines the nesting depth
1362 of the topic.
1363 PREFIX-LEAD:
1364 The string at the beginning of a topic prefix, normally a `.'.
1365 It can be customized by changing the setting of
1366 `allout-header-prefix' and then reinitializing `allout-mode'.
1368 By setting the prefix-lead to the comment-string of a
1369 programming language, you can embed outline structuring in
1370 program code without interfering with the language processing
1371 of that code. See `allout-use-mode-specific-leader'
1372 docstring for more detail.
1373 PREFIX-PADDING:
1374 Spaces or asterisks which separate the prefix-lead and the
1375 bullet, according to the depth of the topic.
1376 BULLET: A character at the end of the topic prefix, it must be one of
1377 the characters listed on `allout-plain-bullets-string' or
1378 `allout-distinctive-bullets-string'. (See the documentation
1379 for these variables for more details.) The default choice of
1380 bullet when generating varies in a cycle with the depth of the
1381 topic.
1382 ENTRY: The text contained in a topic before any offspring.
1383 BODY: Same as ENTRY.
1386 EXPOSURE:
1387 The state of a topic which determines the on-screen visibility
1388 of its offspring and contained text.
1389 CONCEALED:
1390 Topics and entry text whose display is inhibited. Contiguous
1391 units of concealed text is represented by `...' ellipses.
1392 (Ref the `selective-display' var.)
1394 Concealed topics are effectively collapsed within an ancestor.
1395 CLOSED: A topic whose immediate offspring and body-text is concealed.
1396 OPEN: A topic that is not closed, though its offspring or body may be."
1397 ;;;_ . Code
1402 ; Massage universal-arg `toggle' val:
1405 toggle)))
1406 ; Activation specifically demanded?
1408 ;;
1413 ;; allout-mode already called once during this complex command?
1417 'write-file-functions
1419 do-layout
1420 )
1422 ; See comments below re v19.18,.19 bug.
1427 ;; Provision for v19.18, 19.19 bug -
1428 ;; Emacs v 19.18, 19.19 file-var code invokes prop-line-designated
1429 ;; modes twice when file is visited. We have to avoid toggling mode
1430 ;; off on second invocation, so we detect it as best we can, and
1431 ;; skip everything.
1433 ; as last time `allout-mode' invoked.
1434 active ; Already activated.
1438 t)
1440 ;; Deactivation:
1443 ; Activation not explicitly
1444 ; requested, and either in
1445 ; active state or *de*activation
1446 ; specifically requested:
1449 ; Revoke those keys that remain
1450 ; as we set them:
1458 allout-added-bindings)
1474 auto-save-hook))
1478 'auto-fill-hook
1483 ;; Activation:
1496 ; Produce map from current version
1497 ; of allout-keybindings-list:
1501 ; epoch, minor-mode key bindings:
1506 ; Include on minor-mode-map-alist,
1507 ; if not already there:
1509 minor-mode-map-alist))
1512 minor-mode-map-alist))))
1514 ; V18 minor-mode key bindings:
1515 ; Stash record of added bindings
1516 ; for later revocation:
1521 ; and add them:
1524 )
1526 ; selective-display is the
1527 ; emacs conditional exposure
1528 ; mechanism:
1534 ; Custom auto-fill func, to support
1535 ; respect for topic headline,
1536 ; hanging-indents, etc:
1538 'auto-fill-hook
1541 ;; Register prevailing fill func for use by allout-auto-fill:
1543 ;; Register allout-auto-fill to be used if filling is active:
1545 ;; Paragraphs are broken by topic headlines.
1571 ;; Reactivation:
1577 allout-auto-activation
1583 allout-layout))
1584 t
1586 nil)
1587 t)))
1596 ;; Problem applying exposure - notify user, but don't
1597 ;; interrupt, eg, file visit:
1600 allout-mode
1603 ;;;_ > allout-minor-mode
1606 ;;;_ #3 Internal Position State-Tracking - "allout-recent-*" funcs
1607 ;;; All the basic outline functions that directly do string matches to
1608 ;;; evaluate heading prefix location set the variables
1609 ;;; `allout-recent-prefix-beginning' and `allout-recent-prefix-end'
1610 ;;; when successful. Functions starting with `allout-recent-' all
1611 ;;; use this state, providing the means to avoid redundant searches
1612 ;;; for just-established data. This optimization can provide
1613 ;;; significant speed improvement, but it must be employed carefully.
1614 ;;;_ = allout-recent-prefix-beginning
1618 ;;;_ = allout-recent-prefix-end
1622 ;;;_ = allout-recent-end-of-subtree
1626 ;;;_ > allout-prefix-data (beg end)
1628 "Register allout-prefix state data - BEGINNING and END of prefix.
1630 For reference by `allout-recent' funcs. Returns BEGINNING."
1633 ;;;_ > allout-recent-depth ()
1635 "Return depth of last heading encountered by an outline maneuvering function.
1637 All outline functions which directly do string matches to assess
1638 headings set the variables `allout-recent-prefix-beginning' and
1639 `allout-recent-prefix-end' if successful. This function uses those settings
1640 to return the current depth."
1643 allout-recent-prefix-beginning
1644 allout-header-subtraction)))
1645 ;;;_ > allout-recent-prefix ()
1647 "Like `allout-recent-depth', but returns text of last encountered prefix.
1649 All outline functions which directly do string matches to assess
1650 headings set the variables `allout-recent-prefix-beginning' and
1651 `allout-recent-prefix-end' if successful. This function uses those settings
1652 to return the current depth."
1654 allout-recent-prefix-end))
1655 ;;;_ > allout-recent-bullet ()
1657 "Like allout-recent-prefix, but returns bullet of last encountered prefix.
1659 All outline functions which directly do string matches to assess
1660 headings set the variables `allout-recent-prefix-beginning' and
1661 `allout-recent-prefix-end' if successful. This function uses those settings
1662 to return the current depth of the most recently matched topic."
1664 allout-recent-prefix-end))
1666 ;;;_ #4 Navigation
1668 ;;;_ - Position Assessment
1669 ;;;_ : Location Predicates
1670 ;;;_ > allout-on-current-heading-p ()
1672 "Return non-nil if point is on current visible topics' header line.
1674 Actually, returns prefix beginning point."
1679 ;;;_ > allout-on-heading-p ()
1681 ;;;_ > allout-e-o-prefix-p ()
1683 "True if point is located where current topic prefix ends, heading begins."
1687 ;;;_ > allout-hidden-p ()
1689 "True if point is in hidden text."
1693 ;;;_ > allout-visible-p ()
1695 "True if point is not in hidden text."
1698 ;;;_ : Location attributes
1699 ;;;_ > allout-depth ()
1701 "Like `allout-current-depth', but respects hidden as well as visible topics."
1706 ;; Oops, no prefix, zero prefix data:
1708 ;; ... and return 0:
1710 ;;;_ > allout-current-depth ()
1712 "Return nesting depth of visible topic most immediately containing point."
1717 allout-recent-prefix-beginning
1718 allout-header-subtraction))
1720 ;;;_ > allout-get-current-prefix ()
1722 "Topic prefix of the current topic."
1726 ;;;_ > allout-get-bullet ()
1728 "Return bullet of containing topic (visible or not)."
1732 ;;;_ > allout-current-bullet ()
1734 "Return bullet of current (visible) topic heading, or none if none found."
1739 allout-recent-prefix-end))
1740 ;; Quick and dirty provision, ostensibly for missing bullet:
1742 )
1743 ;;;_ > allout-get-prefix-bullet (prefix)
1745 "Return the bullet of the header prefix string PREFIX."
1746 ;; Doesn't make sense if we're old-style prefixes, but this just
1747 ;; oughtn't be called then, so forget about it...
1750 ;;;_ > allout-sibling-index (&optional depth)
1752 "Item number of this prospective topic among its siblings.
1754 If optional arg DEPTH is greater than current depth, then we're
1755 opening a new level, and return 0.
1757 If less than this depth, ascend to that depth and count..."
1765 index))
1770 ;;;_ > allout-topic-flat-index ()
1772 "Return a list indicating point's numeric section.subsect.subsubsect...
1773 Outermost is first."
1781 rev-sibls)
1782 )
1784 ;;;_ - Navigation macros
1785 ;;;_ > allout-next-heading ()
1787 "Move to the heading for the topic \(possibly invisible) before this one.
1789 Returns the location of the heading, or nil if none found."
1797 allout-recent-prefix-beginning))
1799 ;;;_ : allout-this-or-next-heading
1801 "Position cursor on current or next heading."
1802 ;; A throwaway non-macro that is defined after allout-next-heading
1803 ;; and usable by allout-mode.
1805 ;;;_ > allout-previous-heading ()
1807 "Move to the prior \(possibly invisible) heading line.
1809 Return the location of the beginning of the heading, or nil if not found."
1812 nil
1815 ;; searches are unbounded and return nil if failed:
1821 allout-recent-prefix-beginning))
1824 ;;;_ - Subtree Charting
1825 ;;;_ " These routines either produce or assess charts, which are
1826 ;;; nested lists of the locations of topics within a subtree.
1827 ;;;
1828 ;;; Use of charts enables efficient navigation of subtrees, by
1829 ;;; requiring only a single regexp-search based traversal, to scope
1830 ;;; out the subtopic locations. The chart then serves as the basis
1831 ;;; for assessment or adjustment of the subtree, without redundant
1832 ;;; traversal of the structure.
1834 ;;;_ > allout-chart-subtree (&optional levels orig-depth prev-depth)
1838 Optional argument LEVELS specifies the depth \(relative to start
1839 depth) for the chart. Subsequent optional args are not for public
1840 use.
1842 Point is left at the end of the subtree.
1844 Charts are used to capture outline structure, so that outline-altering
1845 routines need assess the structure only once, and then use the chart
1846 for their elaborate manipulations.
1848 Topics are entered in the chart so the last one is at the car.
1849 The entry for each topic consists of an integer indicating the point
1850 at the beginning of the topic. Charts for offspring consists of a
1851 list containing, recursively, the charts for the respective subtopics.
1852 The chart for a topics' offspring precedes the entry for the topic
1853 itself.
1855 The other function parameters are for internal recursion, and should
1856 not be specified by external callers. ORIG-DEPTH is depth of topic at
1857 starting point, and PREV-DEPTH is depth of prior topic."
1860 chart curr-depth)
1863 ; Register initial settings and
1864 ; position to first offspring:
1869 ;; Loop over the current levels' siblings. Besides being more
1870 ;; efficient than tail-recursing over a level, it avoids exceeding
1871 ;; the typically quite constrained Emacs max-lisp-eval-depth.
1872 ;;
1873 ;; Probably would speed things up to implement loop-based stack
1874 ;; operation rather than recursing for lower levels. Bah.
1877 ; Still within original topic?
1880 ;; Register this one and move on:
1883 ;; At depth limit - skip sublevels:
1885 ;; or no more siblings - proceed to
1886 ;; next heading at lesser depth:
1895 ;; Recurse on deeper level of curr topic:
1899 orig-depth
1900 curr-depth)
1901 chart))
1902 ;; ... then continue with this one.
1903 )
1905 ;; ... else nil if we've ascended back to prev-depth.
1907 )))
1910 ; the original level. Position
1911 ; to the end of it:
1921 chart ; (nreverse chart) not necessary,
1922 ; and maybe not preferable.
1923 ))
1924 ;;;_ > allout-chart-siblings (&optional start end)
1926 "Produce a list of locations of this and succeeding sibling topics.
1927 Effectively a top-level chart of siblings. See `allout-chart-subtree'
1928 for an explanation of charts."
1935 ;;;_ > allout-chart-to-reveal (chart depth)
1938 "Return a flat list of hidden points in subtree CHART, up to DEPTH.
1940 Note that point can be left at any of the points on chart, or at the
1941 start point."
1945 chart)
1950 ;; We're on the start of a subtree - recurse with it, if there's
1951 ;; more depth to go:
1958 result))
1959 ;;;_ X allout-chart-spec (chart spec &optional exposing)
1960 ;; (defun allout-chart-spec (chart spec &optional exposing)
1961 ;; "Not yet \(if ever) implemented.
1963 ;; Produce exposure directives given topic/subtree CHART and an exposure SPEC.
1965 ;; Exposure spec indicates the locations to be exposed and the prescribed
1966 ;; exposure status. Optional arg EXPOSING is an integer, with 0
1967 ;; indicating pending concealment, anything higher indicating depth to
1968 ;; which subtopic headers should be exposed, and negative numbers
1969 ;; indicating (negative of) the depth to which subtopic headers and
1970 ;; bodies should be exposed.
1972 ;; The produced list can have two types of entries. Bare numbers
1973 ;; indicate points in the buffer where topic headers that should be
1974 ;; exposed reside.
1976 ;; - bare negative numbers indicates that the topic starting at the
1977 ;; point which is the negative of the number should be opened,
1978 ;; including their entries.
1979 ;; - bare positive values indicate that this topic header should be
1980 ;; opened.
1981 ;; - Lists signify the beginning and end points of regions that should
1982 ;; be flagged, and the flag to employ. (For concealment: `\(\?r\)', and
1983 ;; exposure:"
1984 ;; (while spec
1985 ;; (cond ((listp spec)
1986 ;; )
1987 ;; )
1988 ;; (setq spec (cdr spec)))
1989 ;; )
1991 ;;;_ - Within Topic
1992 ;;;_ > allout-goto-prefix ()
1994 "Put point at beginning of immediately containing outline topic.
1996 Goes to most immediate subsequent topic if none immediately containing.
1998 Not sensitive to topic visibility.
2000 Returns the point at the beginning of the prefix, or nil if none."
2015 done)))
2016 ;;;_ > allout-end-of-prefix ()
2018 "Position cursor at beginning of header text.
2020 If optional IGNORE-DECORATIONS is non-nil, put just after bullet,
2021 otherwise skip white space between bullet and ensuing text."
2024 nil
2028 t
2032 ;; Reestablish where we are:
2034 ;;;_ > allout-current-bullet-pos ()
2036 "Return position of current \(visible) topic's bullet."
2039 nil
2041 ;;;_ > allout-back-to-current-heading ()
2043 "Move to heading line of current topic, or beginning if already on the line."
2048 nil
2052 ;;;_ > allout-back-to-heading ()
2054 ;;;_ > allout-pre-next-preface ()
2056 "Skip forward to just before the next heading line.
2058 Returns that character position."
2063 ;;;_ > allout-end-of-subtree (&optional current)
2065 "Put point at the end of the last leaf in the containing topic.
2067 If optional CURRENT is true (default false), then put point at the end of
2068 the containing visible topic.
2070 Returns the value of point."
2086 ;;;_ > allout-end-of-current-subtree ()
2088 "Put point at end of last leaf in currently visible containing topic.
2090 Returns the value of point."
2093 ;;;_ > allout-beginning-of-current-entry ()
2095 "When not already there, position point at beginning of current topic header.
2097 If already there, move cursor to bullet for hot-spot operation.
2098 \(See `allout-mode' doc string for details on hot-spot operation.)"
2105 ;;;_ > allout-end-of-entry ()
2107 "Position the point at the end of the current topics' entry."
2112 ;;;_ > allout-end-of-current-heading ()
2119 ;;;_ > allout-get-body-text ()
2121 "Return the unmangled body text of the topic immediately containing point."
2125 nil
2129 nil
2133 )
2134 )
2135 )
2136 )
2138 ;;;_ - Depth-wise
2139 ;;;_ > allout-ascend-to-depth (depth)
2141 "Ascend to depth DEPTH, returning depth if successful, nil if not."
2150 depth)
2152 nil))
2154 ;;;_ > allout-ascend ()
2156 "Ascend one level, returning t if successful, nil if not."
2161 ;;;_ > allout-descend-to-depth (depth)
2163 "Descend to depth DEPTH within current topic.
2165 Returning depth if successful, nil if not."
2175 depth
2177 nil))
2178 )
2179 ;;;_ > allout-up-current-level (arg &optional dont-complain)
2181 "Move out ARG levels from current visible topic.
2183 Positions on heading line of containing topic. Error if unable to
2184 ascend that far, or nil if unable to ascend but optional arg
2185 DONT-COMPLAIN is non-nil."
2190 failed
2191 return)
2192 ;; Loop for iterating arg:
2198 ;; Loop for going back over current or greater depth:
2211 nil))
2213 allout-recent-prefix-beginning)))
2215 ;;;_ - Linear
2216 ;;;_ > allout-next-sibling (&optional depth backward)
2218 "Like `allout-forward-current-level', but respects invisible topics.
2220 Traverse at optional DEPTH, or current depth if none specified.
2222 Go backward if optional arg BACKWARD is non-nil.
2224 Return depth if successful, nil otherwise."
2227 nil
2230 last-depth)
2238 allout-recent-prefix-beginning
2241 nil))))
2242 ;;;_ > allout-previous-sibling (&optional depth backward)
2244 "Like `allout-forward-current-level' backwards, respecting invisible topics.
2246 Optional DEPTH specifies depth to traverse, default current depth.
2248 Optional BACKWARD reverses direction.
2250 Return depth if successful, nil otherwise."
2252 )
2253 ;;;_ > allout-snug-back ()
2255 "Position cursor at end of previous topic.
2257 Presumes point is at the start of a topic prefix."
2259 nil
2262 nil
2267 ;;;_ > allout-beginning-of-level ()
2269 "Go back to the first sibling at this level, visible or not."
2271 ;;;_ > allout-end-of-level (&optional backward)
2273 "Go to the last sibling at this level, visible or not."
2279 ;;;_ > allout-next-visible-heading (arg)
2281 "Move to the next ARG'th visible heading line, backward if arg is negative.
2283 Move as far as possible in indicated direction \(beginning or end of
2284 buffer) if headings are exhausted."
2290 prev got)
2294 ;; Move, skipping over all those concealed lines:
2297 ;; Register this got, it may be the last:
2306 ;;;_ > allout-previous-visible-heading (arg)
2308 "Move to the previous heading line.
2310 With argument, repeats or can move forward if negative.
2311 A heading line is one that starts with a `*' (or that `allout-regexp'
2312 matches)."
2315 ;;;_ > allout-forward-current-level (arg)
2317 "Position point at the next heading of the same level.
2319 Takes optional repeat-count, goes backward if count is negative.
2321 Returns resulting position, else nil if none found."
2327 last-depth
2329 at-boundary)
2334 at-boundary))
2348 allout-recent-prefix-beginning
2351 nil
2358 ;;;_ > allout-backward-current-level (arg)
2360 "Inverse of `allout-forward-current-level'."
2367 ;;;_ #5 Alteration
2369 ;;;_ - Fundamental
2370 ;;;_ = allout-post-goto-bullet
2372 "Outline internal var, for `allout-pre-command-business' hot-spot operation.
2374 When set, tells post-processing to reposition on topic bullet, and
2375 then unset it. Set by `allout-pre-command-business' when implementing
2376 hot-spot operation, where literal characters typed over a topic bullet
2377 are mapped to the command of the corresponding control-key on the
2380 ;;;_ > allout-post-command-business ()
2382 "Outline `post-command-hook' function.
2384 - Implement (and clear) `allout-post-goto-bullet', for hot-spot
2385 outline commands.
2387 - Decrypt topic currently being edited if it was encrypted for a save.
2389 - Massage buffer-undo-list so successive, standard character self-inserts are
2390 aggregated. This kludge compensates for lack of undo bunching when
2391 before-change-functions is used."
2393 ; Apply any external change func:
2395 nil
2398 ;; Undo bunching business:
2404 cur-cell cur-from cur-to
2405 prev-cell prev-from prev-to)
2412 ;; cur contents denote a single char insertion:
2417 ;; prev contents denote fewer than aggregate-limit
2418 ;; insertions:
2421 ; Below threshold:
2428 allout-after-save-decrypt)
2431 ;; Implement -post-goto-bullet, if set: (must be after undo business)
2436 ))
2437 ;;;_ > allout-pre-command-business ()
2439 "Outline `pre-command-hook' function for outline buffers.
2440 Implements special behavior when cursor is on bullet character.
2442 When the cursor is on the bullet character, self-insert characters are
2443 reinterpreted as the corresponding control-character in the
2444 `allout-mode-map'. The `allout-mode' `post-command-hook' insures that
2445 the cursor which has moved as a result of such reinterpretation is
2446 positioned on the bullet character of the destination topic.
2448 The upshot is that you can get easy, single (ie, unmodified) key
2449 outline maneuvering operations by positioning the cursor on the bullet
2450 char. When in this mode you can use regular cursor-positioning
2451 command/keystrokes to relocate the cursor off of a bullet character to
2452 return to regular interpretation of self-insert characters."
2455 ;; Shouldn't be invoked if not in allout-mode, but just in case:
2456 nil
2457 ;; Register isearch status:
2461 ;; Hot-spot navigation provisions:
2466 last-command-char)
2467 ;; Only xemacs has characterp.
2473 mapped-binding)
2475 nil
2476 ; Map upper-register literals
2477 ; to lower register:
2480 ; Check if we have a literal:
2490 this-command mapped-binding)))))))
2491 ;;;_ > allout-find-file-hook ()
2493 "Activate `allout-mode' when `allout-auto-activation', `allout-layout' non-nil.
2495 See `allout-init' for setup instructions."
2498 allout-layout)
2500 ;;;_ > allout-isearch-rectification
2502 "Rectify outline exposure before, during, or after isearch.
2504 Called as part of `allout-post-command-business'."
2513 ;; Not and wasn't isearching:
2516 ;;;_ = allout-isearch-was-font-lock
2519 ;;;_ > allout-isearch-expose (mode)
2521 "MODE is either 'clear, 'start, 'continue, or 'final."
2522 ;; allout-isearch-prior-pos encodes exposure status of prior pos:
2523 ;; (pos was-vis header-pos end-pos)
2524 ;; pos - point of concern
2525 ;; was-vis - t, else 'topic if entire topic was exposed, 'entry otherwise
2526 ;; Do reclosure or prior pos, as necessary:
2529 font-lock-mode)
2530 font-lock-mode nil)
2535 ;; Conceal prior peek:
2544 nil
2548 ;;;_ > allout-enwrap-isearch ()
2550 "Impose `allout-mode' isearch-abort wrapper for dynamic exposure in isearch.
2552 The function checks to ensure that the rebinding is done only once."
2556 ;;
2557 nil
2558 ; Ensure load of isearch-mode:
2564 "Skipping isearch-mode provisions - %s '%s'"
2568 ;; Inhibit subsequent tries and return nil:
2570 ;; Isearch-mode loaded, encapsulate specific entry points for
2571 ;; outline dynamic-exposure business:
2573 ;; stash crucial isearch-mode funcs under known, private
2574 ;; names, then register wrapper functions under the old
2575 ;; names, in their stead:
2578 ;;;_ > allout-isearch-abort ()
2580 "Wrapper for allout-real-isearch-abort \(which see), to register
2581 actual quits."
2589 ;;; Prevent unnecessary font-lock while isearching!
2592 "Inhibit `font-lock' while isearching - for use on `isearch-mode-hook'."
2595 font-lock-mode nil)))
2598 "Reenable font-lock after isearching - for use on `isearch-mode-end-hook'."
2602 font-lock-mode t))))
2605 ;;;_ - Topic Format Assessment
2606 ;;;_ > allout-solicit-alternate-bullet (depth &optional current-bullet)
2609 "Prompt for and return a bullet char as an alternative to the current one.
2611 Offer one suitable for current depth DEPTH as default."
2616 choice)
2621 sans-escapes
2622 default-bullet)
2623 sans-escapes
2624 t)))
2627 )
2628 ;;;_ > allout-distinctive-bullet (bullet)
2630 "True if BULLET is one of those on `allout-distinctive-bullets-string'."
2632 ;;;_ > allout-numbered-type-prefix (&optional prefix)
2634 "True if current header prefix bullet is numbered bullet."
2640 ;;;_ > allout-encrypted-type-prefix (&optional prefix)
2642 "True if current header prefix bullet is for an encrypted entry \(body)."
2648 ;;;_ > allout-bullet-for-depth (&optional depth)
2650 "Return outline topic bullet suited to optional DEPTH, or current depth."
2651 ;; Find bullet in plain-bullets-string modulo DEPTH.
2655 allout-plain-bullets-string-len)))
2656 allout-primary-bullet)
2657 )
2659 ;;;_ - Topic Production
2660 ;;;_ > allout-make-topic-prefix (&optional prior-bullet
2662 new
2663 depth
2664 solicit
2665 number-control
2666 index)
2667 ;; Depth null means use current depth, non-null means we're either
2668 ;; opening a new topic after current topic, lower or higher, or we're
2669 ;; changing level of current topic.
2670 ;; Solicit dominates specified bullet-char.
2671 ;;;_ . Doc string:
2672 "Generate a topic prefix suitable for optional arg DEPTH, or current depth.
2674 All the arguments are optional.
2676 PRIOR-BULLET indicates the bullet of the prefix being changed, or
2677 nil if none. This bullet may be preserved (other options
2678 notwithstanding) if it is on the `allout-distinctive-bullets-string',
2679 for instance.
2681 Second arg NEW indicates that a new topic is being opened after the
2682 topic at point, if non-nil. Default bullet for new topics, eg, may
2683 be set (contingent to other args) to numbered bullets if previous
2684 sibling is one. The implication otherwise is that the current topic
2685 is being adjusted - shifted or rebulleted - and we don't consider
2686 bullet or previous sibling.
2688 Third arg DEPTH forces the topic prefix to that depth, regardless of
2689 the current topics' depth.
2691 If SOLICIT is non-nil, then the choice of bullet is solicited from
2692 user. If it's a character, then that character is offered as the
2693 default, otherwise the one suited to the context \(according to
2694 distinction or depth) is offered. \(This overrides other options,
2695 including, eg, a distinctive PRIOR-BULLET.) If non-nil, then the
2696 context-specific bullet is used.
2698 Fifth arg, NUMBER-CONTROL, matters only if `allout-numbered-bullet'
2699 is non-nil *and* soliciting was not explicitly invoked. Then
2700 NUMBER-CONTROL non-nil forces prefix to either numbered or
2701 denumbered format, depending on the value of the sixth arg, INDEX.
2703 \(Note that NUMBER-CONTROL does *not* apply to level 1 topics. Sorry...)
2705 If NUMBER-CONTROL is non-nil and sixth arg INDEX is non-nil then
2706 the prefix of the topic is forced to be numbered. Non-nil
2707 NUMBER-CONTROL and nil INDEX forces non-numbered format on the
2708 bullet. Non-nil NUMBER-CONTROL and non-nil, non-number INDEX means
2709 that the index for the numbered prefix will be derived, by counting
2710 siblings back to start of level. If INDEX is a number, then that
2711 number is used as the index for the numbered prefix (allowing, eg,
2712 sequential renumbering to not require this function counting back the
2713 index for each successive sibling)."
2714 ;;;_ . Code:
2715 ;; The options are ordered in likely frequence of use, most common
2716 ;; highest, least lowest. Ie, more likely to be doing prefix
2717 ;; adjustments than soliciting, and yet more than numbering.
2718 ;; Current prefix is least dominant, but most likely to be commonly
2719 ;; specified...
2722 numbering
2723 denumbering
2728 ;; Getting value for bullet char is practically the whole job:
2731 ; Simplest situation - level 1:
2733 ; Simple, too: all asterisks:
2735 ;; Cheat - make body the whole thing, null out header-lead and
2736 ;; bullet-char:
2742 ;; (Neither level 1 nor old-style, so we're space padding.
2743 ;; Sneak it in the condition of the next case, whatever it is.)
2745 ;; Solicitation overrides numbering and other cases:
2747 ;; The actual condition:
2748 solicit)
2750 ;; Gotta check whether we're numbering and got a numbered bullet:
2754 ;; Now return what we got, regardless:
2755 got))
2757 ;; Numbering invoked through args:
2760 allout-numbered-bullet
2763 prior-bullet)))
2764 prior-bullet
2767 ;;; Neither soliciting nor controlled numbering ;;;
2768 ;;; (may be controlled denumbering, tho) ;;;
2770 ;; Check wrt previous sibling:
2773 allout-numbered-bullet ; ... & numbering enabled
2777 ;; Locate correct sibling:
2785 ;; Distinctive prior bullet?
2788 ;; Either non-numbered:
2791 ;; or numbered, and not denumbering:
2793 ;; Here 'tis:
2794 prior-bullet))
2796 ;; Else, standard bullet per depth:
2800 body
2801 bullet-char
2806 )
2807 )
2808 ;;;_ > allout-open-topic (relative-depth &optional before use_recent_bullet)
2810 "Open a new topic at depth DEPTH.
2812 New topic is situated after current one, unless optional flag BEFORE
2813 is non-nil, or unless current line is complete empty (not even
2814 whitespace), in which case open is done on current line.
2816 If USE_RECENT_BULLET is true, offer to use the bullet of the prior sibling.
2818 Nuances:
2820 - Creation of new topics is with respect to the visible topic
2821 containing the cursor, regardless of intervening concealed ones.
2823 - New headers are generally created after/before the body of a
2824 topic. However, they are created right at cursor location if the
2825 cursor is on a blank line, even if that breaks the current topic
2826 body. This is intentional, to provide a simple means for
2827 deliberately dividing topic bodies.
2829 - Double spacing of topic lists is preserved. Also, the first
2830 level two topic is created double-spaced (and so would be
2831 subsequent siblings, if that's left intact). Otherwise,
2832 single-spacing is used.
2834 - Creation of sibling or nested topics is with respect to the topic
2835 you're starting from, even when creating backwards. This way you
2836 can easily create a sibling in front of the current topic without
2837 having to go to its preceding sibling, and then open forward
2838 from there."
2843 ;; bunch o vars set while computing ref-topic
2844 opening-numbered
2845 opening-encrypted
2846 ref-depth
2847 ref-bullet
2864 allout-numbered-bullet))))
2871 allout-numbered-bullet))))
2873 dbl-space
2874 doing-beginning)
2877 ; Positioning and vertical
2878 ; padding - only if not
2879 ; opening-on-blank:
2885 ;; at b-o-b or preceded by a blank line?
2890 ;; succeeded by a blank line?
2897 ;; Don't already have following
2898 ;; vertical padding:
2901 ; Position to prior heading,
2902 ; if inserting backwards, and
2903 ; not going outwards:
2913 ;; Not going inwards, don't snug up:
2929 ;; Going inwards - double-space if first offspring is,
2930 ;; otherwise snug up.
2934 ;; Blank lines between current header body and next
2935 ;; header - get to last substantive (non-white-space)
2936 ;; line in body:
2941 ;; This is an offspring.
2949 ;;(if doing-beginning (goto-char doing-beginning))
2951 ;; We insert a newline char rather than using open-line to
2952 ;; avoid rear-stickiness inheritence of read-only property.
2970 ))
2972 t
2973 depth)
2976 ;;(if doing-beginning (save-excursion (newline (if dbl-space 2 1))))
2980 ref-bullet)
2981 depth ;;; depth
2982 nil ;;; number-control
2983 nil ;;; index
2984 t)
2986 )
2987 )
2988 ;;;_ . open-topic contingencies
2989 ;;;_ ; base topic - one from which open was issued
2990 ;;;_ , beginning char
2991 ;;;_ , amount of space before will be used, unless opening in place
2992 ;;;_ , end char will be used, unless opening before (and it still may)
2993 ;;;_ ; absolute depth of new topic
2994 ;;;_ ! insert in place - overrides most stuff
2995 ;;;_ ; relative depth of new re base
2996 ;;;_ ; before or after base topic
2997 ;;;_ ; spacing around topic, if any, prior to new topic and at same depth
2998 ;;;_ ; buffer boundaries - special provisions for beginning and end ob
2999 ;;;_ ; level 1 topics have special provisions also - double space.
3000 ;;;_ ; location of new topic
3001 ;;;_ > allout-open-line-not-read-only ()
3003 "Open line and remove inherited read-only text prop from new char, if any."
3008 ;;;_ > allout-open-subtopic (arg)
3010 "Open new topic header at deeper level than the current one.
3012 Negative universal arg means to open deeper, but place the new topic
3013 prior to the current one."
3016 ;;;_ > allout-open-sibtopic (arg)
3018 "Open new topic header at same level as the current one.
3020 Positive universal arg means to use the bullet of the prior sibling.
3022 Negative universal arg means to place the new topic prior to the current
3023 one."
3026 ;;;_ > allout-open-supertopic (arg)
3028 "Open new topic header at shallower level than the current one.
3030 Negative universal arg means to open shallower, but place the new
3031 topic prior to the current one."
3036 ;;;_ - Outline Alteration
3037 ;;;_ : Topic Modification
3038 ;;;_ = allout-former-auto-filler
3041 ;;;_ > allout-auto-fill ()
3043 "`allout-mode' autofill function.
3045 Maintains outline hanging topic indentation if
3046 `allout-use-hanging-indents' is set."
3048 ;; Check for topic header indentation:
3052 ;; ... construct indentation to account for
3053 ;; length of topic prefix:
3056 ?\ ))))))
3059 ;;;_ > allout-reindent-body (old-depth new-depth &optional number)
3061 "Reindent body lines which were indented at OLD-DEPTH to NEW-DEPTH.
3063 Optional arg NUMBER indicates numbering is being added, and it must
3064 be accommodated.
3066 Note that refill of indented paragraphs is not done."
3071 excess old-indent-begin old-indent-end
3072 curr-ind
3073 ;; We want the column where the header-prefix text started
3074 ;; *before* the prefix was changed, so we infer it relative
3075 ;; to the new margin and the shift in depth:
3078 ;; Process lines up to (but excluding) next topic header:
3083 nil
3084 t)
3085 ;; Register the indent data, before we reset the
3086 ;; match data with a subsequent `looking-at':
3091 old-margin)))
3092 ;; Text starts left of old margin - don't adjust:
3093 nil
3094 ;; Text was hanging at or right of old left margin -
3095 ;; reindent it, preserving its existing indentation
3096 ;; beyond the old margin:
3099 ;;;_ > allout-rebullet-current-heading (arg)
3101 "Solicit new bullet for current visible heading."
3111 nil ;;; depth
3112 nil ;;; number-control
3113 nil ;;; index
3117 nil
3126 ;;;_ > allout-rebullet-heading (&optional solicit ...)
3128 new-depth
3129 number-control
3130 index
3131 do-successors)
3133 "Adjust bullet of current topic prefix.
3135 All args are optional.
3137 If SOLICIT is non-nil, then the choice of bullet is solicited from
3138 user. If it's a character, then that character is offered as the
3139 default, otherwise the one suited to the context \(according to
3140 distinction or depth) is offered. If non-nil, then the
3141 context-specific bullet is just used.
3143 Second arg DEPTH forces the topic prefix to that depth, regardless
3144 of the topic's current depth.
3146 Third arg NUMBER-CONTROL can force the prefix to or away from
3147 numbered form. It has effect only if `allout-numbered-bullet' is
3148 non-nil and soliciting was not explicitly invoked (via first arg).
3149 Its effect, numbering or denumbering, then depends on the setting
3150 of the forth arg, INDEX.
3152 If NUMBER-CONTROL is non-nil and forth arg INDEX is nil, then the
3153 prefix of the topic is forced to be non-numbered. Null index and
3154 non-nil NUMBER-CONTROL forces denumbering. Non-nil INDEX (and
3155 non-nil NUMBER-CONTROL) forces a numbered-prefix form. If non-nil
3156 INDEX is a number, then that number is used for the numbered
3157 prefix. Non-nil and non-number means that the index for the
3158 numbered prefix will be derived by allout-make-topic-prefix.
3160 Fifth arg DO-SUCCESSORS t means re-resolve count on succeeding
3161 siblings.
3163 Cf vars `allout-stylish-prefixes', `allout-old-style-prefixes',
3164 and `allout-numbered-bullet', which all affect the behavior of
3165 this function."
3173 nil
3174 new-depth
3175 solicit
3176 number-control
3177 index)))
3179 ;; Is new one is identical to old?
3183 ;; Nothing to do:
3184 t
3186 ;; New prefix probably different from old:
3187 ; get rid of old one:
3190 ; Dispense with number if
3191 ; numbered-bullet prefix:
3198 ; Put in new prefix:
3201 ;; Reindent the body if elected, margin changed, and not encrypted body:
3207 ;; Recursively rectify successive siblings of orig topic if
3208 ;; caller elected for it:
3217 new-depth ;;; new-depth
3218 number-control;;; number-control
3219 index ;;; index
3224 ;;;_ > allout-rebullet-topic (arg)
3226 "Rebullet the visible topic containing point and all contained subtopics.
3228 Descends into invisible as well as visible topics, however.
3230 With repeat count, shift topic depth by that amount."
3235 ;; Normalize arg:
3238 ;; Fill the user in, in case we're shifting a big topic:
3246 ;;;_ > allout-rebullet-topic-grunt (&optional relative-depth ...)
3248 starting-depth
3249 starting-point
3250 index
3251 do-successors)
3252 "Like `allout-rebullet-topic', but on nearest containing topic
3253 \(visible or not).
3255 See `allout-rebullet-heading' for rebulleting behavior.
3257 All arguments are optional.
3259 First arg RELATIVE-DEPTH means to shift the depth of the entire
3260 topic that amount.
3262 The rest of the args are for internal recursive use by the function
3263 itself. The are STARTING-DEPTH, STARTING-POINT, and INDEX."
3270 ;; Leave index null on starting call, so rebullet-heading
3271 ;; calculates it at what might be new depth:
3278 ;; Sanity check for excessive promotion done only on starting call:
3280 moving-outwards
3285 ;; We're at depth to work on this one:
3288 relative-depth)
3289 nil ;;; number
3290 index ;;; index
3291 ;; Every contained topic will get hit,
3292 ;; and we have to get to outside ones
3293 ;; deliberately:
3295 ;; ... and work on subsequent ones which are at greater depth:
3303 starting-point ;;; starting-point
3307 ;; Rare case - subtopic more than one level deeper than parent.
3308 ;; Treat this one at an even deeper level:
3310 new-depth ;;; starting-depth
3311 starting-point ;;; starting-point
3316 ;; Rectify numbering of former siblings of the adjusted topic,
3317 ;; if topic has changed depth
3322 relative-depth)))))
3324 ;; Now rectify numbering of new siblings of the adjusted topic,
3325 ;; if depth has been changed:
3329 )
3330 )
3331 ;;;_ > allout-renumber-to-depth (&optional depth)
3333 "Renumber siblings at current depth.
3335 Affects superior topics if optional arg DEPTH is less than current depth.
3337 Returns final depth."
3339 ;; Proceed by level, processing subsequent siblings on each,
3340 ;; ascending until we get shallower than the start depth:
3343 was-eobp)
3348 ; Skip over all topics at
3349 ; lesser depths, which can not
3350 ; have been disturbed:
3354 ; Prime ascender for ascension:
3358 nil ;;; depth
3359 nil ;;; number-control
3360 nil ;;; index
3364 ;;;_ > allout-number-siblings (&optional denumber)
3366 "Assign numbered topic prefix to this topic and its siblings.
3368 With universal argument, denumber - assign default bullet to this
3369 topic and its siblings.
3371 With repeated universal argument (`^U^U'), solicit bullet for each
3372 rebulleting each topic at this level."
3385 depth ;;; depth
3386 t ;;; number-control
3387 index ;;; index
3391 ;;;_ > allout-shift-in (arg)
3393 "Increase depth of current heading and any topics collapsed within it.
3395 We disallow shifts that would result in the topic having a depth more than
3396 one level greater than the immediately previous topic, to avoid containment
3397 discontinuity. The first topic in the file can be adjusted to any positive
3398 depth, however."
3418 ;;;_ > allout-shift-out (arg)
3420 "Decrease depth of current heading and any topics collapsed within it.
3422 We disallow shifts that would result in the topic having a depth more than
3423 one level greater than the immediately previous topic, to avoid containment
3424 discontinuity. The first topic in the file can be adjusted to any positive
3425 depth, however."
3430 ;;;_ : Surgery (kill-ring) functions with special provisions for outlines:
3431 ;;;_ > allout-kill-line (&optional arg)
3433 "Kill line, adjusting subsequent lines suitably for outline mode."
3439 binding)
3444 allout-numbered-bullet ; numbers may need adjustment,
3447 ;; Above conditions do not obtain - just do a regular kill:
3449 ;; Ah, have to watch out for adjustments:
3452 binding)
3453 ; Do the kill, presenting option
3454 ; for read-only text:
3456 ; Provide some feedback:
3459 ; Start with the topic
3460 ; following killed line:
3464 ;; condition case handler:
3472 ;; ensure prior kill-ring leader is properly restored:
3474 ;; Aborted kill got pushed on front - ditch it:
3477 got)
3478 ;; Aborted kill got appended to prior - resurrect prior:
3480 ;; make last-command skip this failed command, so kill-appending
3481 ;; conditions track:
3485 binding)))
3486 )
3487 )
3488 ;;;_ > allout-kill-topic ()
3490 "Kill topic together with subtopics.
3492 Leaves primary topic's trailing vertical whitespace, if any."
3494 ;; Some finagling is done to make complex topic kills appear faster
3495 ;; than they actually are. A redisplay is performed immediately
3496 ;; after the region is disposed of, though the renumbering process
3497 ;; has yet to be performed. This means that there may appear to be
3498 ;; a lag *after* the kill has been performed.
3506 ;; A blank line - cut it with this topic *unless* this
3507 ;; is the last topic at this level, in which case
3508 ;; we'll leave the blank line as part of the
3509 ;; containing topic:
3519 ;;;_ > allout-yank-processing ()
3522 "Incidental outline-specific business to be done just after text yanks.
3524 Does depth adjustment of yanked topics, when:
3526 1 the stuff being yanked starts with a valid outline header prefix, and
3527 2 it is being yanked at the end of a line which consists of only a valid
3528 topic prefix.
3530 Also, adjusts numbering of subsequent siblings when appropriate.
3532 Depth adjustment alters the depth of all the topics being yanked
3533 the amount it takes to make the first topic have the depth of the
3534 header into which it's being yanked.
3536 The point is left in front of yanked, adjusted topics, rather than
3537 at the end (and vice-versa with the mark). Non-adjusted yanks,
3538 however, are left exactly like normal, non-allout-specific yanks."
3541 ; Get to beginning, leaving
3542 ; region around subject:
3547 ;; 'resituate' if yanking an entire topic into topic header:
3552 ;; `rectify-numbering' if resituating (where several topics may
3553 ;; be resituating) or yanking a topic into a topic slot (bol):
3557 ; The yanked stuff is a topic:
3562 ;; Nil if adjustment unnecessary, otherwise depth to which
3563 ;; adjustment should be made:
3576 done
3580 ; Do the adjustment:
3585 ; Trim off excessive blank
3586 ; line at end, if any:
3590 ; Work backwards, with each
3591 ; shallowest level,
3592 ; successively excluding the
3593 ; last processed topic from
3594 ; the narrow region:
3597 ; go as high as we can in each bunch:
3601 subj-depth))
3608 ;; Preserve new bullet if it's a distinctive one, otherwise
3609 ;; use old one:
3611 allout-distinctive-bullets-string)
3612 ; Delete from bullet of old to
3613 ; before bullet of new:
3620 ; Delete base subj prefix,
3621 ; leaving old one:
3623 prefix-len
3625 ; and delete residual subj
3626 ; prefix digits and space:
3633 ; Give some preliminary feedback:
3635 ; ... and renumber, in case necessary:
3640 nil ;;; number-control
3641 nil ;;; index
3642 t))
3646 ;;;_ > allout-yank (&optional arg)
3648 "`allout-mode' yank, with depth and numbering adjustment of yanked topics.
3650 Non-topic yanks work no differently than normal yanks.
3652 If a topic is being yanked into a bare topic prefix, the depth of the
3653 yanked topic is adjusted to the depth of the topic prefix.
3655 1 we're yanking in an `allout-mode' buffer
3656 2 the stuff being yanked starts with a valid outline header prefix, and
3657 3 it is being yanked at the end of a line which consists of only a valid
3658 topic prefix.
3660 If these conditions hold then the depth of the yanked topics are all
3661 adjusted the amount it takes to make the first one at the depth of the
3662 header into which it's being yanked.
3664 The point is left in front of yanked, adjusted topics, rather than
3665 at the end (and vice-versa with the mark). Non-adjusted yanks,
3666 however, (ones that don't qualify for adjustment) are handled
3667 exactly like normal yanks.
3669 Numbering of yanked topics, and the successive siblings at the depth
3670 into which they're being yanked, is adjusted.
3672 `allout-yank-pop' works with `allout-yank' just like normal `yank-pop'
3673 works with normal `yank' in non-outline buffers."
3680 ;;;_ > allout-yank-pop (&optional arg)
3682 "Yank-pop like `allout-yank' when popping to bare outline prefixes.
3684 Adapts level of popped topics to level of fresh prefix.
3686 Note - prefix changes to distinctive bullets will stick, if followed
3687 by pops to non-distinctive yanks. Bug..."
3695 ;;;_ - Specialty bullet functions
3696 ;;;_ : File Cross references
3697 ;;;_ > allout-resolve-xref ()
3699 "Pop to file associated with current heading, if it has an xref bullet.
3701 \(Works according to setting of `allout-file-xref-bullet')."
3708 allout-file-xref-bullet)
3720 ; A registry-files ref, strip the `:'
3721 ; and try to follow it:
3728 file-name))
3734 )
3735 )
3736 )
3737 )
3739 ;;;_ #6 Exposure Control
3741 ;;;_ - Fundamental
3742 ;;;_ > allout-flag-region (from to flag)
3744 "Hide or show lines from FROM to TO, via Emacs selective-display FLAG char.
3745 Ie, text following flag C-m \(carriage-return) is hidden until the
3746 next C-j (newline) char.
3748 Returns the endpoint of the region."
3749 ;; "OFR-" prefixes to avoid collisions with vars in code calling the macro.
3750 ;; ie, elisp macro vars are not 'hygenic', so distinct names are necessary.
3754 trans)
3763 flag t)
3764 ;; adjust character read-protection on all the affected lines.
3765 ;; we handle the region line-by-line.
3772 ;; handle from start of exposed to beginning of hidden, or eol:
3775 nil t)
3779 ;; handle from start of hidden, if any, to eol:
3783 ;; Handle the end-of-line to beginning of next line:
3788 )
3793 )
3794 )
3795 )
3796 ;;;_ > allout-flag-current-subtree (flag)
3798 "Hide or show subtree of currently-visible topic.
3800 See `allout-flag-region' for more details."
3808 ;;;_ - Topic-specific
3809 ;;;_ > allout-show-entry ()
3811 "Like `allout-show-current-entry', reveals entries nested in hidden topics.
3813 This is a way to give restricted peek at a concealed locality without the
3814 expense of exposing its context, but can leave the outline with aberrant
3815 exposure. `allout-hide-current-entry-completely' or `allout-show-offshoot'
3816 should be used after the peek to rectify the exposure."
3821 beg end)
3826 ;; We're on topic head line - show only it:
3828 ;; or we're in body - include it:
3832 ;;;_ > allout-show-children (&optional level strict)
3835 "If point is visible, show all direct subheadings of this heading.
3837 Otherwise, do `allout-show-to-offshoot', and then show subheadings.
3839 Optional LEVEL specifies how many levels below the current level
3840 should be shown, or all levels if t. Default is 1.
3842 Optional STRICT means don't resort to -show-to-offshoot, no matter
3843 what. This is basically so -show-to-offshoot, which is called by
3844 this function, can employ the pure offspring-revealing capabilities of
3845 it.
3847 Returns point at end of subtree that was opened, if any. (May get a
3848 point of non-opened subtree?)"
3856 ; expose it.
3857 ;; Then recurse, but with "strict" set so we don't
3858 ;; infinite regress:
3868 ;; Concealed root would already have been taken care of,
3869 ;; unless strict was set.
3882 ;;;_ > allout-hide-point-reconcile ()
3884 "Like `allout-hide-current-entry'; hides completely if within hidden region.
3886 Specifically intended for aberrant exposure states, like entries that were
3887 exposed by `allout-show-entry' but are within otherwise concealed regions."
3897 ;;;_ > allout-show-to-offshoot ()
3899 "Like `allout-show-entry', but reveals all concealed ancestors, as well.
3901 As with `allout-hide-current-entry-completely', useful for rectifying
3902 aberrant exposure states produced by `allout-show-entry'."
3909 bag-it)
3913 ;; Oops, we're not making any progress! Show the current
3914 ;; topic completely, and bag this try.
3921 "allout-show-to-offshoot: "
3928 ;;;_ > allout-hide-current-entry ()
3930 "Hide the body directly following this heading."
3937 ;;;_ > allout-show-current-entry (&optional arg)
3940 "Show body following current heading, or hide the entry if repeat count."
3949 )))
3950 ;;;_ > allout-hide-current-entry-completely ()
3951 ; ... allout-hide-current-entry-completely also for isearch dynamic exposure:
3953 "Like `allout-hide-current-entry', but conceal topic completely.
3955 Specifically intended for aberrant exposure states, like entries that were
3956 exposed by `allout-show-entry' but are within otherwise concealed regions."
3966 ;;;_ > allout-show-current-subtree (&optional arg)
3968 "Show everything within the current topic. With a repeat-count,
3969 expose this topic and its siblings."
3973 ;; Outside any topics - try to get to the first:
3976 ;; got to first, outermost topic - set to expose it and siblings:
3983 ;;;_ > allout-hide-current-subtree (&optional just-close)
3985 "Close the current topic, or containing topic if this one is already closed.
3987 If this topic is closed and it's a top level topic, close this topic
3988 and its siblings.
3990 If optional arg JUST-CLOSE is non-nil, do not treat the parent or
3991 siblings, even if the target topic is already closed."
4005 ;; Structure didn't change - try hiding current level:
4008 t
4015 nil)
4019 ;;;_ > allout-show-current-branches ()
4021 "Show all subheadings of this heading, but not their bodies."
4025 ;;;_ > allout-hide-current-leaves ()
4027 "Hide the bodies of the current topic and all its offspring."
4033 ;;;_ - Region and beyond
4034 ;;;_ > allout-show-all ()
4036 "Show all of the text in the buffer."
4041 ;;;_ > allout-hide-bodies ()
4043 "Hide all of buffer except headings."
4046 ;;;_ > allout-hide-region-body (start end)
4048 "Hide all body lines in the region, but not headings."
4061 ;;;_ > allout-expose-topic (spec)
4063 "Apply exposure specs to successive outline topic items.
4065 Use the more convenient frontend, `allout-new-exposure', if you don't
4066 need evaluation of the arguments, or even better, the `allout-layout'
4067 variable-keyed mode-activation/auto-exposure feature of allout outline
4068 mode. See the respective documentation strings for more details.
4070 Cursor is left at start position.
4072 SPEC is either a number or a list.
4074 Successive specs on a list are applied to successive sibling topics.
4076 A simple spec \(either a number, one of a few symbols, or the null
4077 list) dictates the exposure for the corresponding topic.
4079 Non-null lists recursively designate exposure specs for respective
4080 subtopics of the current topic.
4082 The `:' repeat spec is used to specify exposure for any number of
4083 successive siblings, up to the trailing ones for which there are
4084 explicit specs following the `:'.
4086 Simple (numeric and null-list) specs are interpreted as follows:
4088 Numbers indicate the relative depth to open the corresponding topic.
4089 - negative numbers force the topic to be closed before opening to the
4090 absolute value of the number, so all siblings are open only to
4091 that level.
4092 - positive numbers open to the relative depth indicated by the
4093 number, but do not force already opened subtopics to be closed.
4094 - 0 means to close topic - hide all offspring.
4095 : - `repeat'
4096 apply prior element to all siblings at current level, *up to*
4097 those siblings that would be covered by specs following the `:'
4098 on the list. Ie, apply to all topics at level but the last
4099 ones. \(Only first of multiple colons at same level is
4100 respected - subsequent ones are discarded.)
4101 * - completely opens the topic, including bodies.
4102 + - shows all the sub headers, but not the bodies
4103 - - exposes the body of the corresponding topic.
4105 Examples:
4106 \(allout-expose-topic '(-1 : 0))
4107 Close this and all following topics at current level, exposing
4108 only their immediate children, but close down the last topic
4109 at this current level completely.
4110 \(allout-expose-topic '(-1 () : 1 0))
4111 Close current topic so only the immediate subtopics are shown;
4112 show the children in the second to last topic, and completely
4113 close the last one.
4114 \(allout-expose-topic '(-2 : -1 *))
4115 Expose children and grandchildren of all topics at current
4116 level except the last two; expose children of the second to
4117 last and completely open the last one."
4121 nil
4124 prev-elem curr-elem
4125 stay done
4126 snug-back
4127 )
4144 ;; Expand the `repeat' spec to an explicit version,
4145 ;; w.r.t. remaining siblings:
4147 ;; Dang - could be nice to make use of the chart, sigh:
4151 ;; Some residue - cover it with prev-elem:
4153 spec)))))))
4158 nil
4161 allout-recent-end-of-subtree)))))
4173 ;; Capitalize on max-pos state to get us nearer next sibling:
4177 max-pos)))
4178 ;;;_ > allout-old-expose-topic (spec &rest followers)
4181 "Deprecated. Use `allout-expose-topic' \(with different schema
4182 format) instead.
4184 Dictate wholesale exposure scheme for current topic, according to SPEC.
4186 SPEC is either a number or a list. Optional successive args
4187 dictate exposure for subsequent siblings of current topic.
4189 A simple spec (either a number, a special symbol, or the null list)
4190 dictates the overall exposure for a topic. Non null lists are
4191 composite specs whose first element dictates the overall exposure for
4192 a topic, with the subsequent elements in the list interpreted as specs
4193 that dictate the exposure for the successive offspring of the topic.
4195 Simple (numeric and null-list) specs are interpreted as follows:
4197 - Numbers indicate the relative depth to open the corresponding topic:
4198 - negative numbers force the topic to be close before opening to the
4199 absolute value of the number.
4200 - positive numbers just open to the relative depth indicated by the number.
4201 - 0 just closes
4202 - `*' completely opens the topic, including bodies.
4203 - `+' shows all the sub headers, but not the bodies
4204 - `-' exposes the body and immediate offspring of the corresponding topic.
4206 If the spec is a list, the first element must be a number, which
4207 dictates the exposure depth of the topic as a whole. Subsequent
4208 elements of the list are nested SPECs, dictating the specific exposure
4209 for the corresponding offspring of the topic.
4211 Optional FOLLOWERS arguments dictate exposure for succeeding siblings."
4215 done
4216 max-pos)
4234 ;(let ((got (allout-old-expose-topic (car spec))))
4235 ; (if (and got (or (not max-pos) (> got max-pos)))
4236 ; (setq max-pos got)))
4238 got)
4255 max-pos))
4256 ;;;_ > allout-new-exposure '()
4258 "Literal frontend for `allout-expose-topic', doesn't evaluate arguments.
4259 Some arguments that would need to be quoted in `allout-expose-topic'
4260 need not be quoted in `allout-new-exposure'.
4262 Cursor is left at start position.
4264 Use this instead of obsolete `allout-exposure'.
4266 Examples:
4267 \(allout-new-exposure (-1 () () () 1) 0)
4268 Close current topic at current level so only the immediate
4269 subtopics are shown, except also show the children of the
4270 third subtopic; and close the next topic at the current level.
4271 \(allout-new-exposure : -1 0)
4272 Close all topics at current level to expose only their
4273 immediate children, except for the last topic at the current
4274 level, in which even its immediate children are hidden.
4275 \(allout-new-exposure -2 : -1 *)
4276 Expose children and grandchildren of first topic at current
4277 level, and expose children of subsequent topics at current
4278 level *except* for the last, which should be opened completely."
4285 ;;;_ #7 Systematic outline presentation - copying, printing, flattening
4287 ;;;_ - Mapping and processing of topics
4288 ;;;_ ( See also Subtree Charting, in Navigation code.)
4289 ;;;_ > allout-stringify-flat-index (flat-index)
4291 "Convert list representing section/subsection/... to document string.
4293 Optional arg CONTEXT indicates interior levels to include."
4295 result
4296 numstr
4298 ;; Take care of the explicit context:
4307 ;; Take care of the indentation:
4315 1
4317 ? )
4318 result)))
4320 ;; Dispose of single extra delim:
4323 ;;;_ > allout-stringify-flat-index-plain (flat-index)
4325 "Convert list representing section/subsection/... to document string."
4327 result)
4334 ;;;_ > allout-stringify-flat-index-indented (flat-index)
4336 "Convert list representing section/subsection/... to document string."
4338 result
4339 numstr)
4340 ;; Take care of the explicit context:
4347 ;; Take care of the indentation:
4355 1
4357 ? )
4358 result)))
4360 ;; Dispose of single extra delim:
4363 ;;;_ > allout-listify-exposed (&optional start end format)
4366 "Produce a list representing exposed topics in current region.
4368 This list can then be used by `allout-process-exposed' to manipulate
4369 the subject region.
4371 Optional START and END indicate bounds of region.
4373 optional arg, FORMAT, designates an alternate presentation form for
4374 the prefix:
4376 list - Present prefix as numeric section.subsection..., starting with
4377 section indicated by the list, innermost nesting first.
4378 `indent' \(symbol) - Convert header prefixes to all white space,
4379 except for distinctive bullets.
4381 The elements of the list produced are lists that represents a topic
4382 header and body. The elements of that list are:
4384 - a number representing the depth of the topic,
4385 - a string representing the header-prefix, including trailing whitespace and
4386 bullet.
4387 - a string representing the bullet character,
4388 - and a series of strings, each containing one line of the exposed
4389 portion of the topic entry."
4394 ;; state vars:
4396 next done)
4400 ;; Goto initial topic, and register preceeding stuff, if any:
4402 ;; First topic follows beginning point - register preliminary stuff:
4424 beg
4425 ;To hidden text or end of line:
4434 strings))
4438 ;; Accumulate list for this topic:
4445 allout-distinctive-bullets-string)
4446 bullet)))
4451 gone-out)
4453 format))
4454 strings
4455 special))
4461 strings)
4464 strings)))
4468 result))
4469 ;; Reasses format, if any:
4477 ; Pop the residue:
4481 ; And increment the current one:
4486 ;; Put the list with first at front, to last at back:
4488 ;;;_ > my-region-active-p ()
4493 ;;;_ > allout-process-exposed (&optional func from to frombuf
4494 ;;; tobuf format)
4497 "Map function on exposed parts of current topic; results to another buffer.
4499 All args are options; default values itemized below.
4501 Apply FUNCTION to exposed portions FROM position TO position in buffer
4502 FROMBUF to buffer TOBUF. Sixth optional arg, FORMAT, designates an
4503 alternate presentation form:
4505 `flat' - Present prefix as numeric section.subsection..., starting with
4506 section indicated by the start-num, innermost nesting first.
4507 X`flat-indented' - Prefix is like `flat' for first topic at each
4508 X level, but subsequent topics have only leaf topic
4509 X number, padded with blanks to line up with first.
4510 `indent' \(symbol) - Convert header prefixes to all white space,
4511 except for distinctive bullets.
4513 Defaults:
4514 FUNCTION: `allout-insert-listified'
4515 FROM: region start, if region active, else start of buffer
4516 TO: region end, if region active, else end of buffer
4517 FROMBUF: current buffer
4519 FORMAT: nil"
4521 ; Resolve arguments,
4522 ; defaulting if necessary:
4530 ;; Specified but not a buffer - get it:
4534 frombuf
4537 ;; not specified - default it:
4542 ;; not specified - default it:
4554 ;;;_ - Copy exposed
4555 ;;;_ > allout-insert-listified (listified)
4557 "Insert contents of listified outline portion in current buffer.
4559 LISTIFIED is a list representing each topic header and body:
4561 \`(depth prefix text)'
4563 or \`(depth prefix text bullet-plus)'
4565 If `bullet-plus' is specified, it is inserted just after the entire prefix."
4581 ;;;_ > allout-copy-exposed-to-buffer (&optional arg tobuf format)
4583 "Duplicate exposed portions of current outline to another buffer.
4587 With repeat count, copy the exposed parts of only the current topic.
4589 Optional second arg TOBUF is target buffer name.
4591 Optional third arg FORMAT, if non-nil, symbolically designates an
4592 alternate presentation format for the outline:
4594 `flat' - Convert topic header prefixes to numeric
4595 section.subsection... identifiers.
4596 `indent' - Convert header prefixes to all white space, except for
4597 distinctive bullets.
4598 `indent-flat' - The best of both - only the first of each level has
4599 the full path, the rest have only the section number
4600 of the leaf, preceded by the right amount of indentation."
4617 beg
4618 end
4620 tobuf
4621 format start-list)
4625 ;;;_ > allout-flatten-exposed-to-buffer (&optional arg tobuf)
4627 "Present numeric outline of outline's exposed portions in another buffer.
4629 The resulting outline is not compatible with outline mode - use
4630 `allout-copy-exposed-to-buffer' if you want that.
4632 Use `allout-indented-exposed-to-buffer' for indented presentation.
4634 With repeat count, copy the exposed portions of only current topic.
4637 it, unless optional second arg TOBUF is specified, in which case it is
4638 used verbatim."
4641 ;;;_ > allout-indented-exposed-to-buffer (&optional arg tobuf)
4643 "Present indented outline of outline's exposed portions in another buffer.
4645 The resulting outline is not compatible with outline mode - use
4646 `allout-copy-exposed-to-buffer' if you want that.
4648 Use `allout-flatten-exposed-to-buffer' for numeric sectional presentation.
4650 With repeat count, copy the exposed portions of only current topic.
4653 it, unless optional second arg TOBUF is specified, in which case it is
4654 used verbatim."
4658 ;;;_ - LaTeX formatting
4659 ;;;_ > allout-latex-verb-quote (string &optional flow)
4661 "Return copy of STRING for literal reproduction across LaTeX processing.
4662 Expresses the original characters \(including carriage returns) of the
4663 string across LaTeX processing."
4670 string
4672 ;;;_ > allout-latex-verbatim-quote-curr-line ()
4674 "Express line for exact \(literal) representation across LaTeX processing.
4676 Adjust line contents so it is unaltered \(from the original line)
4677 across LaTeX processing, within the context of a `verbatim'
4678 environment. Leaves point at the end of the line."
4684 ;;"\\\\\\|\\{\\|\\}\\|\\_\\|\\$\\|\\\"\\|\\&\\|\\^\\|\\-\\|\\*\\|#"
4685 end ; bounded by end-of-line
4691 ;;;_ > allout-insert-latex-header (buffer)
4693 "Insert initial LaTeX commands at point in BUFFER."
4694 ;; Much of this is being derived from the stuff in appendix of E in
4695 ;; the TeXBook, pg 421.
4710 allout-title-style))
4712 allout-label-style))
4714 allout-head-line-style))
4716 allout-body-line-style))
4720 allout-indent
4728 allout-line-skip
4735 allout-line-skip
4751 page-numbering
4752 titlecmd
4753 labelcmd
4754 headlinecmd
4755 bodylinecmd
4756 setlength
4757 oneheadline
4758 onebodyline
4759 begindoc
4760 title
4761 hsize
4762 hoffset
4763 vspace)
4764 )))
4765 ;;;_ > allout-insert-latex-trailer (buffer)
4767 "Insert concluding LaTeX commands at point in BUFFER."
4770 ;;;_ > allout-latexify-one-item (depth prefix bullet text)
4772 "Insert LaTeX commands for formatting one outline item.
4774 Args are the topics numeric DEPTH, the header PREFIX lead string, the
4775 BULLET string, and a list of TEXT strings for the body."
4779 body-content bop)
4780 ; Do the head line:
4783 "\1}{"
4784 depth
4791 nil
4792 ;;(insert "\\beginlines\n")
4799 ; Mangle any occurrences of
4800 ; "\end{verbatim}" in text,
4801 ; it's special:
4805 ">"
4807 ;;(insert "|" (car body-lines) "|")
4817 ;;(insert "\\endlines\n")
4819 )))
4820 ;;;_ > allout-latexify-exposed (arg &optional tobuf)
4822 "Format current topics exposed portions to TOBUF for LaTeX processing.
4823 TOBUF defaults to a buffer named the same as the current buffer, but
4826 With repeat count, copy the exposed portions of entire buffer."
4841 beg
4842 end
4843 buf
4844 tobuf)
4851 ;;;_ #8 Encryption
4852 ;;;_ > allout-toggle-current-subtree-encryption (&optional fetch-pass)
4854 "Encrypt clear text or decrypt encoded topic contents \(body and subtopics.)
4856 Optional FETCH-PASS universal argument provokes key-pair encryption with
4857 single universal argument. With doubled universal argument \(value = 16),
4858 it forces prompting for the passphrase regardless of availability from the
4859 passphrase cache. With no universal argument, the appropriate passphrase
4860 for the is obtained from the cache, if available, else from the user.
4862 Currently only GnuPG encryption is supported.
4864 \**NOTE WELL** that the encrypted text must be ascii-armored. For gnupg
4865 encryption, include the option ``armor'' in your ~/.gnupg/gpg.conf file.
4867 Both symmetric-key and key-pair encryption is implemented. Symmetric is
4868 the default, use a single \(x4) universal argument for keypair mode.
4870 Encrypted topic's bullet is set to a `~' to signal that the contents of the
4871 topic \(body and subtopics, but not heading) is pending encryption or
4872 encrypted. `*' asterisk immediately after the bullet signals that the body
4873 is encrypted, its' absence means the topic is meant to be encrypted but is
4874 not. When a file with topics pending encryption is saved, topics pending
4875 encryption are encrypted. See allout-encrypt-unencrypted-on-saves for
4876 auto-encryption specifics.
4878 \**NOTE WELL** that automatic encryption that happens during saves will
4879 default to symmetric encryption - you must manually \(re)encrypt key-pair
4880 encrypted topics if you want them to continue to use the key-pair cipher.
4882 Level-1 topics, with prefix consisting solely of an `*' asterisk, cannot be
4883 encrypted. If you want to encrypt the contents of a top-level topic, use
4886 Passphrase Caching
4888 The encryption passphrase is solicited if not currently available in the
4889 passphrase cache from a recent encryption action.
4891 The solicited passphrase is retained for reuse in a buffer-specific cache
4892 for some set period of time \(default, 60 seconds), after which the string
4893 is nulled. The passphrase cache timeout is customized by setting
4894 `pgg-passphrase-cache-expiry'.
4896 Symmetric Passphrase Hinting and Verification
4898 If the file previously had no associated passphrase, or had a different
4899 passphrase than specified, the user is prompted to repeat the new one for
4900 corroboration. A random string encrypted by the new passphrase is set on
4901 the buffer-specific variable `allout-passphrase-verifier-string', for
4902 confirmation of the passphrase when next obtained, before encrypting or
4903 decrypting anything with it. This helps avoid mistakenly shifting between
4904 keys.
4906 If allout customization var `allout-passphrase-verifier-handling' is
4907 non-nil, an entry for `allout-passphrase-verifier-string' and its value is
4908 added to an Emacs 'local variables' section at the end of the file, which
4909 is created if necessary. That setting is for retention of the passphrase
4910 verifier across emacs sessions.
4912 Similarly, `allout-passphrase-hint-string' stores a user-provided reminder
4913 about their passphrase, and `allout-passphrase-hint-handling' specifies
4914 when the hint is presented, or if passphrase hints are disabled. If
4915 enabled \(see the `allout-passphrase-hint-handling' docstring for details),
4916 the hint string is stored in the local-variables section of the file, and
4917 solicited whenever the passphrase is changed."
4928 ;; Asses location:
4935 nil
4941 subtree-end))
4948 ;; Assess key parameters:
4950 ;; detect the type by which it is already encrypted
4959 result-text)
4964 for-key-type for-key-identity fetch-pass))
4966 ;; Replace the subtree with the processed product.
4974 ;; adjust trailling-blank-lines to preserve topic spacing:
4979 ;; Ensure that the item has an encrypted-entry bullet:
4982 allout-topic-encryption-bullet))
4987 ;; Remove the is-encrypted bullet qualifier:
4990 ;; Add the is-encrypted bullet qualifier:
4993 )
4994 )
4995 )
4996 )
4997 )
4998 ;;;_ > allout-encrypt-string (text decrypt allout-buffer key-type for-key
4999 ;;; fetch-pass &optional retried verifying
5000 ;;; passphrase)
5002 fetch-pass &optional retried verifying
5003 passphrase)
5004 "Encrypt or decrypt message TEXT.
5006 If DECRYPT is true (default false), then decrypt instead of encrypt.
5008 FETCH-PASS (default false) forces fresh prompting for the passphrase.
5010 KEY-TYPE indicates whether to use a 'symmetric or 'keypair cipher.
5012 FOR-KEY is human readable identification of the first of the user's
5013 eligible secret keys a keypair decryption targets, or else nil.
5015 Optional RETRIED is for internal use - conveys the number of failed keys
5016 that have been solicited in sequence leading to this current call.
5018 Optional PASSPHRASE enables explicit delivery of the decryption passphrase,
5019 for verification purposes.
5021 Returns the resulting string, or nil if the transformation fails."
5031 scheme))
5038 key-type
5040 target-prompt-id
5042 target-prompt-id))))
5044 work-buffer result result-text status)
5047 ;; Force later fetch by evicting passphrase from the cache.
5052 ;; Obtain the passphrase if we don't already have one and we're not
5053 ;; doing a keypair encryption:
5059 target-cache-id
5060 target-prompt-id
5061 key-type
5062 allout-buffer
5063 retried fetch-pass)))
5070 ;; symmetric:
5078 passphrase)))
5082 ;; failed - handle passphrase caching
5089 ;; encrypt 'keypair:
5102 ;; decrypt 'keypair:
5112 )
5117 ;; validate result - non-empty
5120 nil
5121 ;; transform was fruitless, retry w/new passphrase.
5125 passphrase)))
5127 ;; Barf if encryption yields extraordinary control chars:
5130 result-text))
5134 ;; valid result and just verifying or non-symmetric:
5138 passphrase t))
5139 result-text)
5141 ;; valid result and regular symmetric - "register"
5142 ;; passphrase with mnemonic aids/cache.
5147 passphrase t))
5149 allout-buffer)
5150 result-text)
5151 )
5152 )
5153 )
5154 )
5155 )
5156 ;;;_ > allout-obtain-passphrase (for-key cache-id prompt-id key-type
5157 ;;; allout-buffer retried fetch-pass)
5159 allout-buffer retried fetch-pass)
5160 "Obtain passphrase for a key from the cache or else from the user.
5162 When obtaining from the user, symmetric-cipher passphrases are verified
5163 against either, if available and enabled, a random string that was
5164 encrypted against the passphrase, or else against repeated entry by the
5165 user for corroboration.
5167 FOR-KEY is the key for which the passphrase is being obtained.
5169 CACHE-ID is the cache id of the key for the passphrase.
5171 PROMPT-ID is the id for use when prompting the user.
5173 KEY-TYPE is either 'symmetric or 'keypair.
5175 ALLOUT-BUFFER is the buffer containing the entry being en/decrypted.
5177 RETRIED is the number of this attempt to obtain this passphrase.
5179 FETCH-PASS causes the passphrase to be solicited from the user, regardless
5180 of the availability of a cached copy."
5183 ;; do regular passphrase read on non-symmetric passphrase:
5186 pgg-default-scheme
5191 cache-id t)
5193 ;; Symmetric hereon:
5201 retried)))
5206 prompt-id retry-message))
5208 prompt-id hint retry-message))
5217 confirmation)
5220 nil
5222 ;; Duplicate our handle on the passphrase so it's not clobbered by
5223 ;; deactivate-passwd memory clearing:
5229 allout-buffer 'symmetric
5231 got-pass)
5238 ;; deactivate password for subsequent
5239 ;; confirmation:
5243 nil)
5244 t))
5247 ;; No verifier string - force confirmation by repetition of
5248 ;; (new) passphrase:
5251 ;; confirmation vs new input - doing pgg-read-passphrase will do the
5252 ;; right thing, in either case:
5257 cache-id t)))
5260 confirmation
5265 ;; recurse to this routine:
5269 ;; reduce opportunity for memory cherry-picking by zeroing duplicate:
5272 )
5273 )
5274 )
5275 )
5276 )
5277 ;;;_ > allout-encrypted-topic-p ()
5279 "True if the current topic is encryptable and encrypted."
5283 allout-topic-encryption-bullet)
5285 )
5286 )
5287 ;;;_ > allout-encrypted-key-info (text)
5288 ;; XXX gpg-specific, alas
5290 "Return a pair of the key type and identity of a recipient's secret key.
5292 The key type is one of 'symmetric or 'keypair.
5294 if 'keypair, and some of the user's secret keys are among those for which
5295 the message was encoded, return the identity of the first. otherwise,
5296 return nil for the second item of the pair.
5298 An error is raised if the text is not encrypted."
5305 'symmetric
5307 secret-keys first-secret-key for-key-owner)
5311 secret-keys)
5314 first-secret-key))))
5316 )
5317 )
5318 )
5319 )
5320 ;;;_ > allout-create-encryption-passphrase-verifier (passphrase)
5322 "Encrypt random message for later validation of symmetric key's passphrase."
5323 ;; use 20 random ascii characters, across the entire ascii range.
5330 )
5331 ;;;_ > allout-update-passphrase-mnemonic-aids (for-key passphrase
5332 ;;; outline-buffer)
5334 outline-buffer)
5335 "Update passphrase verifier and hint strings if necessary.
5337 See `allout-passphrase-verifier-string' and `allout-passphrase-hint-string'
5338 settings.
5340 PASSPHRASE is the passphrase being mnemonicized
5342 OUTLINE-BUFFER is the buffer of the outline being adjusted.
5344 These are used to help the user keep track of the passphrase they use for
5345 symmetric encryption in the file.
5347 Behavior is governed by `allout-passphrase-verifier-handling',
5348 `allout-passphrase-hint-handling', and also, controlling whether the values
5349 are preserved on Emacs local file variables,
5350 `allout-enable-file-variable-adjustment'."
5352 ;; If passphrase doesn't agree with current verifier:
5353 ;; - adjust the verifier
5354 ;; - if passphrase hint handling is enabled, adjust the passphrase hint
5355 ;; - if file var settings are enabled, adjust the file vars
5358 for-key passphrase outline-buffer)))
5361 ;; Collapse to a single line and enclose in string quotes:
5364 passphrase))))
5365 new-hint)
5367 ;; do the passphrase hint first, since it's interactive
5372 allout-passphrase-hint-string))
5376 allout-passphrase-hint-string)))
5380 allout-passphrase-verifier-string))
5381 )
5382 )
5383 )
5384 ;;;_ > allout-get-encryption-passphrase-verifier ()
5386 "Return text of the encrypt passphrase verifier, unmassaged, or nil if none.
5388 Derived from value of `allout-file-passphrase-verifier-string'."
5391 allout-passphrase-verifier-string)))
5393 ;; Return it uncollapsed
5395 )
5396 )
5397 ;;;_ > allout-verify-passphrase (key passphrase allout-buffer)
5399 "True if passphrase successfully decrypts verifier, nil otherwise.
5405 allout-passphrase-verifier-string
5409 t)))
5410 ;;;_ > allout-next-topic-pending-encryption (&optional except-mark)
5412 "Return the point of the next topic pending encryption, or nil if none.
5414 EXCEPT-MARK identifies a point whose containing topics should be excluded
5415 from encryption. This supports 'except-current mode of
5416 `allout-encrypt-unencrypted-on-saves'.
5418 Such a topic has the allout-topic-encryption-bullet without an
5419 immediately following '*' that would mark the topic as being encrypted. It
5420 must also have content."
5428 nil t))
5430 done t)
5441 done t))
5445 done t))
5455 ;; Continue looking
5457 ;; Got it!
5459 )
5460 )
5463 )
5464 )
5465 ;;;_ > allout-encrypt-decrypted (&optional except-mark)
5467 "Encrypt topics pending encryption except those containing exemption point.
5469 EXCEPT-MARK identifies a point whose containing topics should be excluded
5470 from encryption. This supports 'except-current mode of
5471 `allout-encrypt-unencrypted-on-saves'.
5473 If a topic that is currently being edited was encrypted, we return a list
5474 containing the location of the topic and the location of the cursor just
5475 before the topic was encrypted. This can be used, eg, to decrypt the topic
5476 and exactly resituate the cursor if this is being done as part of a file
5477 save. See `allout-encrypt-unencrypted-on-saves' for more info."
5482 was-modified
5483 bo-subtree
5484 editing-topic editing-point)
5490 allout-encrypt-unencrypted-on-saves
5492 ;; Not collapsed:
5498 ;; we had to wait for this 'til now so prior topics are
5499 ;; encrypted, any relevant text shifts are in place:
5504 )
5508 )
5509 )
5510 )
5512 ;;;_ #9 miscellaneous
5513 ;;;_ > allout-mark-topic ()
5515 "Put the region around topic currently containing point."
5522 ;;;_ > outlineify-sticky ()
5523 ;; outlinify-sticky is correct spelling; provide this alias for sticklers:
5524 ;;;###autoload
5526 ;;;###autoload
5528 "Activate outline mode and establish file var so it is started subsequently.
5530 See doc-string for `allout-layout' and `allout-init' for details on
5531 setup for auto-startup."
5540 t
5546 ;;;_ > allout-file-vars-section-data ()
5548 "Return data identifying the file-vars section, or nil if none.
5550 Returns list `(beginning-point prefix-string suffix-string)'."
5551 ;; minimally gleaned from emacs 21.4 files.el hack-local-variables function.
5558 nil
5569 beg))
5571 )
5572 )
5573 )
5574 ;;;_ > allout-adjust-file-variable (varname value)
5576 "Adjust the setting of an emacs file variable named VARNAME to VALUE.
5578 This activity is inhibited if either `enable-local-variables'
5579 `allout-enable-file-variable-adjustment' are nil.
5581 When enabled, an entry for the variable is created if not already present,
5582 or changed if established with a different value. The section for the file
5583 variables, itself, is created if not already present. When created, the
5584 section lines \(including the section line) exist as second-level topics in
5585 a top-level topic at the end of the file.
5587 enable-local-variables must be true for any of this to happen."
5589 allout-enable-file-variable-adjustment))
5590 nil
5593 beg prefix suffix)
5598 ;; create the section
5606 suffix ""
5610 beg))
5615 )
5616 ;; look for existing entry or create one, leaving point for insertion
5617 ;; of new value:
5633 )
5634 )
5635 )
5636 )
5637 ;;;_ > solicit-char-in-string (prompt string &optional do-defaulting)
5639 "Solicit (with first arg PROMPT) choice of a character from string STRING.
5641 Optional arg DO-DEFAULTING indicates to accept empty input (CR)."
5644 got)
5649 ;; We do our own reading here, so we can circumvent, eg, special
5650 ;; treatment for `?' character. (Oughta use minibuffer keymap instead.)
5657 ;; Return empty string to default:
5662 got
5663 " ...pick from: "
5664 string
5666 nil))))
5667 ;; got something out of loop - return it:
5668 got)
5669 )
5670 ;;;_ > regexp-sans-escapes (string)
5672 "Return a copy of REGEXP with all character escapes stripped out.
5675 single backslash.
5677 Optional arg SUCCESSIVE-BACKSLASHES is used internally for recursion."
5680 ""
5681 ;; Set successive-backslashes to number if current char is
5682 ;; backslash, or else to nil:
5686 nil))
5688 ;; Include first char:
5691 ;; Exclude first char, but maintain count:
5693 ;;;_ - add-hook definition for divergent emacsen
5694 ;;;_ > add-hook (hook function &optional append)
5697 "Add to the value of HOOK the function FUNCTION unless already present.
5698 \(It becomes the first hook on the list unless optional APPEND is non-nil, in
5699 which case it becomes the last). HOOK should be a symbol, and FUNCTION may be
5700 any valid function. HOOK's value should be a list of functions, not a single
5701 function. If HOOK is void, it is first set to nil."
5704 ;; Clever way to tell whether a given lambda-expression
5705 ;; is equal to anything in the hook.
5713 ;;;_ > subst-char-in-string if necessary
5716 "Replace FROMCHAR with TOCHAR in STRING each time it occurs.
5717 Unless optional argument INPLACE is non-nil, return a new string."
5724 newstr)))
5725 ;;;_ : my-mark-marker to accommodate divergent emacsen:
5727 "Accommodate the different signature for `mark-marker' across Emacsen.
5729 XEmacs takes two optional args, while mainline GNU Emacs does not,
5730 so pass them along when appropriate."
5735 ;;;_ #10 Under development
5736 ;;;_ > allout-bullet-isearch (&optional bullet)
5738 "Isearch \(regexp) for topic with bullet BULLET."
5742 "ISearch for topic with bullet: "
5747 allout-header-prefix
5749 bullet)))
5752 ;;;_ ? Re hooking up with isearch - use isearch-op-fun rather than
5753 ;;; wrapping the isearch functions.
5755 ;;;_* Local emacs vars.
5756 ;;; The following `allout-layout' local variable setting:
5757 ;;; - closes all topics from the first topic to just before the third-to-last,
5758 ;;; - shows the children of the third to last (config vars)
5759 ;;; - and the second to last (code section),
5760 ;;; - and closes the last topic (this local-variables section).
5761 ;;;Local variables:
5762 ;;;allout-layout: (0 : -1 -1 0)
5763 ;;;End:
5765 ;;; arch-tag: cf38fbc3-c044-450f-8bff-afed8ba5681c
5766 ;;; allout.el ends here