Index: allout.el =================================================================== RCS file: /sources/emacs/emacs/lisp/allout.el,v retrieving revision 1.89 diff -u -u -r1.89 allout.el --- allout.el 15 Nov 2006 16:34:20 -0000 1.89 +++ allout.el 29 Nov 2006 20:40:25 -0000 @@ -1651,90 +1651,109 @@ navigation and exposure. It also is specifically aimed at accommodating syntax-sensitive text like programming languages. \(For an example, see the allout code itself, which is organized as an allout -outline.) +outline.\) -In addition to outline navigation and exposure, allout includes: +In addition to typical outline navigation and exposure, allout includes: - - topic-oriented repositioning, promotion/demotion, cut, and paste - - integral outline exposure-layout + - topic-oriented authoring, including keystroke-based topic creation, + repositioning, promotion/demotion, cut, and paste - incremental search with dynamic exposure and reconcealment of hidden text - - automatic topic-number maintenance + - adjustable format, so programming code can be developed in outline-structure - easy topic encryption and decryption - - \"Hot-spot\" operation, for single-keystroke maneuvering and - exposure control. \(See the allout-mode docstring.) + - \"Hot-spot\" operation, for single-keystroke maneuvering and exposure control + - integral outline layout, for automatic initial exposure when visiting a file + - independent extensibility, using comprehensive exposure and authoring hooks and many other features. -Below is a description of the bindings, and then explanation of +Below is a description of the key bindings, and then explanation of special `allout-mode' features and terminology. See also the outline menubar additions for quick reference to many of the features, and see the docstring of the function `allout-init' for instructions on priming your emacs session for automatic activation of `allout-mode'. - -The bindings are dictated by the `allout-keybindings-list' and -`allout-command-prefix' variables. - - Navigation: Exposure Control: - ---------- ---------------- -\\[allout-next-visible-heading] allout-next-visible-heading | \\[allout-hide-current-subtree] allout-hide-current-subtree -\\[allout-previous-visible-heading] allout-previous-visible-heading | \\[allout-show-children] allout-show-children -\\[allout-up-current-level] allout-up-current-level | \\[allout-show-current-subtree] allout-show-current-subtree -\\[allout-forward-current-level] allout-forward-current-level | \\[allout-show-current-entry] allout-show-current-entry -\\[allout-backward-current-level] allout-backward-current-level | \\[allout-show-all] allout-show-all -\\[allout-end-of-entry] allout-end-of-entry -\\[allout-beginning-of-current-entry] allout-beginning-of-current-entry, alternately, goes to hot-spot - - Topic Header Production: - ----------------------- -\\[allout-open-sibtopic] allout-open-sibtopic Create a new sibling after current topic. -\\[allout-open-subtopic] allout-open-subtopic ... an offspring of current topic. -\\[allout-open-supertopic] allout-open-supertopic ... a sibling of the current topic's parent. - - Topic Level and Prefix Adjustment: - --------------------------------- -\\[allout-shift-in] allout-shift-in Shift current topic and all offspring deeper. -\\[allout-shift-out] allout-shift-out ... less deep. -\\[allout-rebullet-current-heading] allout-rebullet-current-heading Prompt for alternate bullet for - current topic. -\\[allout-rebullet-topic] allout-rebullet-topic Reconcile bullets of topic and its offspring - - distinctive bullets are not changed, others - alternated according to nesting depth. -\\[allout-number-siblings] allout-number-siblings Number bullets of topic and siblings - the - offspring are not affected. With repeat - count, revoke numbering. - - Topic-oriented Killing and Yanking: - ---------------------------------- -\\[allout-kill-topic] allout-kill-topic Kill current topic, including offspring. -\\[allout-copy-topic-as-kill] allout-copy-topic-as-kill Copy current topic, including offspring. -\\[allout-kill-line] allout-kill-line kill-line, attending to outline structure. -\\[allout-copy-line-as-kill] allout-copy-line-as-kill Copy line but don't delete it. -\\[allout-yank] allout-yank Yank, adjusting depth of yanked topic to - depth of heading if yanking into bare topic - heading (ie, prefix sans text). -\\[allout-yank-pop] allout-yank-pop Is to allout-yank as yank-pop is to yank - - Topic-oriented Encryption: - ------------------------- -\\[allout-toggle-current-subtree-encryption] allout-toggle-current-subtree-encryption Encrypt/Decrypt topic content - - Misc commands: - ------------- -M-x outlineify-sticky Activate outline mode for current buffer, - and establish a default file-var setting - for `allout-layout'. -\\[allout-mark-topic] allout-mark-topic -\\[allout-copy-exposed-to-buffer] allout-copy-exposed-to-buffer - Duplicate outline, sans concealed text, to - buffer with name derived from derived from that - of current buffer - \"*BUFFERNAME exposed*\". -\\[allout-flatten-exposed-to-buffer] allout-flatten-exposed-to-buffer - Like above 'copy-exposed', but convert topic - prefixes to section.subsection... numeric - format. -\\[eval-expression] (allout-init t) Setup Emacs session for outline mode - auto-activation. +The bindings are dictated by the customizable `allout-keybindings-list' +variable. We recommend customizing `allout-command-prefix' to use just +`\\C-c' as the command prefix, if the allout bindings don't conflict with +any personal bindings you have on \\C-c. In any case, outline structure +navigation and authoring is simplified by positioning the cursor on an +item's bullet character, the \"hot-spot\" - then you can invoke allout +commands with just the un-prefixed, un-control-shifted command letters. +This is described further in the HOT-SPOT Operation section. + + Exposure Control: + ---------------- +\\[allout-hide-current-subtree] `allout-hide-current-subtree' +\\[allout-show-children] `allout-show-children' +\\[allout-show-current-subtree] `allout-show-current-subtree' +\\[allout-show-current-entry] `allout-show-current-entry' +\\[allout-show-all] `allout-show-all' + + Navigation: + ---------- +\\[allout-next-visible-heading] `allout-next-visible-heading' +\\[allout-previous-visible-heading] `allout-previous-visible-heading' +\\[allout-up-current-level] `allout-up-current-level' +\\[allout-forward-current-level] `allout-forward-current-level' +\\[allout-backward-current-level] `allout-backward-current-level' +\\[allout-end-of-entry] `allout-end-of-entry' +\\[allout-beginning-of-current-entry] `allout-beginning-of-current-entry' \(alternately, goes to hot-spot\) +\\[allout-beginning-of-line] `allout-beginning-of-line' - like regular beginning-of-line, but + if immediately repeated cycles to the beginning of the current item + and then to the hot-spot \(if `allout-beginning-of-line-cycles' is set\). + + + Topic Header Production: + ----------------------- +\\[allout-open-sibtopic] `allout-open-sibtopic' Create a new sibling after current topic. +\\[allout-open-subtopic] `allout-open-subtopic' ... an offspring of current topic. +\\[allout-open-supertopic] `allout-open-supertopic' ... a sibling of the current topic's parent. + + Topic Level and Prefix Adjustment: + --------------------------------- +\\[allout-shift-in] `allout-shift-in' Shift current topic and all offspring deeper +\\[allout-shift-out] `allout-shift-out' ... less deep +\\[allout-rebullet-current-heading] `allout-rebullet-current-heading' Prompt for alternate bullet for + current topic +\\[allout-rebullet-topic] `allout-rebullet-topic' Reconcile bullets of topic and + its' offspring - distinctive bullets are not changed, others + are alternated according to nesting depth. +\\[allout-number-siblings] `allout-number-siblings' Number bullets of topic and siblings - + the offspring are not affected. + With repeat count, revoke numbering. + + Topic-oriented Killing and Yanking: + ---------------------------------- +\\[allout-kill-topic] `allout-kill-topic' Kill current topic, including offspring. +\\[allout-copy-topic-as-kill] `allout-copy-topic-as-kill' Copy current topic, including offspring. +\\[allout-kill-line] `allout-kill-line' kill-line, attending to outline structure. +\\[allout-copy-line-as-kill] `allout-copy-line-as-kill' Copy line but don't delete it. +\\[allout-yank] `allout-yank' Yank, adjusting depth of yanked topic to + depth of heading if yanking into bare topic + heading \(ie, prefix sans text\). +\\[allout-yank-pop] `allout-yank-pop' Is to allout-yank as yank-pop is to yank + + Topic-oriented Encryption: + ------------------------- +\\[allout-toggle-current-subtree-encryption] `allout-toggle-current-subtree-encryption' + Encrypt/Decrypt topic content + + Misc commands: + ------------- +M-x outlineify-sticky Activate outline mode for current buffer, + and establish a default file-var setting + for `allout-layout'. +\\[allout-mark-topic] `allout-mark-topic' +\\[allout-copy-exposed-to-buffer] `allout-copy-exposed-to-buffer' + Duplicate outline, sans concealed text, to + buffer with name derived from derived from that + of current buffer - \"*BUFFERNAME exposed*\". +\\[allout-flatten-exposed-to-buffer] `allout-flatten-exposed-to-buffer' + Like above 'copy-exposed', but convert topic + prefixes to section.subsection... numeric + format. +\\[eval-expression] \(allout-init t\) Setup Emacs session for outline mode + auto-activation. Topic Encryption @@ -1742,108 +1761,136 @@ symmetric and key-pair modes, passphrase timeout, passphrase consistency checking, user-provided hinting for symmetric key mode, and auto-encryption of topics pending encryption on save. -\(Topics pending encryption are, by default, automatically -encrypted during file saves; if you're editing the contents of -such a topic, it is automatically decrypted for continued -editing.) The aim is reliable topic privacy while preventing -accidents like neglected encryption before saves, forgetting -which passphrase was used, and other practical pitfalls. -See `allout-toggle-current-subtree-encryption' function docstring and -`allout-encrypt-unencrypted-on-saves' customization variable for details. +Topics pending encryption are, by default, automatically +encrypted during file saves. If the contents of the topic +containing the cursor was encrypted for a save, it is +automatically decrypted for continued editing. + +The aim of these measures is reliable topic privacy while +preventing accidents like neglected encryption before saves, +forgetting which passphrase was used, and other practical +pitfalls. + +See `allout-toggle-current-subtree-encryption' function docstring +and `allout-encrypt-unencrypted-on-saves' customization variable +for details. - HOT-SPOT Operation + HOT-SPOT Operation Hot-spot operation provides a means for easy, single-keystroke outline navigation and exposure control. When the text cursor is positioned directly on the bullet character of -a topic, regular characters (a to z) invoke the commands of the +a topic, regular characters \(a to z\) invoke the commands of the corresponding allout-mode keymap control chars. For example, \"f\" would invoke the command typically bound to \"C-cC-f\" -\(\\[allout-forward-current-level] `allout-forward-current-level'). +\(\\[allout-forward-current-level] `allout-forward-current-level'\). Thus, by positioning the cursor on a topic bullet, you can execute the outline navigation and manipulation commands with a -single keystroke. Regular navigation keys (eg, \\[forward-char], \\[next-line]) never get +single keystroke. Regular navigation keys \(eg, \\[forward-char], \\[next-line]\) don't get this special translation, so you can use them to get out of the -hot-spot and back to normal operation. +hot-spot and back to normal editing operation. -Note that the command `allout-beginning-of-current-entry' \(\\[allout-beginning-of-current-entry]\) -will move to the hot-spot when the cursor is already located at the -beginning of the current entry, so you usually can hit \\[allout-beginning-of-current-entry] -twice in a row to get to the hot-spot. +In allout-mode, the normal beginning-of-line command \(\\[allout-beginning-of-line]]\) is +replaced with one that makes it easy to get to the hot-spot. If you +repeat it immediately it cycles \(if `allout-beginning-of-line-cycles' +is set\) to the beginning of the item and then, if you hit it again +immediately, to the hot-spot. Similarly, `allout-beginning-of-current-entry' +\(\\[allout-beginning-of-current-entry]\) moves to the hot-spot when the cursor is already located +at the beginning of the current entry. + + Extending Allout + +Allout exposure and authoring activites all have associated +hooks, by which independent code can cooperate with allout +without changes to the allout core. Here are key ones: + +`allout-mode-hook' +`allout-mode-deactivate-hook' +`allout-exposure-change-hook' +`allout-structure-added-hook' +`allout-structure-deleted-hook' +`allout-structure-shifted-hook' - Terminology + Terminology Topic hierarchy constituents - TOPICS and SUBTOPICS: -TOPIC: A basic, coherent component of an Emacs outline. It can - contain and be contained by other topics. -CURRENT topic: - The visible topic most immediately containing the cursor. -DEPTH: The degree of nesting of a topic; it increases with - containment. Also called the: -LEVEL: The same as DEPTH. +ITEM: A unitary outline element, including the HEADER and ENTRY text. +TOPIC: An ITEM and any ITEMs contained within it, ie having greater DEPTH + and with no intervening items of lower DEPTH than the container. +CURRENT ITEM: + The visible ITEM most immediately containing the cursor. +DEPTH: The degree of nesting of an ITEM; it increases with containment. + The DEPTH is determined by the HEADER PREFIX. The DEPTH is also + called the: +LEVEL: The same as DEPTH. ANCESTORS: - The topics that contain a topic. -PARENT: A topic's immediate ancestor. It has a depth one less than - the topic. + Those ITEMs whose TOPICs contain an ITEM. +PARENT: An ITEM's immediate ANCESTOR. It has a DEPTH one less than that + of the ITEM. OFFSPRING: - The topics contained by a topic; + The ITEMs contained within an ITEM's TOPIC. SUBTOPIC: - An immediate offspring of a topic; -CHILDREN: - The immediate offspring of a topic. + An OFFSPRING of its ANCESTOR TOPICs. +CHILD: + An immediate SUBTOPIC of its PARENT. SIBLINGS: - Topics having the same parent and depth. + TOPICs having the same PARENT and DEPTH. Topic text constituents: -HEADER: The first line of a topic, include the topic PREFIX and header - text. -PREFIX: The leading text of a topic which distinguishes it from normal - text. It has a strict form, which consists of a prefix-lead - string, padding, and a bullet. The bullet may be followed by a +HEADER: The first line of an ITEM, include the ITEM PREFIX and HEADER + text. +ENTRY: The text content of an ITEM, before any OFFSPRING, but including + the HEADER text and distinct from the ITEM PREFIX. +BODY: Same as ENTRY. +PREFIX: The leading text of an ITEM which distinguishes it from normal + ENTRY text. Allout recognizes the outline structure according + to the strict PREFIX format. It consists of a PREFIX-LEAD string, + PREFIX-PADDING, and a BULLET. The BULLET might be followed by a number, indicating the ordinal number of the topic among its - siblings, a space, and then the header text. + siblings, or an asterisk indicating encryption, plus an optional + space. After that is the ITEM HEADER text, which is not part of + the PREFIX. - The relative length of the PREFIX determines the nesting depth - of the topic. + The relative length of the PREFIX determines the nesting DEPTH + of the ITEM. PREFIX-LEAD: - The string at the beginning of a topic prefix, normally a `.'. - It can be customized by changing the setting of - `allout-header-prefix' and then reinitializing `allout-mode'. - - By setting the prefix-lead to the comment-string of a - programming language, you can embed outline structuring in - program code without interfering with the language processing - of that code. See `allout-use-mode-specific-leader' - docstring for more detail. + The string at the beginning of a HEADER PREFIX, by default a `.'. + It can be customized by changing the setting of + `allout-header-prefix' and then reinitializing `allout-mode'. + + When the PREFIX-LEAD is set to the comment-string of a + programming language, outline structuring can be embedded in + program code without interfering with processing of the text + \(by emacs or the language processor\) as program code. This + setting happens automatically when allout mode is used in + programming-mode buffers. See `allout-use-mode-specific-leader' + docstring for more detail. PREFIX-PADDING: - Spaces or asterisks which separate the prefix-lead and the - bullet, determining the depth of the topic. -BULLET: A character at the end of the topic prefix, it must be one of - the characters listed on `allout-plain-bullets-string' or - `allout-distinctive-bullets-string'. (See the documentation - for these variables for more details.) The default choice of - bullet when generating topics varies in a cycle with the depth of - the topic. -ENTRY: The text contained in a topic before any offspring. -BODY: Same as ENTRY. - + Spaces or asterisks which separate the PREFIX-LEAD and the + bullet, determining the ITEM's DEPTH. +BULLET: A character at the end of the ITEM PREFIX, it must be one of + the characters listed on `allout-plain-bullets-string' or + `allout-distinctive-bullets-string'. \(See the documentation + for these variables for more details.\) The default choice of + BULLET when generating ITEMs varies in a cycle with the DEPTH of + the ITEM. EXPOSURE: - The state of a topic which determines the on-screen visibility - of its offspring and contained text. + The state of a TOPIC which determines the on-screen visibility + of its OFFSPRING and contained ENTRY text. CONCEALED: - Topics and entry text whose display is inhibited. Contiguous - units of concealed text is represented by `...' ellipses. + TOPICs and ENTRY text whose EXPOSURE is inhibited. Concealed + text is represented by \"...\" ellipses. - Concealed topics are effectively collapsed within an ancestor. -CLOSED: A topic whose immediate offspring and body-text is concealed. -OPEN: A topic that is not closed, though its offspring or body may be." + CONCEALED TOPICs are effectively collapsed within an ANCESTOR. +CLOSED: A TOPIC whose immediate OFFSPRING and body-text is CONCEALED. +OPEN: A TOPIC that is not CLOSED, though its OFFSPRING or BODY may be." ;;;_ . Code (interactive "P") @@ -1934,22 +1981,8 @@ extend)) ;; Produce map from current version of allout-keybindings-list: - (setq allout-mode-map - (produce-allout-mode-map allout-keybindings-list)) - (substitute-key-definition 'beginning-of-line - 'allout-beginning-of-line - allout-mode-map global-map) - (substitute-key-definition 'move-beginning-of-line - 'allout-beginning-of-line - allout-mode-map global-map) - (substitute-key-definition 'end-of-line - 'allout-end-of-line - allout-mode-map global-map) - (substitute-key-definition 'move-end-of-line - 'allout-end-of-line - allout-mode-map global-map) + (allout-setup-mode-map) (produce-allout-mode-menubar-entries) - (fset 'allout-mode-map allout-mode-map) ;; Include on minor-mode-map-alist, if not already there: (if (not (member '(allout-mode . allout-mode-map) @@ -2039,6 +2072,28 @@ allout-mode ) ; let* ) ; defun +(defun allout-setup-mode-map () + "Establish allout-mode bindings." + (setq-default allout-mode-map + (produce-allout-mode-map allout-keybindings-list)) + (setq allout-mode-map + (produce-allout-mode-map allout-keybindings-list)) + (substitute-key-definition 'beginning-of-line + 'allout-beginning-of-line + allout-mode-map global-map) + (substitute-key-definition 'move-beginning-of-line + 'allout-beginning-of-line + allout-mode-map global-map) + (substitute-key-definition 'end-of-line + 'allout-end-of-line + allout-mode-map global-map) + (substitute-key-definition 'move-end-of-line + 'allout-end-of-line + allout-mode-map global-map) + (fset 'allout-mode-map allout-mode-map)) +;; ensure that allout-mode-map has some setting even if allout-mode hasn't +;; been invoked: +(allout-setup-mode-map) ;;;_ > allout-minor-mode (defalias 'allout-minor-mode 'allout-mode) @@ -2887,19 +2942,31 @@ (if (interactive-p) (allout-end-of-prefix)) (and last-ascended allout-recent-depth)))) ;;;_ > allout-ascend () -(defun allout-ascend () - "Ascend one level, returning t if successful, nil if not." +(defun allout-ascend (&optional dont-move-if-unsuccessful) + "Ascend one level, returning resulting depth if successful, nil if not. + +Point is left at the beginning of the level whether or not +successful, unless optional DONT-MOVE-IF-UNSUCCESSFUL is set, in +which case point is returned to its original starting location." + (if dont-move-if-unsuccessful + (setq dont-move-if-unsuccessful (point))) (prog1 (if (allout-beginning-of-level) (let ((bolevel (point)) (bolevel-depth allout-recent-depth)) (allout-previous-heading) - (if (< allout-recent-depth bolevel-depth) - allout-recent-depth - ;; some topic after file's first is at lower depth than first: - (goto-char bolevel) - (allout-depth) - nil))) + (cond ((< allout-recent-depth bolevel-depth) + allout-recent-depth) + ((= allout-recent-depth bolevel-depth) + (if dont-move-if-unsuccessful + (goto-char dont-move-if-unsuccessful)) + (allout-depth) + nil) + (t + ;; some topic after very first is lower depth than first: + (goto-char bolevel) + (allout-depth) + nil)))) (if (interactive-p) (allout-end-of-prefix)))) ;;;_ > allout-descend-to-depth (depth) (defun allout-descend-to-depth (depth) @@ -4445,7 +4512,7 @@ (while more (allout-back-to-current-heading) ; go as high as we can in each bunch: - (while (allout-ascend)) + (while (allout-ascend t)) (save-excursion (allout-unprotected (allout-rebullet-topic-grunt (- adjust-to-depth