comparison lisp/allout.el @ 64283:d57ad48e7901

(my-mark-marker, allout-isearch-prior-pos, allout-unprotected, allout-undo-aggregation, allout-snug-back, allout-post-command-business, allout-flag-region, isearch-reenable-font-lock, allout-yank, allout-insert-latex-header, allout-insert-latex-trailer, allout-latex-verbatim-quote-curr-line, allout-latexify-exposed, allout-latex-verb-quote): Fix typos in docstrings. (allout-enwrap-isearch, regexp-sans-escapes): Doc fix. (allout-unprotected, allout-prefix-data): Improve argument/docstring consistency. (allout-chart-subtree): Fix argument spec. (allout-open-topic): Rename `use_sib_bullet' argument to `use-sib-bullet'. Doc fix.

64282:769e8d799acf

  "Cue for isearch-dynamic-exposure mechanism, implemented in
allout-pre- and -post-command-hooks.")
(make-variable-buffer-local 'allout-pre-was-isearching)
;;;_   = allout-isearch-prior-pos nil
(defvar allout-isearch-prior-pos nil
  "Cue for isearch-dynamic-exposure tracking, used by allout-isearch-expose.")
(make-variable-buffer-local 'allout-isearch-prior-pos)
;;;_   = allout-isearch-did-quit
(defvar allout-isearch-did-quit nil
  "Distinguishes isearch conclusion and cancellation.

against inadvertent, unnoticed changes.  This is for use by specific,
native outline functions to temporarily override that protection.
It's automatically reset to nil after every buffer modification.")
(make-variable-buffer-local 'allout-override-protect)
;;;_   > allout-unprotected (expr)
(defmacro allout-unprotected (expr)
  "Evaluate EXPRESSION with `allout-override-protect' let-bound t."
  `(let ((allout-override-protect t))
     ,expr))
;;;_   = allout-undo-aggregation
(defvar allout-undo-aggregation 30
  "Amount of successive self-insert actions to bunch together per undo.

This is purely a kludge variable, regulating the compensation for a bug in
the way that before-change-functions and undo interact.")
(make-variable-buffer-local 'allout-undo-aggregation)
;;;_   = file-var-bug hack
(defvar allout-v18/19-file-var-hack nil
  "Horrible hack used to prevent invalid multiple triggering of outline
mode from prop-line file-var activation.  Used by `allout-mode' function

;;;_  = allout-recent-end-of-subtree
(defvar allout-recent-end-of-subtree 0
  "Buffer point last returned by `allout-end-of-current-subtree'.")
(make-variable-buffer-local 'allout-recent-end-of-subtree)
;;;_  > allout-prefix-data (beg end)
(defmacro allout-prefix-data (beg end)
  "Register allout-prefix state data - BEGINNING and END of prefix.

For reference by `allout-recent' funcs.  Returns BEGINNING."
  `(setq allout-recent-prefix-end ,end
         allout-recent-prefix-beginning ,beg))
;;;_  > allout-recent-depth ()
(defmacro allout-recent-depth ()
  "Return depth of last heading encountered by an outline maneuvering function.

All outline functions which directly do string matches to assess

at the beginning of the topic.  Charts for offspring consists of a
list containing, recursively, the charts for the respective subtopics.
The chart for a topics' offspring precedes the entry for the topic
itself.

\(fn &optional levels)"

  ;; The other function parameters are for internal recursion, and should
  ;; not be specified by external callers.  ORIG-DEPTH is depth of topic at
  ;; starting point, and PREV-DEPTH is depth of prior topic."

Return depth if successful, nil otherwise."
  (allout-next-sibling depth (not backward))
  )
;;;_   > allout-snug-back ()
(defun allout-snug-back ()
  "Position cursor at end of previous topic

Presumes point is at the start of a topic prefix."
 (if (or (bobp) (eobp))
     nil
   (forward-char -1))

- Null `allout-override-protect', so it's not left open.

- Implement (and clear) `allout-post-goto-bullet', for hot-spot
  outline commands.

- Massages buffer-undo-list so successive, standard character self-inserts are
  aggregated.  This kludge compensates for lack of undo bunching when
  `before-change-functions' is used."

					; Apply any external change func:
  (if (not (allout-mode-p))		; In allout-mode.
      nil

(defvar allout-isearch-was-font-lock
  (and (boundp 'font-lock-mode) font-lock-mode))

;;;_   > allout-flag-region (from to flag)
(defmacro allout-flag-region (from to flag)
  "Hide or show lines from FROM to TO, via Emacs selective-display FLAG char.
Ie, text following flag C-m \(carriage-return) is hidden until the
next C-j (newline) char.

Returns the endpoint of the region."
  `(let ((buffer-read-only nil)

	(setq allout-isearch-prior-pos nil)
	(allout-show-children))))
  (setq allout-isearch-did-quit nil))
;;;_   > allout-enwrap-isearch ()
(defun allout-enwrap-isearch ()
  "Impose `allout-mode' isearch-abort wrapper for dynamic exposure in isearch.

The function checks to ensure that the rebinding is done only once."

  (add-hook 'isearch-mode-end-hook 'allout-isearch-rectification)
  (if (fboundp 'allout-real-isearch-abort)

  (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 ()
  "Reenable font-lock after isearching - for use on isearch-mode-end-hook."
  (if (and (boundp 'font-lock-mode) font-lock-mode)
      (if (and (allout-mode-p) isearch-was-font-locking)
	  (setq isearch-was-font-locking nil
		font-lock-mode t))))
(add-hook 'isearch-mode-end-hook 'isearch-reenable-font-lock)

                (format "%d" (cond ((and index (numberp index)) index)
                                   (new (1+ (allout-sibling-index depth)))
                                   ((allout-sibling-index))))))
    )
  )
;;;_   > allout-open-topic (relative-depth &optional before use_sib_bullet)
(defun allout-open-topic (relative-depth &optional before use_sib_bullet)
  "Open a new topic at depth RELATIVE-DEPTH.

New topic is situated after current one, unless optional flag BEFORE
is non-nil, or unless current line is complete empty (not even
whitespace), in which case open is done on current line.

If USE_SIB_BULLET is true, use the bullet of the prior sibling.

Nuances:

- Creation of new topics is with respect to the visible topic
  containing the cursor, regardless of intervening concealed ones.

		    " "))

    ;;(if doing-beginning (save-excursion (newline (if dbl-space 2 1))))


    (allout-rebullet-heading (and use_sib_bullet ref-bullet);;; solicit
                              depth			     ;;; depth
                              nil 			     ;;; number-control
                              nil			     ;;; index
                              t)     (end-of-line)
    )

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)
  (if (allout-mode-p)

  (allout-copy-exposed-to-buffer arg tobuf 'indent))

;;;_  - LaTeX formatting
;;;_   > allout-latex-verb-quote (string &optional flow)
(defun allout-latex-verb-quote (string &optional flow)
  "Return copy of STRING for literal reproduction across latex processing.
Expresses the original characters \(including carriage returns) of the
string across latex processing."
  (mapconcat (function
	      (lambda (char)
		(cond ((memq char '(?\\ ?$ ?% ?# ?& ?{ ?} ?_ ?^ ?- ?*))
		       (concat "\\char" (number-to-string char) "{}"))
		      ((= char ?\n) "\\\\")
		      (t (char-to-string char)))))
	     string
	     ""))
;;;_   > allout-latex-verbatim-quote-curr-line ()
(defun allout-latex-verbatim-quote-curr-line ()
  "Express line for exact \(literal) representation across latex processing.

Adjust line contents so it is unaltered \(from the original line)
across latex processing, within the context of a `verbatim'
environment.  Leaves point at the end of the line."
  (beginning-of-line)
  (let ((beg (point))
	(end (progn (end-of-line)(point))))
    (goto-char beg)

      (insert "\\")
      (setq end (1+ end))
      (goto-char (1+ (match-end 0))))))
;;;_   > allout-insert-latex-header (buffer)
(defun allout-insert-latex-header (buffer)
  "Insert initial latex commands at point in BUFFER."
  ;; Much of this is being derived from the stuff in appendix of E in
  ;; the TeXBook, pg 421.
  (set-buffer buffer)
  (let ((doc-style (format "\n\\documentstyle{%s}\n"
			   "report"))

		    hoffset
		    vspace)
	    )))
;;;_   > allout-insert-latex-trailer (buffer)
(defun allout-insert-latex-trailer (buffer)
  "Insert concluding latex commands at point in BUFFER."
  (set-buffer buffer)
  (insert "\n\\end{document}\n"))
;;;_   > allout-latexify-one-item (depth prefix bullet text)
(defun allout-latexify-one-item (depth prefix bullet text)
  "Insert LaTeX commands for formatting one outline item.

      ;;(insert "\\endlines\n")
      (insert "\\end{verbatim}\n")
      )))
;;;_   > allout-latexify-exposed (arg &optional tobuf)
(defun allout-latexify-exposed (arg &optional tobuf)
  "Format current topics exposed portions to TOBUF for latex processing.
TOBUF defaults to a buffer named the same as the current buffer, but
with \"*\" prepended and \" latex-formed*\" appended.

With repeat count, copy the exposed portions of entire buffer."

  "Return a copy of REGEXP with all character escapes stripped out.

Representations of actual backslashes - '\\\\\\\\' - are left as a
single backslash.

Optional arg SUCCESSIVE-BACKSLASHES is used internally for recursion."

  (if (string= regexp "")
      ""
    ;; Set successive-backslashes to number if current char is
    ;; backslash, or else to nil:

	       (if append
		   (nconc (symbol-value hook) (list function))
		 (cons function (symbol-value hook)))))))
;;;_  : my-mark-marker to accommodate divergent emacsen:
(defun my-mark-marker (&optional force buffer)
  "Accommodate the different signature for mark-marker across Emacsen.

XEmacs takes two optional args, while GNU Emacs does not,
so pass them along when appropriate."
  (if (featurep 'xemacs)
      (mark-marker force buffer)

64283:d57ad48e7901

  "Cue for isearch-dynamic-exposure mechanism, implemented in
allout-pre- and -post-command-hooks.")
(make-variable-buffer-local 'allout-pre-was-isearching)
;;;_   = allout-isearch-prior-pos nil
(defvar allout-isearch-prior-pos nil
  "Cue for isearch-dynamic-exposure tracking, used by `allout-isearch-expose'.")
(make-variable-buffer-local 'allout-isearch-prior-pos)
;;;_   = allout-isearch-did-quit
(defvar allout-isearch-did-quit nil
  "Distinguishes isearch conclusion and cancellation.

against inadvertent, unnoticed changes.  This is for use by specific,
native outline functions to temporarily override that protection.
It's automatically reset to nil after every buffer modification.")
(make-variable-buffer-local 'allout-override-protect)
;;;_   > allout-unprotected (expr)
(defmacro allout-unprotected (expression)
  "Evaluate EXPRESSION with `allout-override-protect' let-bound to t."
  `(let ((allout-override-protect t))
     ,expression))
;;;_   = allout-undo-aggregation
(defvar allout-undo-aggregation 30
  "Amount of successive self-insert actions to bunch together per undo.

This is purely a kludge variable, regulating the compensation for a bug in
the way that `before-change-functions' and undo interact.")
(make-variable-buffer-local 'allout-undo-aggregation)
;;;_   = file-var-bug hack
(defvar allout-v18/19-file-var-hack nil
  "Horrible hack used to prevent invalid multiple triggering of outline
mode from prop-line file-var activation.  Used by `allout-mode' function

;;;_  = allout-recent-end-of-subtree
(defvar allout-recent-end-of-subtree 0
  "Buffer point last returned by `allout-end-of-current-subtree'.")
(make-variable-buffer-local 'allout-recent-end-of-subtree)
;;;_  > allout-prefix-data (beg end)
(defmacro allout-prefix-data (beginning end)
  "Register allout-prefix state data - BEGINNING and END of prefix.

For reference by `allout-recent' funcs.  Returns BEGINNING."
  `(setq allout-recent-prefix-end ,end
         allout-recent-prefix-beginning ,beginning))
;;;_  > allout-recent-depth ()
(defmacro allout-recent-depth ()
  "Return depth of last heading encountered by an outline maneuvering function.

All outline functions which directly do string matches to assess

at the beginning of the topic.  Charts for offspring consists of a
list containing, recursively, the charts for the respective subtopics.
The chart for a topics' offspring precedes the entry for the topic
itself.

\(fn &optional LEVELS)"

  ;; The other function parameters are for internal recursion, and should
  ;; not be specified by external callers.  ORIG-DEPTH is depth of topic at
  ;; starting point, and PREV-DEPTH is depth of prior topic."

Return depth if successful, nil otherwise."
  (allout-next-sibling depth (not backward))
  )
;;;_   > allout-snug-back ()
(defun allout-snug-back ()
  "Position cursor at end of previous topic.

Presumes point is at the start of a topic prefix."
 (if (or (bobp) (eobp))
     nil
   (forward-char -1))

- Null `allout-override-protect', so it's not left open.

- Implement (and clear) `allout-post-goto-bullet', for hot-spot
  outline commands.

- Massages `buffer-undo-list' so successive, standard character self-inserts
  are aggregated.  This kludge compensates for lack of undo bunching when
  `before-change-functions' is used."

					; Apply any external change func:
  (if (not (allout-mode-p))		; In allout-mode.
      nil

(defvar allout-isearch-was-font-lock
  (and (boundp 'font-lock-mode) font-lock-mode))

;;;_   > allout-flag-region (from to flag)
(defmacro allout-flag-region (from to flag)
  "Hide or show lines from FROM to TO, via Emacs `selective-display' FLAG char.
Ie, text following flag C-m \(carriage-return) is hidden until the
next C-j (newline) char.

Returns the endpoint of the region."
  `(let ((buffer-read-only nil)

	(setq allout-isearch-prior-pos nil)
	(allout-show-children))))
  (setq allout-isearch-did-quit nil))
;;;_   > allout-enwrap-isearch ()
(defun allout-enwrap-isearch ()
  "Impose `isearch-abort' wrapper for dynamic exposure in isearch.

The function checks to ensure that the rebinding is done only once."

  (add-hook 'isearch-mode-end-hook 'allout-isearch-rectification)
  (if (fboundp 'allout-real-isearch-abort)

  (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 ()
  "Reenable font-lock after isearching - for use on `isearch-mode-end-hook'."
  (if (and (boundp 'font-lock-mode) font-lock-mode)
      (if (and (allout-mode-p) isearch-was-font-locking)
	  (setq isearch-was-font-locking nil
		font-lock-mode t))))
(add-hook 'isearch-mode-end-hook 'isearch-reenable-font-lock)

                (format "%d" (cond ((and index (numberp index)) index)
                                   (new (1+ (allout-sibling-index depth)))
                                   ((allout-sibling-index))))))
    )
  )
;;;_   > allout-open-topic (relative-depth &optional before use-sib-bullet)
(defun allout-open-topic (relative-depth &optional before use-sib-bullet)
  "Open a new topic at depth RELATIVE-DEPTH.

New topic is situated after current one, unless optional flag BEFORE
is non-nil, or unless current line is complete empty (not even
whitespace), in which case open is done on current line.

If USE-SIB-BULLET is true, use the bullet of the prior sibling.

Nuances:

- Creation of new topics is with respect to the visible topic
  containing the cursor, regardless of intervening concealed ones.

		    " "))

    ;;(if doing-beginning (save-excursion (newline (if dbl-space 2 1))))


    (allout-rebullet-heading (and use-sib-bullet ref-bullet);;; solicit
                              depth			     ;;; depth
                              nil 			     ;;; number-control
                              nil			     ;;; index
                              t)     (end-of-line)
    )

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)
  (if (allout-mode-p)

  (allout-copy-exposed-to-buffer arg tobuf 'indent))

;;;_  - LaTeX formatting
;;;_   > allout-latex-verb-quote (string &optional flow)
(defun allout-latex-verb-quote (string &optional flow)
  "Return copy of STRING for literal reproduction across LaTeX processing.
Expresses the original characters \(including carriage returns) of the
string across LaTeX processing."
  (mapconcat (function
	      (lambda (char)
		(cond ((memq char '(?\\ ?$ ?% ?# ?& ?{ ?} ?_ ?^ ?- ?*))
		       (concat "\\char" (number-to-string char) "{}"))
		      ((= char ?\n) "\\\\")
		      (t (char-to-string char)))))
	     string
	     ""))
;;;_   > allout-latex-verbatim-quote-curr-line ()
(defun allout-latex-verbatim-quote-curr-line ()
  "Express line for exact \(literal) representation across LaTeX processing.

Adjust line contents so it is unaltered \(from the original line)
across LaTeX processing, within the context of a `verbatim'
environment.  Leaves point at the end of the line."
  (beginning-of-line)
  (let ((beg (point))
	(end (progn (end-of-line)(point))))
    (goto-char beg)

      (insert "\\")
      (setq end (1+ end))
      (goto-char (1+ (match-end 0))))))
;;;_   > allout-insert-latex-header (buffer)
(defun allout-insert-latex-header (buffer)
  "Insert initial LaTeX commands at point in BUFFER."
  ;; Much of this is being derived from the stuff in appendix of E in
  ;; the TeXBook, pg 421.
  (set-buffer buffer)
  (let ((doc-style (format "\n\\documentstyle{%s}\n"
			   "report"))

		    hoffset
		    vspace)
	    )))
;;;_   > allout-insert-latex-trailer (buffer)
(defun allout-insert-latex-trailer (buffer)
  "Insert concluding LaTeX commands at point in BUFFER."
  (set-buffer buffer)
  (insert "\n\\end{document}\n"))
;;;_   > allout-latexify-one-item (depth prefix bullet text)
(defun allout-latexify-one-item (depth prefix bullet text)
  "Insert LaTeX commands for formatting one outline item.

      ;;(insert "\\endlines\n")
      (insert "\\end{verbatim}\n")
      )))
;;;_   > allout-latexify-exposed (arg &optional tobuf)
(defun allout-latexify-exposed (arg &optional tobuf)
  "Format current topics exposed portions to TOBUF for LaTeX processing.
TOBUF defaults to a buffer named the same as the current buffer, but
with \"*\" prepended and \" latex-formed*\" appended.

With repeat count, copy the exposed portions of entire buffer."

  "Return a copy of REGEXP with all character escapes stripped out.

Representations of actual backslashes - '\\\\\\\\' - are left as a
single backslash.

\(fn REGEXP)"
;; Optional arg SUCCESSIVE-BACKSLASHES is used internally for recursion.

  (if (string= regexp "")
      ""
    ;; Set successive-backslashes to number if current char is
    ;; backslash, or else to nil:

	       (if append
		   (nconc (symbol-value hook) (list function))
		 (cons function (symbol-value hook)))))))
;;;_  : my-mark-marker to accommodate divergent emacsen:
(defun my-mark-marker (&optional force buffer)
  "Accommodate the different signature for `mark-marker' across Emacsen.

XEmacs takes two optional args, while GNU Emacs does not,
so pass them along when appropriate."
  (if (featurep 'xemacs)
      (mark-marker force buffer)