Function: allout-rebullet-topic-grunt

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

Signature

(allout-rebullet-topic-grunt &optional RELATIVE-DEPTH STARTING-DEPTH STARTING-POINT INDEX DO-SUCCESSORS SANS-OFFSPRING)

Documentation

Like allout-rebullet-topic, but on nearest containing topic (visible or not).

See allout-rebullet-heading for rebulleting behavior.

All arguments are optional.

First arg RELATIVE-DEPTH means to shift the depth of the entire topic that amount.

Several subsequent args are for internal recursive use by the function itself: STARTING-DEPTH, STARTING-POINT, and INDEX.

Finally, if optional SANS-OFFSPRING is non-nil then the offspring are not shifted. (Shifting a topic outwards without shifting its offspring is disallowed, since this would create a
"containment discontinuity", where the depth difference between
a topic and its immediate offspring is greater than one.)

Source Code

;; Defined in /usr/src/emacs/lisp/allout.el.gz
;;;_    > allout-rebullet-topic-grunt (&optional relative-depth ...)
(defun allout-rebullet-topic-grunt (&optional relative-depth
                                               starting-depth
                                               starting-point
                                               index
                                               do-successors
                                               sans-offspring)
  "Like `allout-rebullet-topic', but on nearest containing topic (visible or not).

See `allout-rebullet-heading' for rebulleting behavior.

All arguments are optional.

First arg RELATIVE-DEPTH means to shift the depth of the entire
topic that amount.

Several subsequent args are for internal recursive use by the function
itself: STARTING-DEPTH, STARTING-POINT, and INDEX.

Finally, if optional SANS-OFFSPRING is non-nil then the offspring
are not shifted.  (Shifting a topic outwards without shifting
its offspring is disallowed, since this would create a
\"containment discontinuity\", where the depth difference between
a topic and its immediate offspring is greater than one.)"

  ;; XXX the recursion here is peculiar, and in general the routine may
  ;; need simplification with refactoring.

  (if (and sans-offspring
           relative-depth
           (< relative-depth 0))
      (error (concat "Attempt to shift topic outwards without offspring,"
                     " would cause containment discontinuity.")))

  (let* ((relative-depth (or relative-depth 0))
         (new-depth (allout-depth))
         (starting-depth (or starting-depth new-depth))
         (on-starting-call  (null starting-point))
         (index (or index
                    ;; Leave index null on starting call, so rebullet-heading
                    ;; calculates it at what might be new depth:
                    (and (or (zerop relative-depth)
                             (not on-starting-call))
                         (allout-sibling-index))))
         (starting-index index)
         (moving-outwards (< 0 relative-depth))
         (starting-point (or starting-point (point)))
         (local-point (point)))

    ;; Sanity check for excessive promotion done only on starting call:
    (and on-starting-call
         moving-outwards
         (> 0 (+ starting-depth relative-depth))
         (error "Attempt to shift topic out beyond level 1"))

    (cond ((= starting-depth new-depth)
           ;; We're at depth to work on this one.

           ;; When shifting out we work on the children before working on
           ;; the parent to avoid interim `allout-aberrant-container-p'
           ;; aberrancy, and vice-versa when shifting in:
           (if (>= relative-depth 0)
               (allout-rebullet-heading nil
                                        (+ starting-depth relative-depth)
                                        nil		;;; number
                                        index
                                        nil)) ;;; do-successors
           (when (not sans-offspring)
             ;; ... and work on subsequent ones which are at greater depth:
             (setq index 0)
             (allout-next-heading)
             (while (and (not (eobp))
                         (< starting-depth (allout-depth)))
               (setq index (1+ index))
               (allout-rebullet-topic-grunt relative-depth
                                            (1+ starting-depth)
                                            starting-point
                                            index)))
           (when (< relative-depth 0)
             (save-excursion
               (goto-char local-point)
               (allout-rebullet-heading nil               ;;; instead
                                        (+ starting-depth relative-depth)
                                        nil		;;; number
                                        starting-index
                                        nil)))) ;;; do-successors

          ((< starting-depth new-depth)
           ;; Rare case -- subtopic more than one level deeper than parent.
           ;; Treat this one at an even deeper level:
           (allout-rebullet-topic-grunt relative-depth
                                         new-depth
                                         starting-point
                                         index
                                         sans-offspring)))

    (if on-starting-call
        (progn
          ;; Rectify numbering of former siblings of the adjusted topic,
          ;; if topic has changed depth
          (if (or do-successors
                  (and (not (zerop relative-depth))
                       (or (= allout-recent-depth starting-depth)
                           (= allout-recent-depth (+ starting-depth
                                                        relative-depth)))))
              (allout-rebullet-heading nil nil nil nil t))
          ;; Now rectify numbering of new siblings of the adjusted topic,
          ;; if depth has been changed:
          (progn (goto-char starting-point)
                 (if (not (zerop relative-depth))
                     (allout-rebullet-heading nil nil nil nil t)))))
    )
  )