Function: outline-show-entry-and-parents

outline-show-entry-and-parents is an interactive and byte-compiled function defined in outline.el.gz.

Signature

(outline-show-entry-and-parents)

Documentation

Reveal the current entry and its parent hierarchy.

This command ensures that the current entry, all of its ancestor headings, and their immediate sibling headings are visible.

The function iteratively unfolds the children and body of the target entry until it is fully revealed. If invoked when the point is inside a completely hidden subtree, it manages the visibility state to avoid leaving the buffer in an inconsistent layout. This guarantees a safe and predictable visual expansion.

View in manual

Probably introduced at or before Emacs version 32.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/outline.el.gz
(defun outline-show-entry-and-parents ()
  "Reveal the current entry and its parent hierarchy.
This command ensures that the current entry, all of its ancestor
headings, and their immediate sibling headings are visible.

The function iteratively unfolds the children and body of the target
entry until it is fully revealed.  If invoked when the point is inside
a completely hidden subtree, it manages the visibility state to avoid
leaving the buffer in an inconsistent layout.  This guarantees a safe
and predictable visual expansion."
  (interactive)
  ;; Wrap in `save-match-data' because outline functions use regular
  ;; expressions.  Without this, calling `outline-show-entry-and-parents'
  ;; programmatically would clobber the caller's match data, leading to
  ;; subtle, hard-to-trace bugs.
  (save-match-data
    ;; Repeatedly expand the outline structure at point from the outside
    ;; in until the target text is fully visible.
    ;;
    ;; Think of this block as manually opening nested folds:
    ;; - It checks whether the heading at point is folded.
    ;; - If it is folded, it moves backward to that parent heading.
    ;; - It opens the heading to reveal its text and subheadings.
    ;; - It repeats this process layer by layer down to the target.
    (let (heading-point
          prior-heading-point)
      (while (condition-case nil
                 (save-excursion
                   ;; Workaround: `outline-back-to-heading' throws an
                   ;; `outline-before-first-heading' error if the
                   ;; heading is on the first line (e.g., in
                   ;; `markdown-ts-mode') and point is deep within the
                   ;; hidden body of that folded first heading.
                   (vertical-motion 0)
                   ;; Navigate backward to the nearest visible heading
                   (outline-back-to-heading)
                   (setq heading-point (point))
                   ;; Break the loop if we stop making progress,
                   ;; preventing infinite recursion
                   (if (eq heading-point prior-heading-point)
                       ;; Break out of the loop
                       nil
                     (setq prior-heading-point heading-point)
                     ;; Check if the heading is folded by inspecting the
                     ;; end of the line
                     (when (invisible-p (pos-eol))
                       ;; Ignore errors to guarantee the target entry is
                       ;; still revealed via `outline-show-entry' even
                       ;; if a buggy third-party `outline-level'
                       ;; function fails during child expansion.
                       (ignore-errors (outline-show-children))

                       ;; Show the body directly following this heading
                       (outline-show-entry)

                       ;; Return t to continue drilling down to the next
                       ;; layer of the outline hierarchy
                       t)))
               (outline-before-first-heading
                nil))))))