Function: `allout-mode`

allout-mode is an autoloaded, interactive and byte-compiled function defined in allout.el.gz.

Signature

(allout-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 the variable allout-mode(var)/allout-mode(fun).

The mode's hook is called both when the mode is enabled and when it is disabled.

Probably introduced at or before Emacs version 22.1.

Key Bindings

Aliases

allout-minor-mode

Source Code