Function: allout-show-children

allout-show-children is an interactive and byte-compiled function defined in allout.el.gz.

Signature

(allout-show-children &optional LEVEL STRICT)

Documentation

If point is visible, show all direct subheadings of this heading.

Otherwise, do allout-show-to-offshoot, and then show subheadings.

Optional LEVEL specifies how many levels below the current level should be shown, or all levels if t. Default is 1.

Optional STRICT means don't resort to -show-to-offshoot, no matter what. This is basically so -show-to-offshoot, which is called by this function, can employ the pure offspring-revealing capabilities of it.

Returns point at end of subtree that was opened, if any. (May get a point of non-opened subtree?)

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/allout.el.gz
;;;_   > allout-show-children (&optional level strict)
(defun allout-show-children (&optional level strict)

  "If point is visible, show all direct subheadings of this heading.

Otherwise, do `allout-show-to-offshoot', and then show subheadings.

Optional LEVEL specifies how many levels below the current level
should be shown, or all levels if t.  Default is 1.

Optional STRICT means don't resort to -show-to-offshoot, no matter
what.  This is basically so -show-to-offshoot, which is called by
this function, can employ the pure offspring-revealing capabilities of
it.

Returns point at end of subtree that was opened, if any.  (May get a
point of non-opened subtree?)"

  (interactive "p")
  (let ((start-point (point)))
    (if (and (not strict)
             (allout-hidden-p))

        (progn (allout-show-to-offshoot) ; Point's concealed, open to
                                        ; expose it.
               ;; Then recurse, but with "strict" set so we don't
               ;; infinite regress:
               (allout-show-children level t))

      (save-excursion
        (allout-beginning-of-current-line)
        (save-restriction
          (let* (depth
                 ;; translate the level spec for this routine to the ones
                 ;; used by -chart-subtree and -chart-to-reveal:
                 (chart-level (cond ((not level) 1)
                                    ((eq level t) nil)
                                    (t level)))
                 (chart (allout-chart-subtree chart-level))
                 (to-reveal (or (allout-chart-to-reveal chart chart-level)
                                ;; interactive, show discontinuous children:
                                (and chart
                                     (allout-called-interactively-p)
                                     (save-excursion
                                       (allout-back-to-current-heading)
                                       (setq depth (allout-current-depth))
                                       (and (allout-next-heading)
                                            (> allout-recent-depth
                                               (1+ depth))))
                                     (message
                                      "Discontinuous offspring; use `%s %s'%s."
                                      (substitute-command-keys
                                       "\\[universal-argument]")
                                      (substitute-command-keys
                                       "\\[allout-shift-out]")
                                      " to elevate them.")
                                     (allout-chart-to-reveal
                                      chart (- allout-recent-depth depth))))))
            (goto-char start-point)
            (when (and strict (allout-hidden-p))
              ;; Concealed root would already have been taken care of,
              ;; unless strict was set.
              (allout-flag-region (point) (allout-snug-back) nil)
              (when allout-show-bodies
                (goto-char (car to-reveal))
                (allout-show-current-entry)))
            (while to-reveal
              (goto-char (car to-reveal))
              (allout-flag-region (save-excursion (allout-snug-back) (point))
                                  (progn (search-forward "\n" nil t)
                                         (1- (point)))
                                  nil)
              (when allout-show-bodies
                (goto-char (car to-reveal))
                (allout-show-current-entry))
              (setq to-reveal (cdr to-reveal)))))))
    ;; Compensate for `save-excursion's maintenance of point
    ;; within invisible text:
    (goto-char start-point)))