allout.el

;;; allout.el --- extensive outline mode for use alone and with other modes

;; Copyright (C) 1992-1994, 2001-2011  Free Software Foundation, Inc.

;; Author: Ken Manheimer <ken dot manheimer at gmail...>
;; Maintainer: Ken Manheimer <ken dot manheimer at gmail...>
;; Created: Dec 1991 -- first release to usenet
;; Version: 2.3
;; Keywords: outlines, wp, languages, PGP, GnuPG
;; Website: http://myriadicity.net/software-and-systems/craft/emacs-allout

;; This file is part of GNU Emacs.

;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.

;;; Commentary:

;; Allout outline minor mode provides extensive outline formatting and
;; and manipulation beyond standard emacs outline mode.  Some features:
;;
;;  - Classic outline-mode topic-oriented navigation and exposure adjustment
;;  - Topic-oriented editing including coherent topic and subtopic
;;    creation, promotion, demotion, cut/paste across depths, etc.
;;  - Incremental search with dynamic exposure and reconcealment of text
;;  - Customizable bullet format -- enables programming-language specific
;;    outlining, for code-folding editing.  (Allout code itself is to try it;
;;    formatted as an outline -- do ESC-x eval-buffer in allout.el; but
;;    emacs local file variables need to be enabled when the
;;    file was visited -- see `enable-local-variables'.)
;;  - Configurable per-file initial exposure settings
;;  - Symmetric-key and key-pair topic encryption.  Encryption is via the
;;    Emacs 'epg' library.  See allout-toggle-current-subtree-encryption
;;    docstring.
;;  - Automatic topic-number maintenance
;;  - "Hot-spot" operation, for single-keystroke maneuvering and
;;    exposure control (see the allout-mode docstring)
;;  - Easy rendering of exposed portions into numbered, latex, indented, etc
;;    outline styles
;;  - Careful attention to whitespace -- enabling blank lines between items
;;    and maintenance of hanging indentation (in paragraph auto-fill and
;;    across topic promotion and demotion) of topic bodies consistent with
;;    indentation of their topic header.
;;
;; and more.
;;
;; See the `allout-mode' function's docstring for an introduction to the
;; mode.
;;
;; Directions to the latest development version and helpful notes are
;; available at http://myriadicity.net/Sundry/EmacsAllout .
;;
;; The outline menubar additions provide quick reference to many of the
;; features.  See the docstring of the variables `allout-layout' and
;; `allout-auto-activation' for details on automatic activation of
;; `allout-mode' as a minor mode.  (`allout-init' is deprecated in favor of
;; a purely customization-based method.)
;;
;; Note -- the lines beginning with `;;;_' are outline topic headers.
;;        Customize `allout-auto-activation' to enable, then revisit this
;;        buffer to give it a whirl.

;; ken manheimer (ken dot manheimer at gmail dot com)

;;; Code:

