Function: allout-minor-mode
allout-minor-mode is a function alias and interactive for allout-mode(var)/allout-mode(fun),
defined in allout.el.gz.
Signature
(allout-minor-mode &optional ARG)
Documentation
Toggle Allout outline mode.
Allout outline mode is a minor mode that provides extensive outline oriented formatting and manipulation. It enables structural editing of outlines, as well as navigation and exposure. It also is specifically aimed at accommodating syntax-sensitive text like programming languages. (For example, see the allout code itself, which is organized as an allout outline.)
In addition to typical outline navigation and exposure, allout includes:
- topic-oriented authoring, including keystroke-based topic creation,
repositioning, promotion/demotion, cut, and paste
- incremental search with dynamic exposure and reconcealment of hidden text
- adjustable format, so programming code can be developed in outline-structure
- easy topic encryption and decryption, symmetric or key-pair
- "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 key bindings, and then description
of special allout-mode(var)/allout-mode(fun) features and terminology. See also the
outline menubar additions for quick reference to many of the
features. Customize allout-auto-activation to prepare your
Emacs session for automatic activation of allout-mode(var)/allout-mode(fun).
The bindings are those listed in allout-prefixed-keybindings
and allout-unprefixed-keybindings. 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:
----------------
C-c SPC h (allout-hide-current-subtree) allout-hide-current-subtree
C-c SPC TAB (allout-show-children) allout-show-children
C-c SPC C-s (allout-show-current-subtree) allout-show-current-subtree
C-c SPC C-o (allout-show-current-entry) allout-show-current-entry
C-c SPC ! (allout-show-all) allout-show-all
Navigation:
----------
C-c SPC C-n (allout-next-visible-heading) allout-next-visible-heading
C-c SPC C-p (allout-previous-visible-heading) allout-previous-visible-heading
C-c SPC C-u (allout-up-current-level) allout-up-current-level
C-c SPC C-f (allout-forward-current-level) allout-forward-current-level
C-c SPC C-b (allout-backward-current-level) allout-backward-current-level
C-c SPC C-e (allout-end-of-entry) allout-end-of-entry
C-c SPC C-a (allout-beginning-of-current-entry) allout-beginning-of-current-entry (alternately, goes to hot-spot)
C-a (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:
-----------------------
C-c SPC SPC (allout-open-sibtopic) allout-open-sibtopic Create a new sibling after current topic.
C-c SPC . (allout-open-subtopic) allout-open-subtopic ... an offspring of current topic.
C-c SPC , (allout-open-supertopic) allout-open-supertopic ... a sibling of the current topic's parent.
Topic Level and Prefix Adjustment:
---------------------------------
C-c SPC > (allout-shift-in) allout-shift-in Shift current topic and all offspring deeper
C-c SPC < (allout-shift-out) allout-shift-out ... less deep
C-c SPC * (allout-rebullet-current-heading) allout-rebullet-current-heading Prompt for alternate bullet for
current topic
C-c SPC RET (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.
C-c SPC # (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:
----------------------------------
C-c SPC C-k (allout-kill-topic) allout-kill-topic Kill current topic, including offspring.
C-c SPC M-k (allout-copy-topic-as-kill) allout-copy-topic-as-kill Copy current topic, including offspring.
C-k (allout-kill-line) allout-kill-line Kill line, attending to outline structure.
M-k (allout-copy-line-as-kill) allout-copy-line-as-kill Copy line but don't delete it.
C-y (allout-yank) allout-yank Yank, adjusting depth of yanked topic to
depth of heading if yanking into bare topic
heading (ie, prefix sans text).
M-y (allout-yank-pop) allout-yank-pop Is to allout-yank as yank-pop is to yank.
Topic-oriented Encryption:
-------------------------
C-c SPC x (allout-toggle-current-subtree-encryption) allout-toggle-current-subtree-encryption
Encrypt/Decrypt topic content
Misc commands:
-------------
M-x allout-outlinify-sticky (allout-outlinify-sticky) Activate outline mode for current buffer,
and establish a default file-var setting
for allout-layout.
M-x allout-mark-topic (allout-mark-topic) allout-mark-topic
C-c SPC = c (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*".
C-c SPC = p (allout-flatten-exposed-to-buffer) allout-flatten-exposed-to-buffer
Like above copy-exposed, but convert topic
prefixes to section.subsection... numeric
format.
M-x customize-variable (customize-variable) allout-auto-activation
Prepare Emacs session for allout outline mode
auto-activation.
Topic Encryption
Outline mode supports gpg encryption of topics, with support for symmetric and key-pair modes, and auto-encryption of topics pending encryption on save.
Topics pending encryption are, by default, automatically encrypted during file saves, including checkpoint saves, to avoid exposing the plain text of encrypted topics in the file system. If the content of the topic containing the cursor was encrypted for a save, it is automatically decrypted for continued editing.
NOTE: A few GnuPG v2 versions improperly preserve incorrect
symmetric decryption keys, preventing entry of the correct key on
subsequent decryption attempts until the cache times-out. That
can take several minutes. (Decryption of other entries is not
affected.) Upgrade your EasyPG version, if you can, and you can
deliberately clear your gpg-agent's cache by sending it a -HUP
signal.
See allout-toggle-current-subtree-encryption function docstring
and allout-encrypt-unencrypted-on-saves customization variable
for details.
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
corresponding allout-mode keymap control chars. For example, "f"
would invoke the command typically bound to "C-c<space>C-f"
(C-c SPC C-f (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, C-f (forward-char), C-n (next-line)) don't get
this special translation, so you can use them to get out of the
hot-spot and back to normal editing operation.
In allout-mode, the normal beginning-of-line command (C-a (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
(C-c SPC C-a (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 activities 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-off-hook
allout-exposure-change-functions
allout-structure-added-functions
allout-structure-deleted-functions
allout-structure-shifted-functions
allout-after-copy-or-kill-hook
allout-post-undo-hook
Terminology
Topic hierarchy constituents -- TOPICS and SUBTOPICS:
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:
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 ITEMs contained within an ITEM's TOPIC.
SUBTOPIC:
An OFFSPRING of its ANCESTOR TOPICs.
CHILD:
An immediate SUBTOPIC of its PARENT.
SIBLINGS:
TOPICs having the same PARENT and DEPTH.
Topic text constituents:
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, 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 ITEM.
PREFIX-LEAD:
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(var)/allout-mode(fun).
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 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. When creating a TOPIC,
plain BULLETs are by default used, according to the DEPTH of the
TOPIC. Choice among the distinctive BULLETs is offered when you
provide a universal argument (C-u (universal-argument)) to the
TOPIC creation command, or when explicitly rebulleting a TOPIC. The
significance of the various distinctive bullets is purely by
convention. See the documentation for the above bullet strings for
more details.
EXPOSURE:
The state of a TOPIC which determines the on-screen visibility
of its OFFSPRING and contained ENTRY text.
CONCEALED:
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.
This is a minor mode. If called interactively, toggle the
Allout mode mode. If the prefix argument is positive, enable
the mode, and if it is zero or negative, disable the mode.
If called from Lisp, toggle the mode if ARG is toggle. Enable
the mode if ARG is nil, omitted, or is a positive number.
Disable the mode if ARG is a negative number.
To check whether the minor mode is enabled in the current buffer,
evaluate allout-mode(var)/allout-mode(fun).
The mode's hook is called both when the mode is enabled and when it is disabled.
Key Bindings