comparison lisp/allout.el @ 48858:f4d079377a9a

Avoid name conflicts with outline.el. Use 3 installments to keep diffs understandable. Change 3: Doc changes to adjust to the change to prefix "allout-". Don't provide 'outline. Use " Allout" as mode line string, not " Outl". Put group 'allout in group 'editing. Update Copyright notice. Autoload `allout-init'.

48857:8641226163f1

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

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

;; Author: Ken Manheimer <[e-mail]>
;; Maintainer: Ken Manheimer <[e-mail]>
;; Created: Dec 1991 - first release to usenet
;; Version: $Id: allout.el,v 1.35 2002/12/16 00:20:42 rost Exp $||
;; Keywords: outlines mode wp languages

;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify

;;    exposure control.  (See the `allout-mode' docstring.)
;; 
;; and many other features.
;; 
;; The outline menubar additions provide quick reference to many of
;; the features, and see the docstring of the variable `allout-init'
;; for instructions on priming your emacs session for automatic
;; activation of `allout-mode'.
;; 
;; See the docstring of the variables `allout-layout' and
;; `allout-auto-activation' for details on automatic activation of

;; Ken Manheimer	[e-mail]

;;; Code:

;;;_* Provide
(provide 'outline)
(provide 'allout)

;;;_* USER CUSTOMIZATION VARIABLES:
(defgroup allout nil
  "Extensive outline mode for use alone and with other modes."
  :prefix "allout-"
  :group 'outlines)

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

;;;_  = allout-auto-activation
(defcustom allout-auto-activation nil

outline mode is automatically activated when the buffer-specific
variable `allout-layout' is non-nil, and whether or not the layout
dictated by `allout-layout' should be imposed on mode activation.

With value `t', auto-mode-activation and auto-layout are enabled.
\(This also depends on `allout-find-file-hooks' being installed in
`find-file-hooks', which is also done by `allout-init'.)

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

  "*Layout specification and provisional mode trigger for allout outlines.

Buffer-specific.

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

See the docstring for `allout-init' for details on setting up for
auto-mode-activation, and for `allout-expose-topic' for the format of
the layout specification.

character, like an \"_\" underscore, to distinguish the lead string
from regular comments that start at bol.")

;;;_  = allout-old-style-prefixes
(defcustom allout-old-style-prefixes nil
  "*When non-nil, use only old-and-crusty allout-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.

;;;_ #1 Internal Outline Formatting and Configuration
;;;_  : Version
;;;_   = allout-version
(defvar allout-version
  (let ((rcs-rev "$Revision: 1.35 $"))
    (condition-case err
	(save-match-data
	  (string-match "Revision: \\([0-9]+\\.[0-9]+\\)" rcs-rev)
	  (substring rcs-rev (match-beginning 1) (match-end 1)))
      ('error rcs-rev)))

(defvar allout-bullets-string-len 0
  "Length of current buffers' `allout-plain-bullets-string'.")
(make-variable-buffer-local 'allout-bullets-string-len)
;;;_   = allout-line-boundary-regexp
(defvar allout-line-boundary-regexp ()
  "Allout-regexp with allout-style beginning-of-line anchor.

\(Ie, C-j, *or* C-m, for prefixes of hidden topics).  This is properly
set when `allout-regexp' is produced by `set-allout-regexp', so
that (match-beginning 2) and (match-end 2) delimit the prefix.")
(make-variable-buffer-local 'allout-line-boundary-regexp)

		      ["Set Header Lead" allout-reset-header-lead t]
		      ["Set New Exposure" allout-expose-topic t])))
;;;_  : Mode-Specific Variable Maintenance Utilities
;;;_   = allout-mode-prior-settings
(defvar allout-mode-prior-settings nil
  "Internal outline mode use; settings to be resumed on mode deactivation.")
(make-variable-buffer-local 'allout-mode-prior-settings)
;;;_   > allout-resumptions (name &optional value)
(defun allout-resumptions (name &optional value)

  "Registers or resumes settings over `allout-mode' activation/deactivation.

  "Horrible hack used to prevent invalid multiple triggering of outline
mode from prop-line file-var activation.  Used by `allout-mode' function
to track repeats.")
;;;_   > allout-write-file-hook ()
(defun allout-write-file-hook ()
  "In outline mode, run as a `local-write-file-hooks' activity.

Currently just sets `allout-during-write-cue', so allout-change-protection
knows to keep inactive during file write."
  (setq allout-during-write-cue t)
  nil)

;;;_ #2 Mode activation

(defmacro allout-mode-p ()
  "Return t if `allout-mode' is active in current buffer."
  'allout-mode)
;;;_  = allout-explicitly-deactivated
(defvar allout-explicitly-deactivated nil
  "Allout-mode was last deliberately deactivated.
So `allout-post-command-business' should not reactivate it...")
(make-variable-buffer-local 'allout-explicitly-deactivated)
;;;_  > allout-init (&optional mode)
(defun allout-init (&optional mode)
  "Prime `allout-mode' to enable/disable auto-activation, wrt `allout-layout'.

MODE is one of the following symbols:

Use this function to setup your emacs session for automatic activation
of allout outline mode, contingent to the buffer-specific setting of
the `allout-layout' variable.  (See `allout-layout' and
`allout-expose-topic' docstrings for more details on auto layout).

`allout-init' works by setting up (or removing) the allout-mode
find-file-hook, and giving `allout-auto-activation' a suitable
setting.

To prime your emacs session for full auto-outline operation, include
the following two lines in your emacs init file:

\(require 'allout)

			  "Outline mode auto-activation and -layout enabled.")
			 'full)))))))
		   
;;;_  > allout-setup-menubar ()
(defun allout-setup-menubar ()
  "Populate the current buffer's menubar with allout allout-mode stuff."
  (let ((menus (list allout-mode-exposure-menu
		     allout-mode-editing-menu
		     allout-mode-navigation-menu
		     allout-mode-misc-menu))
	cur)

  "Toggle minor mode for controlling exposure and editing of text outlines.

Optional arg forces mode to re-initialize iff arg is positive num or
symbol.  Allout outline mode always runs as a minor mode.

Allout outline mode provides extensive allout-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
an example, see the allout code itself, which is organized as an allout
outline.)

	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 allout-structuring in
	program code without interfering with the language processing
	of that code.  See `allout-use-mode-specific-leader'
	docstring for more detail.
PREFIX-PADDING:
	Spaces or asterisks which separate the prefix-lead and the

     ;; Emacs v 19.18, 19.19 file-var code invokes prop-line-designated
     ;; modes twice when file is visited.  We have to avoid toggling mode
     ;; off on second invocation, so we detect it as best we can, and
     ;; skip everything.
     ((and same-complex-command		; Still in same complex command
				       ; as last time `allout-mode' invoked.
	  active			; Already activated.
	  (not explicit-activation)	; Prop-line file-vars don't have args.
	  (string-match "^19.1[89]"	; Bug only known to be in v19.18 and
			emacs-version)); 19.19.
      t)

			  (list (concat paragraph-separate "\\|^\\("
					allout-regexp "\\)")))

      (or (assq 'allout-mode minor-mode-alist)
	  (setq minor-mode-alist
	       (cons '(allout-mode " Outl") minor-mode-alist)))

      (allout-setup-menubar)

      (if allout-layout
	  (setq do-layout t))

Optional argument LEVELS specifies the depth \(relative to start
depth) for the chart.  Subsequent optional args are not for public
use.

Charts are used to capture outline structure, so that allout-altering
routines need assess the structure only once, and then use the chart
for their elaborate manipulations.

Topics are entered in the chart so the last one is at the car.
The entry for each topic consists of an integer indicating the point

        (goto-char start-point)
	(if depth (allout-depth) start-depth)
        nil))))
;;;_   > allout-previous-sibling (&optional depth backward)
(defun allout-previous-sibling (&optional depth backward)
  "Like `allout-forward-current-level',but backwards & respect invisible topics.

Optional DEPTH specifies depth to traverse, default current depth.

Optional BACKWARD reverses direction.

(defun allout-pre-command-business ()
  "Outline `pre-command-hook' function for outline buffers.
Implements special behavior when cursor is on bullet char.

Self-insert characters are reinterpreted control-character references
into the `allout-mode-map'.  The `allout-mode' post-command hook will
position a cursor that has moved as a result of such reinterpretation,
on the destination topic's bullet, when the cursor wound up in the

The upshot is that you can get easy, single (ie, unmodified) key
outline maneuvering operations by positioning the cursor on the bullet

	  (signal 'quit nil))))

;;; Prevent unnecessary font-lock while isearching!
(defvar isearch-was-font-locking nil)
(defun isearch-inhibit-font-lock ()
  "Inhibit font-lock while isearching - for use on `isearch-mode-hook'."
  (if (and (allout-mode-p) (boundp 'font-lock-mode) font-lock-mode)
      (setq isearch-was-font-locking t
	    font-lock-mode nil)))
(add-hook 'isearch-mode-hook 'isearch-inhibit-font-lock)
(defun isearch-reenable-font-lock ()

;;;_    = allout-former-auto-filler
(defvar allout-former-auto-filler nil
  "Name of modal fill function being wrapped by `allout-auto-fill'.")
;;;_    > allout-auto-fill ()
(defun allout-auto-fill ()
  "Allout-mode autofill function.

Maintains outline hanging topic indentation if
`allout-use-hanging-indents' is set."
  (let ((fill-prefix (if allout-use-hanging-indents
                         ;; Check for topic header indentation:

    (save-excursion
      (allout-renumber-to-depth depth))))
;;;_    > allout-yank-processing ()
(defun allout-yank-processing (&optional arg)

  "Incidental allout-specific business to be done just after text yanks.

Does depth adjustment of yanked topics, when:

1 the stuff being yanked starts with a valid outline header prefix, and
2 it is being yanked at the end of a line which consists of only a valid

the amount it takes to make the first topic have the depth of the
header into which it's being yanked.

The point is left in front of yanked, adjusted topics, rather than
at the end (and vice-versa with the mark).  Non-adjusted yanks,
however, are left exactly like normal, non-allout-specific yanks."

  (interactive "*P")
					; Get to beginning, leaving
					; region around subject:
  (if (< (my-mark-marker t) (point))

	    (message ""))))
    (if (not resituate)
      (exchange-point-and-mark))))
;;;_    > allout-yank (&optional arg)
(defun allout-yank (&optional arg)
  "Allout-mode yank, with depth and numbering adjustment of yanked topics.

Non-topic yanks work no differently than normal yanks.

If a topic is being yanked into a bare topic prefix, the depth of the
yanked topic is adjusted to the depth of the topic prefix.

exactly like normal yanks.

Numbering of yanked topics, and the successive siblings at the depth
into which they're being yanked, is adjusted.

`Allout-yank-pop' works with `allout-yank' just like normal yank-pop
works with normal yank in non-outline buffers."

  (interactive "*P")
  (setq this-command 'yank)
  (yank arg)

(defun allout-show-entry ()
  "Like `allout-show-current-entry', reveals entries nested in hidden topics.

This is a way to give restricted peek at a concealed locality without the
expense of exposing its context, but can leave the outline with aberrant
exposure.  `allout-hide-current-entry-completely' or `allout-show-offshoot'
should be used after the peek to rectify the exposure."

  (interactive)
  (save-excursion
    (let ((at (point))

48858:f4d079377a9a

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

;; Copyright (C) 1992, 1993, 1994, 2001, 2002 Free Software Foundation, Inc.

;; Author: Ken Manheimer <[e-mail]>
;; Maintainer: Ken Manheimer <[e-mail]>
;; Created: Dec 1991 - first release to usenet
;; Version: $Id: allout.el,v 1.36 2002/12/16 00:26:22 rost Exp $||
;; Keywords: outlines mode wp languages

;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify

;;    exposure control.  (See the `allout-mode' docstring.)
;; 
;; and many other features.
;; 
;; The outline menubar additions provide 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'.
;; 
;; See the docstring of the variables `allout-layout' and
;; `allout-auto-activation' for details on automatic activation of

;; Ken Manheimer	[e-mail]

;;; Code:

;;;_* Provide
(provide 'allout)

;;;_* USER CUSTOMIZATION VARIABLES:
(defgroup allout nil
  "Extensive outline mode for use alone and with other modes."
  :prefix "allout-"
  :group 'editing)

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

;;;_  = allout-auto-activation
(defcustom allout-auto-activation nil

outline mode is automatically activated when the buffer-specific
variable `allout-layout' is non-nil, and whether or not the layout
dictated by `allout-layout' should be imposed on mode activation.

With value `t', auto-mode-activation and auto-layout are enabled.
\(This also depends on `allout-find-file-hook' being installed in
`find-file-hooks', which is also done by `allout-init'.)

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

  "*Layout specification and provisional mode trigger for allout outlines.

Buffer-specific.

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-init'
has been called to enable it.

See the docstring for `allout-init' for details on setting up for
auto-mode-activation, and for `allout-expose-topic' for the format of
the layout specification.

character, like an \"_\" underscore, to distinguish the lead string
from regular comments that start at bol.")

;;;_  = 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.

;;;_ #1 Internal Outline Formatting and Configuration
;;;_  : Version
;;;_   = allout-version
(defvar allout-version
  (let ((rcs-rev "$Revision: 1.36 $"))
    (condition-case err
	(save-match-data
	  (string-match "Revision: \\([0-9]+\\.[0-9]+\\)" rcs-rev)
	  (substring rcs-rev (match-beginning 1) (match-end 1)))
      ('error rcs-rev)))

(defvar allout-bullets-string-len 0
  "Length of current buffers' `allout-plain-bullets-string'.")
(make-variable-buffer-local 'allout-bullets-string-len)
;;;_   = allout-line-boundary-regexp
(defvar allout-line-boundary-regexp ()
  "`allout-regexp' with outline style beginning-of-line anchor.

\(Ie, C-j, *or* C-m, for prefixes of hidden topics).  This is properly
set when `allout-regexp' is produced by `set-allout-regexp', so
that (match-beginning 2) and (match-end 2) delimit the prefix.")
(make-variable-buffer-local 'allout-line-boundary-regexp)

		      ["Set Header Lead" allout-reset-header-lead t]
		      ["Set New Exposure" allout-expose-topic t])))
;;;_  : Mode-Specific Variable Maintenance Utilities
;;;_   = allout-mode-prior-settings
(defvar allout-mode-prior-settings nil
  "Internal `allout-mode' use; settings to be resumed on mode deactivation.")
(make-variable-buffer-local 'allout-mode-prior-settings)
;;;_   > allout-resumptions (name &optional value)
(defun allout-resumptions (name &optional value)

  "Registers or resumes settings over `allout-mode' activation/deactivation.

  "Horrible hack used to prevent invalid multiple triggering of outline
mode from prop-line file-var activation.  Used by `allout-mode' function
to track repeats.")
;;;_   > allout-write-file-hook ()
(defun allout-write-file-hook ()
  "In `allout-mode', run as a `local-write-file-hooks' activity.

Currently just sets `allout-during-write-cue', so outline change-protection
knows to keep inactive during file write."
  (setq allout-during-write-cue t)
  nil)

;;;_ #2 Mode activation

(defmacro allout-mode-p ()
  "Return t if `allout-mode' is active in current buffer."
  'allout-mode)
;;;_  = allout-explicitly-deactivated
(defvar allout-explicitly-deactivated nil
  "Non-nil if `allout-mode' was last deliberately deactivated.
So `allout-post-command-business' should not reactivate it...")
(make-variable-buffer-local 'allout-explicitly-deactivated)
;;;_  > allout-init (&optional mode)
;;;###autoload
(defun allout-init (&optional mode)
  "Prime `allout-mode' to enable/disable auto-activation, wrt `allout-layout'.

MODE is one of the following symbols:

Use this function to setup your emacs session for automatic activation
of allout outline mode, contingent to the buffer-specific setting of
the `allout-layout' variable.  (See `allout-layout' and
`allout-expose-topic' docstrings for more details on auto layout).

`allout-init' works by setting up (or removing)
`allout-find-file-hook' in `find-file-hooks', and giving
`allout-auto-activation' a suitable setting.

To prime your emacs session for full auto-outline operation, include
the following two lines in your emacs init file:

\(require 'allout)

			  "Outline mode auto-activation and -layout enabled.")
			 'full)))))))
		   
;;;_  > allout-setup-menubar ()
(defun allout-setup-menubar ()
  "Populate the current buffer's menubar with `allout-mode' stuff."
  (let ((menus (list allout-mode-exposure-menu
		     allout-mode-editing-menu
		     allout-mode-navigation-menu
		     allout-mode-misc-menu))
	cur)

  "Toggle minor mode for controlling exposure and editing of text outlines.

Optional arg forces mode to re-initialize iff arg is positive num or
symbol.  Allout outline mode always runs as a minor mode.

Allout outline mode 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
an example, see the allout code itself, which is organized as an allout
outline.)

	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.
PREFIX-PADDING:
	Spaces or asterisks which separate the prefix-lead and the

     ;; Emacs v 19.18, 19.19 file-var code invokes prop-line-designated
     ;; modes twice when file is visited.  We have to avoid toggling mode
     ;; off on second invocation, so we detect it as best we can, and
     ;; skip everything.
     ((and same-complex-command		; Still in same complex command
					; as last time `allout-mode' invoked.
	  active			; Already activated.
	  (not explicit-activation)	; Prop-line file-vars don't have args.
	  (string-match "^19.1[89]"	; Bug only known to be in v19.18 and
			emacs-version)); 19.19.
      t)

			  (list (concat paragraph-separate "\\|^\\("
					allout-regexp "\\)")))

      (or (assq 'allout-mode minor-mode-alist)
	  (setq minor-mode-alist
	       (cons '(allout-mode " Allout") minor-mode-alist)))

      (allout-setup-menubar)

      (if allout-layout
	  (setq do-layout t))

Optional argument LEVELS specifies the depth \(relative to start
depth) for the chart.  Subsequent optional args are not for public
use.

Charts are used to capture outline structure, so that outline altering
routines need assess the structure only once, and then use the chart
for their elaborate manipulations.

Topics are entered in the chart so the last one is at the car.
The entry for each topic consists of an integer indicating the point

        (goto-char start-point)
	(if depth (allout-depth) start-depth)
        nil))))
;;;_   > allout-previous-sibling (&optional depth backward)
(defun allout-previous-sibling (&optional depth backward)
  "Like `allout-forward-current-level', but backwards & respect invisible topics.

Optional DEPTH specifies depth to traverse, default current depth.

Optional BACKWARD reverses direction.

(defun allout-pre-command-business ()
  "Outline `pre-command-hook' function for outline buffers.
Implements special behavior when cursor is on bullet char.

Self-insert characters are reinterpreted control-character references
into the `allout-mode-map'.  The `allout-mode' `post-command-hook' will
position a cursor that has moved as a result of such reinterpretation,
on the destination topic's bullet, when the cursor wound up in the

The upshot is that you can get easy, single (ie, unmodified) key
outline maneuvering operations by positioning the cursor on the bullet

	  (signal 'quit nil))))

;;; Prevent unnecessary font-lock while isearching!
(defvar isearch-was-font-locking nil)
(defun isearch-inhibit-font-lock ()
  "Inhibit `font-lock-mode' while isearching - for use on `isearch-mode-hook'."
  (if (and (allout-mode-p) (boundp 'font-lock-mode) font-lock-mode)
      (setq isearch-was-font-locking t
	    font-lock-mode nil)))
(add-hook 'isearch-mode-hook 'isearch-inhibit-font-lock)
(defun isearch-reenable-font-lock ()

;;;_    = allout-former-auto-filler
(defvar allout-former-auto-filler nil
  "Name of modal fill function being wrapped by `allout-auto-fill'.")
;;;_    > allout-auto-fill ()
(defun allout-auto-fill ()
  "`allout-mode' autofill function.

Maintains outline hanging topic indentation if
`allout-use-hanging-indents' is set."
  (let ((fill-prefix (if allout-use-hanging-indents
                         ;; Check for topic header indentation:

    (save-excursion
      (allout-renumber-to-depth depth))))
;;;_    > allout-yank-processing ()
(defun allout-yank-processing (&optional arg)

  "Incidental outline specific business to be done just after text yanks.

Does depth adjustment of yanked topics, when:

1 the stuff being yanked starts with a valid outline header prefix, and
2 it is being yanked at the end of a line which consists of only a valid

the amount it takes to make the first topic have the depth of the
header into which it's being yanked.

The point is left in front of yanked, adjusted topics, rather than
at the end (and vice-versa with the mark).  Non-adjusted yanks,
however, are left exactly like normal, not outline specific yanks."

  (interactive "*P")
					; Get to beginning, leaving
					; region around subject:
  (if (< (my-mark-marker t) (point))

	    (message ""))))
    (if (not resituate)
      (exchange-point-and-mark))))
;;;_    > allout-yank (&optional arg)
(defun allout-yank (&optional arg)
  "`allout-mode' yank, with depth and numbering adjustment of yanked topics.

Non-topic yanks work no differently than normal yanks.

If a topic is being yanked into a bare topic prefix, the depth of the
yanked topic is adjusted to the depth of the topic prefix.

exactly like normal yanks.

Numbering of yanked topics, and the successive siblings at the depth
into which they're being yanked, is adjusted.

`allout-yank-pop' works with `allout-yank' just like normal yank-pop
works with normal yank in non-outline buffers."

  (interactive "*P")
  (setq this-command 'yank)
  (yank arg)

(defun allout-show-entry ()
  "Like `allout-show-current-entry', reveals entries nested in hidden topics.

This is a way to give restricted peek at a concealed locality without the
expense of exposing its context, but can leave the outline with aberrant
exposure.  `allout-hide-current-entry-completely' or `allout-show-to-offshoot'
should be used after the peek to rectify the exposure."

  (interactive)
  (save-excursion
    (let ((at (point))