;;;_* Dependency loads
(require 'overlay)
(eval-when-compile
  ;; Most of the requires here are for stuff covered by autoloads, which
  ;; byte-compiling doesn't trigger.
  (require 'epg)
  (require 'epa)
  (require 'overlay)
  ;; `cl' is required for `assert'.  `assert' is not covered by a standard
  ;; autoload, but it is a macro, so that eval-when-compile is sufficient
  ;; to byte-compile it in, or to do the require when the buffer evalled.
  (require 'cl)
  )

;;;_* USER CUSTOMIZATION VARIABLES:

;;;_ > defgroup allout, allout-keybindings
(defgroup allout nil
  "Extensive outline minor-mode, for use stand-alone and with other modes.

See Allout Auto Activation for automatic activation."
  :prefix "allout-"
  :group 'outlines)
(defgroup allout-keybindings nil
  "Allout outline mode keyboard bindings configuration."
  :group 'allout)

;;;_ + Layout, Mode, and Topic Header Configuration

(defvar allout-command-prefix)          ; defined below

;;;_  > allout-keybindings incidentals:
;;;_   : internal key binding stuff - in this section for load-order.
;;;_    = allout-mode-map
(defvar allout-mode-map 'allout-mode-map
  "Keybindings place-holder for (allout) outline minor mode.

Do NOT set the value of this variable.  Instead, customize
`allout-command-prefix', `allout-prefixed-keybindings', and
`allout-unprefixed-keybindings'.")
;;;_    = allout-mode-map-value
(defvar allout-mode-map-value nil
  "Keymap for allout outline minor mode.

Do NOT set the value of this variable.  Instead, customize
`allout-command-prefix', `allout-prefixed-keybindings', and
`allout-unprefixed-keybindings'.")
;;;_    = make allout-mode-map-value an alias for allout-mode-map:
;; this needs to be revised when the value is changed, sigh.
(defalias 'allout-mode-map allout-mode-map-value)
;;;_   > allout-compose-and-institute-keymap (&optional varname value)
(defun allout-compose-and-institute-keymap (&optional varname value)
  "Create the allout keymap according to the keybinding specs, and set it.

Useful standalone or to effect customizations of the
respective allout-mode keybinding variables, `allout-command-prefix',
`allout-prefixed-keybindings', and `allout-unprefixed-keybindings'"
  ;; Set the customization variable, if any:
  (when varname
    (set-default varname value))
  (let ((map (make-sparse-keymap)))
    (when (boundp 'allout-prefixed-keybindings)
      ;; tolerate first definitions of the variables:
      (dolist (entry allout-prefixed-keybindings)
        (define-key map
          ;; XXX vector vs non-vector key descriptions?
          (vconcat allout-command-prefix
                   (car (read-from-string (car entry))))
          (cadr entry))))
    (when (boundp 'allout-unprefixed-keybindings)
      (dolist (entry allout-unprefixed-keybindings)
        (define-key map (car (read-from-string (car entry))) (cadr entry))))
    (substitute-key-definition 'beginning-of-line 'allout-beginning-of-line
                               map global-map)
    (substitute-key-definition 'move-beginning-of-line 'allout-beginning-of-line
                               map global-map)
    (substitute-key-definition 'end-of-line 'allout-end-of-line
                               map global-map)
    (substitute-key-definition 'move-end-of-line 'allout-end-of-line
                               map global-map)
    (allout-institute-keymap map)))
;;;_  > allout-institute-keymap (map)
(defun allout-institute-keymap (map)
  "Associate allout-mode bindings with allout as a minor mode."
  ;; Architecture:
  ;; allout-mode-map var is a keymap by virtue of being a defalias for
  ;; allout-mode-map-value, which has the actual keymap value.
  ;; allout-mode-map's symbol value is just 'allout-mode-map, so it can be
  ;; used in minor-mode-map-alist to indirect to the actual
  ;; allout-mode-map-var value, which can be adjusted and reassigned.

  ;; allout-mode-map-value for keymap reference in various places:
  (setq allout-mode-map-value map)
  ;; the function value keymap of allout-mode-map is used in
  ;; minor-mode-map-alist - update it:
  (fset allout-mode-map allout-mode-map-value))
;;;_  * initialize the mode map:
;; ensure that allout-mode-map has some setting even if allout-mode hasn't
;; been invoked:
(allout-compose-and-institute-keymap)
;;;_   = allout-command-prefix
(defcustom allout-command-prefix "\C-c "
  "Key sequence to be used as prefix for outline mode command key bindings.

Default is '\C-c<space>'; just '\C-c' is more short-and-sweet, if you're
willing to let allout use a bunch of \C-c keybindings."
  :type 'string
  :group 'allout-keybindings
  :set 'allout-compose-and-institute-keymap)
;;;_   = allout-keybindings-binding
(define-widget 'allout-keybindings-binding 'lazy
  "Structure of allout keybindings customization items."
  :type '(repeat
          (list (string :tag "Key" :value "[(meta control shift ?f)]")
                (function :tag "Function name"
                          :value allout-forward-current-level))))
;;;_   = allout-prefixed-keybindings
(defcustom allout-prefixed-keybindings
  '(("[(control ?n)]" allout-next-visible-heading)
    ("[(control ?p)]" allout-previous-visible-heading)
    ("[(control ?u)]" allout-up-current-level)
    ("[(control ?f)]" allout-forward-current-level)
    ("[(control ?b)]" allout-backward-current-level)
    ("[(control ?a)]" allout-beginning-of-current-entry)
    ("[(control ?e)]" allout-end-of-entry)
    ("[(control ?i)]" allout-show-children)
    ("[(control ?s)]" allout-show-current-subtree)
    ("[(control ?t)]" allout-toggle-current-subtree-exposure)
;; Let user customize if they want to preempt describe-prefix-bindings ^h use.
;;    ("[(control ?h)]" allout-hide-current-subtree)
    ("[?h]" allout-hide-current-subtree)
    ("[(control ?o)]" allout-show-current-entry)
    ("[?!]" allout-show-all)
    ("[?x]" allout-toggle-current-subtree-encryption)
    ("[? ]" allout-open-sibtopic)
    ("[?.]" allout-open-subtopic)
    ("[?,]" allout-open-supertopic)
    ("[?']" allout-shift-in)
    ("[?>]" allout-shift-in)
    ("[?<]" allout-shift-out)
    ("[(control ?m)]" allout-rebullet-topic)
    ("[?*]" allout-rebullet-current-heading)
    ("[?#]" allout-number-siblings)
    ("[(control ?k)]" allout-kill-topic)
    ("[(meta ?k)]" allout-copy-topic-as-kill)
    ("[?@]" allout-resolve-xref)
    ("[?=?c]" allout-copy-exposed-to-buffer)
    ("[?=?i]" allout-indented-exposed-to-buffer)
    ("[?=?t]" allout-latexify-exposed)
    ("[?=?p]" allout-flatten-exposed-to-buffer)
    )
  "Allout-mode key bindings that are prefixed with `allout-command-prefix'.

See `allout-unprefixed-keybindings' for the list of keybindings
that are not prefixed.

Use vector format for the keys:
  - put literal keys after a '?' question mark, eg: '?a', '?.'
  - enclose control, shift, or meta-modified keys as sequences within
    parentheses, with the literal key, as above, preceded by the name(s)
    of the modifiers, eg: [(control ?a)]
See the existing keys for examples.

Functions can be bound to multiple keys, but binding keys to
multiple functions will not work - the last binding for a key
prevails."
  :type 'allout-keybindings-binding
  :group 'allout-keybindings
  :set 'allout-compose-and-institute-keymap
 )
;;;_   = allout-unprefixed-keybindings
(defcustom allout-unprefixed-keybindings
  '(("[(control ?k)]" allout-kill-line)
    ("[(meta ?k)]" allout-copy-line-as-kill)
    ("[(control ?y)]" allout-yank)
    ("[(meta ?y)]" allout-yank-pop)
    )
  "Allout-mode functions bound to keys without any added prefix.

This is in contrast to the majority of allout-mode bindings on
`allout-prefixed-bindings', whose bindings are created with a
preceding command key.

Use vector format for the keys:
  - put literal keys after a '?' question mark, eg: '?a', '?.'
  - enclose control, shift, or meta-modified keys as sequences within
    parentheses, with the literal key, as above, preceded by the name(s)
    of the modifiers, eg: [(control ?a)]
See the existing keys for examples."
  :type 'allout-keybindings-binding
  :group 'allout-keybindings
  :set 'allout-compose-and-institute-keymap
  )

;;;_  > allout-auto-activation-helper (var value)
;;;###autoload
(defun allout-auto-activation-helper (var value)
  "Institute `allout-auto-activation'.

Intended to be used as the `allout-auto-activation' :set function."
  (set-default var value)
  (allout-setup))
;;;_  > allout-setup ()
;;;###autoload
(defun allout-setup ()
  "Do fundamental Emacs session for allout auto-activation.

Establishes allout processing as part of visiting a file if
`allout-auto-activation' is non-nil, or removes it otherwise.

The proper way to use this is through customizing the setting of
`allout-auto-activation'."
  (if (not allout-auto-activation)
      (remove-hook 'find-file-hook 'allout-find-file-hook)
      (add-hook 'find-file-hook 'allout-find-file-hook)))
;;;_  = allout-auto-activation
;;;###autoload
(defcustom allout-auto-activation nil
  "Configure allout outline mode auto-activation.

Control whether and how allout outline mode is automatically
activated when files are visited with non-nil buffer-specific
file variable `allout-layout'.

When allout-auto-activation is \"On\" (t), allout mode is
activated in buffers with non-nil `allout-layout', and the
specified layout is applied.

With value \"ask\", auto-mode-activation is enabled, and endorsement for
performing auto-layout is asked of the user each time.

With value \"activate\", only auto-mode-activation is enabled.
Auto-layout is not.

With value nil, inhibit any automatic allout-mode activation."
  :set 'allout-auto-activation-helper
  ;; FIXME: Using strings here is unusual and less efficient than symbols.
  :type '(choice (const :tag "On" t)
                (const :tag "Ask about layout" "ask")
                (const :tag "Mode only" "activate")
                (const :tag "Off" nil))
  :group 'allout)
(allout-setup)
;;;_  = allout-default-layout
(defcustom allout-default-layout '(-2 : 0)
  "Default allout outline layout specification.

This setting specifies the outline exposure to use when
`allout-layout' has the local value `t'.  This docstring describes the
layout specifications.

A list value specifies a default layout for the current buffer,
to be applied upon activation of `allout-mode'.  Any non-nil
value will automatically trigger `allout-mode', provided
`allout-auto-activation' has been customized to enable it.

The types of elements in the layout specification are:

 INTEGER -- dictate the relative depth to open the corresponding topic(s),
            where:
         -- negative numbers force the topic to be closed before opening
            to the absolute value of the number, so all siblings are open
            only to that level.
         -- positive numbers open to the relative depth indicated by the
            number, but do not force already opened subtopics to be closed.
         -- 0 means to close topic -- hide all subitems.
 :   -- repeat spec -- apply the preceding element to all siblings at
        current level, *up to* those siblings that would be covered by specs
        following the `:' on the list.  Ie, apply to all topics at level but
        trailing ones accounted for by trailing specs.  (Only the first of
        multiple colons at the same level is honored -- later ones are ignored.)
 *   -- completely exposes the topic, including bodies
 +   -- exposes all subtopics, but not the bodies
 -   -- exposes the body of the corresponding topic, but not subtopics
 LIST -- a nested layout spec, to be applied intricately to its
        corresponding item(s)

Examples:
 (-2 : 0)
	Collapse the top-level topics to show their children and
        grandchildren, but completely collapse the final top-level topic.
 (-1 () : 1 0)
	Close the first topic so only the immediate subtopics are shown,
        leave the subsequent topics exposed as they are until the second
	second to last topic, which is exposed at least one level, and
        completely close the last topic.
 (-2 : -1 *)
        Expose children and grandchildren of all topics at current
	level except the last two; expose children of the second to
	last and completely expose the last one, including its subtopics.

See `allout-expose-topic' for more about the exposure process.

Also, allout's mode-specific provisions will make topic prefixes default
to the comment-start string, if any, of the language of the file.  This
is modulo the setting of `allout-use-mode-specific-leader', which see."
  :type 'allout-layout-type
  :group 'allout)
;;;_  : allout-layout-type
(define-widget 'allout-layout-type 'lazy
  "Allout layout format customization basic building blocks."
  :type '(repeat
          (choice (integer :tag "integer (<= zero is strict)")
                  (const :tag ": (repeat prior)" :)
                  (const :tag "* (completely expose)" *)
                  (const :tag "+ (expose all offspring, headlines only)" +)
                  (const :tag "- (expose topic body but not offspring)" -)
                  (allout-layout-type :tag "<Nested layout>"))))

;;;_  = allout-inhibit-auto-fill
(defcustom allout-inhibit-auto-fill nil
  "If non-nil, auto-fill will be inhibited in the allout buffers.

You can customize this setting to set it for all allout buffers, or set it
in individual buffers if you want to inhibit auto-fill only in particular
buffers.  (You could use a function on `allout-mode-hook' to inhibit
auto-fill according, eg, to the major mode.)

If you don't set this and auto-fill-mode is enabled, allout will use the
value that `normal-auto-fill-function', if any, when allout mode starts, or
else allout's special hanging-indent maintaining auto-fill function,
`allout-auto-fill'."
  :type 'boolean
  :group 'allout)
(make-variable-buffer-local 'allout-inhibit-auto-fill)
;;;_  = allout-inhibit-auto-fill-on-headline
(defcustom allout-inhibit-auto-fill-on-headline nil
  "If non-nil, auto-fill will be inhibited while on topic's header line."
  :type 'boolean
  :group 'allout)
(make-variable-buffer-local 'allout-inhibit-auto-fill-on-headline)
;;;_  = allout-use-hanging-indents
(defcustom allout-use-hanging-indents t
  "If non-nil, topic body text auto-indent defaults to indent of the header.
Ie, it is indented to be just past the header prefix.  This is
relevant mostly for use with `indented-text-mode', or other situations
where auto-fill occurs."
  :type 'boolean
  :group 'allout)
(make-variable-buffer-local 'allout-use-hanging-indents)
;;;###autoload
(put 'allout-use-hanging-indents 'safe-local-variable
     (if (fboundp 'booleanp) 'booleanp (lambda (x) (member x '(t nil)))))
;;;_  = allout-reindent-bodies
(defcustom allout-reindent-bodies (if allout-use-hanging-indents
				    'text)
  "Non-nil enables auto-adjust of topic body hanging indent with depth shifts.

When active, topic body lines that are indented even with or beyond
their topic header are reindented to correspond with depth shifts of
the header.

A value of t enables reindent in non-programming-code buffers, ie
those that do not have the variable `comment-start' set.  A value of
`force' enables reindent whether or not `comment-start' is set."
  :type '(choice (const nil) (const t) (const text) (const force))
  :group 'allout)

(make-variable-buffer-local 'allout-reindent-bodies)
;;;###autoload
(put 'allout-reindent-bodies 'safe-local-variable
     (lambda (x) (memq x '(nil t text force))))

;;;_  = allout-show-bodies
(defcustom allout-show-bodies nil
  "If non-nil, show entire body when exposing a topic, rather than
just the header."
  :type 'boolean
  :group 'allout)
(make-variable-buffer-local 'allout-show-bodies)
;;;###autoload
(put 'allout-show-bodies 'safe-local-variable
     (if (fboundp 'booleanp) 'booleanp (lambda (x) (member x '(t nil)))))

;;;_  = allout-beginning-of-line-cycles
(defcustom allout-beginning-of-line-cycles t
  "If non-nil, \\[allout-beginning-of-line] will cycle through smart-placement options.

Cycling only happens on when the command is repeated, not when it
follows a different command.

Smart-placement means that repeated calls to this function will
advance as follows:

 - if the cursor is on a non-headline body line and not on the first column:
   then it goes to the first column
 - if the cursor is on the first column of a non-headline body line:
   then it goes to the start of the headline within the item body
 - if the cursor is on the headline and not the start of the headline:
   then it goes to the start of the headline
 - if the cursor is on the start of the headline:
   then it goes to the bullet character (for hotspot navigation)
 - if the cursor is on the bullet character:
   then it goes to the first column of that line (the headline)
 - if the cursor is on the first column of the headline:
   then it goes to the start of the headline within the item body.

In this fashion, you can use the beginning-of-line command to do
its normal job and then, when repeated, advance through the
entry, cycling back to start.

If this configuration variable is nil, then the cursor is just
advanced to the beginning of the line and remains there on
repeated calls."
  :type 'boolean :group 'allout)
;;;_  = allout-end-of-line-cycles
(defcustom allout-end-of-line-cycles t
  "If non-nil, \\[allout-end-of-line] will cycle through smart-placement options.

Cycling only happens on when the command is repeated, not when it
follows a different command.

Smart placement means that repeated calls to this function will
advance as follows:

 - if the cursor is not on the end-of-line,
   then it goes to the end-of-line
 - if the cursor is on the end-of-line but not the end-of-entry,
   then it goes to the end-of-entry, exposing it if necessary
 - if the cursor is on the end-of-entry,
   then it goes to the end of the head line

In this fashion, you can use the end-of-line command to do its
normal job and then, when repeated, advance through the entry,
cycling back to start.

If this configuration variable is nil, then the cursor is just
advanced to the end of the line and remains there on repeated
calls."
  :type 'boolean :group 'allout)

;;;_  = allout-header-prefix
(defcustom allout-header-prefix "."
;; this string is treated as literal match.  it will be `regexp-quote'd, so
;; one cannot use regular expressions to match varying header prefixes.
  "Leading string which helps distinguish topic headers.

Outline topic header lines are identified by a leading topic
header prefix, which mostly have the value of this var at their front.
Level 1 topics are exceptions.  They consist of only a single
character, which is typically set to the `allout-primary-bullet'."
  :type 'string
  :group 'allout)
(make-variable-buffer-local 'allout-header-prefix)
;;;###autoload
(put 'allout-header-prefix 'safe-local-variable 'stringp)
;;;_  = allout-primary-bullet
(defcustom allout-primary-bullet "*"
  "Bullet used for top-level outline topics.

Outline topic header lines are identified by a leading topic header
prefix, which is concluded by bullets that includes the value of this
var and the respective allout-*-bullets-string vars.

The value of an asterisk (`*') provides for backwards compatibility
with the original Emacs outline mode.  See `allout-plain-bullets-string'
and `allout-distinctive-bullets-string' for the range of available
bullets."
  :type 'string
  :group 'allout)
(make-variable-buffer-local 'allout-primary-bullet)
;;;###autoload
(put 'allout-primary-bullet 'safe-local-variable 'stringp)
;;;_  = allout-plain-bullets-string
(defcustom allout-plain-bullets-string ".,"
  "The bullets normally used in outline topic prefixes.

See `allout-distinctive-bullets-string' for the other kind of
bullets.

DO NOT include the close-square-bracket, `]', as a bullet.

Outline mode has to be reactivated in order for changes to the value
of this var to take effect."
  :type 'string
  :group 'allout)
(make-variable-buffer-local 'allout-plain-bullets-string)
;;;###autoload
(put 'allout-plain-bullets-string 'safe-local-variable 'stringp)
;;;_  = allout-distinctive-bullets-string
(defcustom allout-distinctive-bullets-string "*+-=>()[{}&!?#%\"X@$~_\\:;^"
  "Persistent outline header bullets used to distinguish special topics.

These bullets are distinguish topics with particular character.
They are not used by default in the topic creation routines, but
are offered as options when you modify topic creation with a
universal argument (\\[universal-argument]), or during rebulleting (\\[allout-rebullet-current-heading]).

Distinctive bullets are not cycled when topics are shifted or
otherwise automatically rebulleted, so their marking is
persistent until deliberately changed.  Their significance is
purely by convention, however.  Some conventions suggest
themselves:

 `(' - open paren -- an aside or incidental point
 `?' - question mark -- uncertain or outright question
 `!' - exclamation point/bang -- emphatic
 `[' - open square bracket -- meta-note, about item instead of item's subject
 `\"' - double quote -- a quotation or other citation
 `=' - equal sign -- an assignment, some kind of definition
 `^' - carat -- relates to something above

Some are more elusive, but their rationale may be recognizable:

 `+' - plus -- pending consideration, completion
 `_' - underscore -- done, completed
 `&' - ampersand -- addendum, furthermore

\(Some other non-plain bullets have special meaning to the
software.  By default:

 `~' marks encryptable topics -- see `allout-topic-encryption-bullet'
 `#' marks auto-numbered bullets -- see `allout-numbered-bullet'.)

See `allout-plain-bullets-string' for the standard, alternating
bullets.

You must run `set-allout-regexp' in order for outline mode to
adopt changes of this value.

DO NOT include the close-square-bracket, `]', on either of the bullet
strings."
  :type 'string
  :group 'allout)
(make-variable-buffer-local 'allout-distinctive-bullets-string)
;;;###autoload
(put 'allout-distinctive-bullets-string 'safe-local-variable 'stringp)

;;;_  = allout-use-mode-specific-leader
(defcustom allout-use-mode-specific-leader t
  "When non-nil, use mode-specific topic-header prefixes.

Allout outline mode will use the mode-specific `allout-mode-leaders' or
comment-start string, if any, to lead the topic prefix string, so topic
headers look like comments in the programming language.  It will also use
the comment-start string, with an '_' appended, for `allout-primary-bullet'.

String values are used as literals, not regular expressions, so
do not escape any regular-expression characters.

Value t means to first check for assoc value in `allout-mode-leaders'
alist, then use comment-start string, if any, then use default (`.').
\(See note about use of comment-start strings, below.)

Set to the symbol for either of `allout-mode-leaders' or
`comment-start' to use only one of them, respectively.

Value nil means to always use the default (`.') and leave
`allout-primary-bullet' unaltered.

comment-start strings that do not end in spaces are tripled in
the header-prefix, and an `_' underscore is tacked on the end, to
distinguish them from regular comment strings.  comment-start
strings that do end in spaces are not tripled, but an underscore
is substituted for the space.  [This presumes that the space is
for appearance, not comment syntax.  You can use
`allout-mode-leaders' to override this behavior, when
undesired.]"
  :type '(choice (const t) (const nil) string
		 (const allout-mode-leaders)
		 (const comment-start))
  :group 'allout)
;;;###autoload
(put 'allout-use-mode-specific-leader 'safe-local-variable
     (lambda (x) (or (memq x '(t nil allout-mode-leaders comment-start))
                      (stringp x))))
;;;_  = allout-mode-leaders
(defvar allout-mode-leaders '()
  "Specific allout-prefix leading strings per major modes.

Use this if the mode's comment-start string isn't what you
prefer, or if the mode lacks a comment-start string.  See
`allout-use-mode-specific-leader' for more details.

If you're constructing a string that will comment-out outline
structuring so it can be included in program code, append an extra
character, like an \"_\" underscore, to distinguish the lead string
from regular comments that start at the beginning-of-line.")

;;;_  = allout-old-style-prefixes
(defcustom allout-old-style-prefixes nil
  "When non-nil, use only old-and-crusty `outline-mode' `*' topic prefixes.

Non-nil restricts the topic creation and modification
functions to asterix-padded prefixes, so they look exactly
like the original Emacs-outline style prefixes.

Whatever the setting of this variable, both old and new style prefixes
are always respected by the topic maneuvering functions."
  :type 'boolean
  :group 'allout)
(make-variable-buffer-local 'allout-old-style-prefixes)
;;;###autoload
(put 'allout-old-style-prefixes 'safe-local-variable
     (if (fboundp 'booleanp) 'booleanp (lambda (x) (member x '(t nil)))))
;;;_  = allout-stylish-prefixes -- alternating bullets
(defcustom allout-stylish-prefixes t
  "Do fancy stuff with topic prefix bullets according to level, etc.

Non-nil enables topic creation, modification, and repositioning
functions to vary the topic bullet char (the char that marks the topic
depth) just preceding the start of the topic text) according to level.
Otherwise, only asterisks (`*') and distinctive bullets are used.

This is how an outline can look (but sans indentation) with stylish
prefixes:

    * Top level
    .* A topic
    . + One level 3 subtopic
    .  . One level 4 subtopic
    .  . A second 4 subtopic
    . + Another level 3 subtopic
    .  #1 A numbered level 4 subtopic
    .  #2 Another
    .  ! Another level 4 subtopic with a different distinctive bullet
    .  #4 And another numbered level 4 subtopic

This would be an outline with stylish prefixes inhibited (but the
numbered and other distinctive bullets retained):

    * Top level
    .* A topic
    . * One level 3 subtopic
    .  * One level 4 subtopic
    .  * A second 4 subtopic
    . * Another level 3 subtopic
    .  #1 A numbered level 4 subtopic
    .  #2 Another
    .  ! Another level 4 subtopic with a different distinctive bullet
    .  #4 And another numbered level 4 subtopic

Stylish and constant prefixes (as well as old-style prefixes) are
always respected by the topic maneuvering functions, regardless of
this variable setting.

The setting of this var is not relevant when `allout-old-style-prefixes'
is non-nil."
  :type 'boolean
  :group 'allout)
(make-variable-buffer-local 'allout-stylish-prefixes)
;;;###autoload
(put 'allout-stylish-prefixes 'safe-local-variable
     (if (fboundp 'booleanp) 'booleanp (lambda (x) (member x '(t nil)))))

;;;_  = allout-numbered-bullet
(defcustom allout-numbered-bullet "#"
  "String designating bullet of topics that have auto-numbering; nil for none.

Topics having this bullet have automatic maintenance of a sibling
sequence-number tacked on, just after the bullet.  Conventionally set
to \"#\", you can set it to a bullet of your choice.  A nil value
disables numbering maintenance."
  :type '(choice (const nil) string)
  :group 'allout)
(make-variable-buffer-local 'allout-numbered-bullet)
;;;###autoload
(put 'allout-numbered-bullet 'safe-local-variable
     (if (fboundp 'string-or-null-p)
         'string-or-null-p
       (lambda (x) (or (stringp x) (null x)))))
;;;_  = allout-file-xref-bullet
(defcustom allout-file-xref-bullet "@"
  "Bullet signifying file cross-references, for `allout-resolve-xref'.

Set this var to the bullet you want to use for file cross-references."
  :type '(choice (const nil) string)
  :group 'allout)
;;;###autoload
(put 'allout-file-xref-bullet 'safe-local-variable
     (if (fboundp 'string-or-null-p)
         'string-or-null-p
       (lambda (x) (or (stringp x) (null x)))))
;;;_  = allout-presentation-padding
(defcustom allout-presentation-padding 2
  "Presentation-format white-space padding factor, for greater indent."
  :type 'integer
  :group 'allout)

(make-variable-buffer-local 'allout-presentation-padding)
;;;###autoload
(put 'allout-presentation-padding 'safe-local-variable 'integerp)

;;;_  = allout-flattened-numbering-abbreviation
(define-obsolete-variable-alias 'allout-abbreviate-flattened-numbering
  'allout-flattened-numbering-abbreviation "24.1")
(defcustom allout-flattened-numbering-abbreviation nil
  "If non-nil, `allout-flatten-exposed-to-buffer' abbreviates topic
numbers to minimal amount with some context.  Otherwise, entire
numbers are always used."
  :type 'boolean
  :group 'allout)

;;;_ + LaTeX formatting
;;;_  - allout-number-pages
(defcustom allout-number-pages nil
  "Non-nil turns on page numbering for LaTeX formatting of an outline."
  :type 'boolean
  :group 'allout)
;;;_  - allout-label-style
(defcustom allout-label-style "\\large\\bf"
  "Font and size of labels for LaTeX formatting of an outline."
  :type 'string
  :group 'allout)
;;;_  - allout-head-line-style
(defcustom allout-head-line-style "\\large\\sl "
  "Font and size of entries for LaTeX formatting of an outline."
  :type 'string
  :group 'allout)
;;;_  - allout-body-line-style
(defcustom allout-body-line-style " "
  "Font and size of entries for LaTeX formatting of an outline."
  :type 'string
  :group 'allout)
;;;_  - allout-title-style
(defcustom allout-title-style "\\Large\\bf"
  "Font and size of titles for LaTeX formatting of an outline."
  :type 'string
  :group 'allout)
;;;_  - allout-title
(defcustom allout-title '(or buffer-file-name (buffer-name))
  "Expression to be evaluated to determine the title for LaTeX
formatted copy."
  :type 'sexp
  :group 'allout)
;;;_  - allout-line-skip
(defcustom allout-line-skip ".05cm"
  "Space between lines for LaTeX formatting of an outline."
  :type 'string
  :group 'allout)
;;;_  - allout-indent
(defcustom allout-indent ".3cm"
  "LaTeX formatted depth-indent spacing."
  :type 'string
  :group 'allout)

;;;_ + Topic encryption
;;;_  = allout-encryption group
(defgroup allout-encryption nil
  "Settings for topic encryption features of allout outliner."
  :group 'allout)
;;;_  = allout-topic-encryption-bullet
(defcustom allout-topic-encryption-bullet "~"
  "Bullet signifying encryption of the entry's body."
  :type '(choice (const nil) string)
  :version "22.1"
  :group 'allout-encryption)
;;;_  = allout-encrypt-unencrypted-on-saves
(defcustom allout-encrypt-unencrypted-on-saves t
  "If non-nil, topics pending encryption are encrypted during buffer saves.

This prevents file-system exposure of un-encrypted contents of
items marked for encryption.

When non-nil, if the topic currently being edited is decrypted,
it will be encrypted for saving but automatically decrypted
before any subsequent user interaction, so it is once again clear
text for editing though the file system copy is encrypted.

\(Auto-saves are handled differently.  Buffers with plain-text
exposed encrypted topics are exempted from auto saves until all
such topics are encrypted.)"

  :type 'boolean
  :version "23.1"
  :group 'allout-encryption)
(make-variable-buffer-local 'allout-encrypt-unencrypted-on-saves)
(defvar allout-auto-save-temporarily-disabled nil
  "True while topic encryption is pending and auto-saving was active.

The value of `buffer-saved-size' at the time of decryption is used,
for restoring when all encryptions are established.")
(defvar allout-just-did-undo nil
  "True just after undo commands, until allout-post-command-business.")
(make-variable-buffer-local 'allout-just-did-undo)

;;;_ + Developer
;;;_  = allout-developer group
(defgroup allout-developer nil
  "Allout settings developers care about, including topic encryption and more."
  :group 'allout)
;;;_  = allout-run-unit-tests-on-load
(defcustom allout-run-unit-tests-on-load nil
  "When non-nil, unit tests will be run at end of loading the allout module.

Generally, allout code developers are the only ones who'll want to set this.

\(If set, this makes it an even better practice to exercise changes by
doing byte-compilation with a repeat count, so the file is loaded after
compilation.)

See `allout-run-unit-tests' to see what's run."
  :type 'boolean
  :group 'allout-developer)

;;;_ + Miscellaneous customization

;;;_  = allout-enable-file-variable-adjustment
(defcustom allout-enable-file-variable-adjustment t
  "If non-nil, some allout outline actions edit Emacs local file var text.

This can range from changes to existing entries, addition of new ones,
and creation of a new local variables section when necessary.

Emacs file variables adjustments are also inhibited if `enable-local-variables'
is nil.

Operations potentially causing edits include allout encryption routines.
For details, see `allout-toggle-current-subtree-encryption's docstring."
  :type 'boolean
  :group 'allout)
(make-variable-buffer-local 'allout-enable-file-variable-adjustment)

;;;_* CODE -- no user customizations below.