Function: allout-rebullet-heading

allout-rebullet-heading is a byte-compiled function defined in allout.el.gz.

Signature

(allout-rebullet-heading &optional INSTEAD NEW-DEPTH NUMBER-CONTROL INDEX DO-SUCCESSORS)

Documentation

Adjust bullet of current topic prefix.

All args are optional.

If INSTEAD is:
- nil, then the bullet char for the context is used, per distinction or depth
- a (numeric) character, then character's string representation is used
- a string, then the user is asked for bullet with the first char as default
- anything else, the user is solicited with bullet char per context as default

Second arg DEPTH forces the topic prefix to that depth, regardless of the topic's current depth.

Third arg NUMBER-CONTROL can force the prefix to or away from numbered form. It has effect only if allout-numbered-bullet is non-nil and soliciting was not explicitly invoked (via first arg). Its effect, numbering or denumbering, then depends on the setting of the fourth arg, INDEX.

If NUMBER-CONTROL is non-nil and fourth arg INDEX is nil, then the prefix of the topic is forced to be non-numbered. Null index and non-nil NUMBER-CONTROL forces denumbering. Non-nil INDEX (and non-nil NUMBER-CONTROL) forces a numbered-prefix form. If non-nil INDEX is a number, then that number is used for the numbered prefix. Non-nil and non-number means that the index for the numbered prefix will be derived by allout-make-topic-prefix.

Fifth arg DO-SUCCESSORS t means re-resolve count on succeeding siblings.

Cf vars allout-stylish-prefixes, allout-old-style-prefixes, and allout-numbered-bullet, which all affect the behavior of this function.

Source Code

;; Defined in /usr/src/emacs/lisp/allout.el.gz
;;;_    > allout-rebullet-heading (&optional instead ...)
(defun allout-rebullet-heading (&optional instead
                                           new-depth
                                           number-control
                                           index
                                           do-successors)

  "Adjust bullet of current topic prefix.

All args are optional.

If INSTEAD is:
- nil, then the bullet char for the context is used, per distinction or depth
- a (numeric) character, then character's string representation is used
- a string, then the user is asked for bullet with the first char as default
- anything else, the user is solicited with bullet char per context as default

Second arg DEPTH forces the topic prefix to that depth, regardless
of the topic's current depth.

Third arg NUMBER-CONTROL can force the prefix to or away from
numbered form.  It has effect only if `allout-numbered-bullet' is
non-nil and soliciting was not explicitly invoked (via first arg).
Its effect, numbering or denumbering, then depends on the setting
of the fourth arg, INDEX.

If NUMBER-CONTROL is non-nil and fourth arg INDEX is nil, then the
prefix of the topic is forced to be non-numbered.  Null index and
non-nil NUMBER-CONTROL forces denumbering.  Non-nil INDEX (and
non-nil NUMBER-CONTROL) forces a numbered-prefix form.  If non-nil
INDEX is a number, then that number is used for the numbered
prefix.  Non-nil and non-number means that the index for the
numbered prefix will be derived by allout-make-topic-prefix.

Fifth arg DO-SUCCESSORS t means re-resolve count on succeeding
siblings.

Cf vars `allout-stylish-prefixes', `allout-old-style-prefixes',
and `allout-numbered-bullet', which all affect the behavior of
this function."

  (let* ((current-depth (allout-depth))
         (new-depth (or new-depth current-depth))
         (mb allout-recent-prefix-beginning)
         (me allout-recent-prefix-end)
         (current-bullet (buffer-substring-no-properties (- me 1) me))
         (has-annotation (get-text-property mb 'allout-was-hidden))
         (new-prefix (allout-make-topic-prefix current-bullet
                                                nil
                                                new-depth
                                                instead
                                                number-control
                                                index)))

    ;; Is new one identical to old?
    (if (and (= current-depth new-depth)
             (string= current-bullet
                      (substring new-prefix (1- (length new-prefix)))))
	;; Nothing to do:
        t

      ;; New prefix probably different from old:
					; get rid of old one:
      (allout-unprotected (delete-region mb me))
      (goto-char mb)
					; Dispense with number if
					; numbered-bullet prefix:
      (save-match-data
        (if (and allout-numbered-bullet
                 (string= allout-numbered-bullet current-bullet)
                 (looking-at "[0-9]+"))
            (allout-unprotected
             (delete-region (match-beginning 0)(match-end 0)))))

      ;; convey 'allout-was-hidden annotation, if original had it:
      (if has-annotation
          (put-text-property 0 (length new-prefix) 'allout-was-hidden t
                             new-prefix))

					; Put in new prefix:
      (allout-unprotected (insert new-prefix))

      ;; Reindent the body if elected, margin changed, and not encrypted body:
      (if (and allout-reindent-bodies
	       (not (= new-depth current-depth))
               (not (allout-encrypted-topic-p)))
	  (allout-reindent-body current-depth new-depth))

      (run-hook-with-args 'allout-exposure-change-functions mb me nil)

      ;; Recursively rectify successive siblings of orig topic if
      ;; caller elected for it:
      (if do-successors
	  (save-excursion
	    (while (allout-next-sibling new-depth nil)
	      (setq index
		    (cond ((numberp index) (1+ index))
			  ((not number-control)  (allout-sibling-index))))
	      (if (allout-numbered-type-prefix)
		  (allout-rebullet-heading nil		;;; instead
					    new-depth	;;; new-depth
					    number-control;;; number-control
					    index	;;; index
					    nil)))))	;;;(dont!)do-successors
      )	; (if (and (= current-depth new-depth)...))
    ) ; let* ((current-depth (allout-depth))...)
  ) ; defun