Function: allout-open-topic
allout-open-topic is a byte-compiled function defined in allout.el.gz.
Signature
(allout-open-topic RELATIVE-DEPTH &optional BEFORE OFFER-RECENT-BULLET)
Documentation
Open a new topic at depth DEPTH.
New topic is situated after current one, unless optional flag BEFORE is non-nil, or unless current line is completely empty -- lacking even whitespace -- in which case open is done on the current line.
When adding an offspring, it will be added immediately after the parent if the other offspring are exposed, or after the last child if the offspring are hidden. (The intervening offspring will be exposed in the latter case.)
If OFFER-RECENT-BULLET is true, offer to 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.
- New headers are generally created after/before the body of a
topic. However, they are created right at cursor location if the
cursor is on a blank line, even if that breaks the current topic
body. This is intentional, to provide a simple means for
deliberately dividing topic bodies.
- Double spacing of topic lists is preserved. Also, the first
level two topic is created double-spaced (and so would be
subsequent siblings, if that's left intact). Otherwise,
single-spacing is used.
- Creation of sibling or nested topics is with respect to the topic
you're starting from, even when creating backwards. This way you
can easily create a sibling in front of the current topic without
having to go to its preceding sibling, and then open forward
from there.
Source Code
;; Defined in /usr/src/emacs/lisp/allout.el.gz
;;;_ > allout-open-topic (relative-depth &optional before offer-recent-bullet)
(defun allout-open-topic (relative-depth &optional before offer-recent-bullet)
"Open a new topic at depth DEPTH.
New topic is situated after current one, unless optional flag BEFORE
is non-nil, or unless current line is completely empty -- lacking even
whitespace -- in which case open is done on the current line.
When adding an offspring, it will be added immediately after the parent if
the other offspring are exposed, or after the last child if the offspring
are hidden. (The intervening offspring will be exposed in the latter
case.)
If OFFER-RECENT-BULLET is true, offer to 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.
- New headers are generally created after/before the body of a
topic. However, they are created right at cursor location if the
cursor is on a blank line, even if that breaks the current topic
body. This is intentional, to provide a simple means for
deliberately dividing topic bodies.
- Double spacing of topic lists is preserved. Also, the first
level two topic is created double-spaced (and so would be
subsequent siblings, if that's left intact). Otherwise,
single-spacing is used.
- Creation of sibling or nested topics is with respect to the topic
you're starting from, even when creating backwards. This way you
can easily create a sibling in front of the current topic without
having to go to its preceding sibling, and then open forward
from there."
(allout-beginning-of-current-line)
(save-match-data
(let* ((inhibit-field-text-motion t)
(depth (+ (allout-current-depth) relative-depth))
(opening-on-blank (if (looking-at "^$")
(not (setq before nil))))
;; bunch o vars set while computing ref-topic
opening-numbered
ref-depth
ref-bullet
(ref-topic (save-excursion
(cond ((< relative-depth 0)
(allout-ascend-to-depth depth))
((>= relative-depth 1) nil)
(t (allout-back-to-current-heading)))
(setq ref-depth allout-recent-depth)
(setq ref-bullet
(if (> allout-recent-prefix-end 1)
(allout-recent-bullet)
""))
(setq opening-numbered
(save-excursion
(and allout-numbered-bullet
(or (<= relative-depth 0)
(allout-descend-to-depth depth))
(if (allout-numbered-type-prefix)
allout-numbered-bullet))))
(point)))
dbl-space
doing-beginning
start end)
(if (not opening-on-blank)
; Positioning and vertical
; padding -- only if not
; opening-on-blank:
(progn
(goto-char ref-topic)
(setq dbl-space ; Determine double space action:
(or (and (<= relative-depth 0) ; not descending;
(save-excursion
;; at b-o-b or preceded by a blank line?
(or (> 0 (forward-line -1))
(looking-at "^\\s-*$")
(bobp)))
(save-excursion
;; succeeded by a blank line?
(allout-end-of-current-subtree)
(looking-at "\n\n")))
(and (= ref-depth 1)
(or before
(= depth 1)
(save-excursion
;; Don't already have following
;; vertical padding:
(not (allout-pre-next-prefix)))))))
;; Position to prior heading, if inserting backwards, and not
;; going outwards:
(if (and before (>= relative-depth 0))
(progn (allout-back-to-current-heading)
(setq doing-beginning (bobp))
(if (not (bobp))
(allout-previous-heading)))
(if (and before (bobp))
(open-line 1)))
(if (<= relative-depth 0)
;; Not going inwards, don't snug up:
(if doing-beginning
(if (not dbl-space)
(open-line 1)
(open-line 2))
(if before
(progn (end-of-line)
(allout-pre-next-prefix)
(while (and (= ?\n (following-char))
(save-excursion
(forward-char 1)
(allout-hidden-p)))
(forward-char 1))
(if (not (looking-at "^$"))
(open-line 1)))
(allout-end-of-current-subtree)
(if (looking-at "\n\n") (forward-char 1))))
;; Going inwards -- double-space if first offspring is
;; double-spaced, otherwise snug up.
(allout-end-of-entry)
(if (eobp)
(newline 1)
(line-move 1))
(allout-beginning-of-current-line)
(backward-char 1)
(if (bolp)
;; Blank lines between current header body and next
;; header -- get to last substantive (non-white-space)
;; line in body:
(progn (setq dbl-space t)
(re-search-backward "[^ \t\n]" nil t)))
(if (looking-at "\n\n")
(setq dbl-space t))
(if (save-excursion
(allout-next-heading)
(when (> allout-recent-depth ref-depth)
;; This is an offspring.
(forward-line -1)
(looking-at "^\\s-*$")))
(progn (forward-line 1)
(open-line 1)
(forward-line 1)))
(allout-end-of-current-line))
;;(if doing-beginning (goto-char doing-beginning))
(if (not (bobp))
;; We insert a newline char rather than using open-line to
;; avoid rear-stickiness inheritance of read-only property.
(progn (if (and (not (> depth ref-depth))
(not before))
(open-line 1)
(if (and (not dbl-space) (> depth ref-depth))
(newline 1)
(if dbl-space
(open-line 1)
(if (not before)
(newline 1)))))
(if (and dbl-space (not (> relative-depth 0)))
(newline 1))
(if (and (not (eobp))
(or (not (bolp))
(and (not (bobp))
;; bolp doesn't detect concealed
;; trailing newlines, compensate:
(save-excursion
(forward-char -1)
(allout-hidden-p)))))
(forward-char 1))))
))
(setq start (point))
(insert (concat (allout-make-topic-prefix opening-numbered t depth)
" "))
(setq end (1+ (point)))
(allout-rebullet-heading (and offer-recent-bullet ref-bullet)
depth nil nil t)
(if (> relative-depth 0)
(save-excursion (goto-char ref-topic)
(allout-show-children)))
(end-of-line)
(run-hook-with-args 'allout-structure-added-functions start end)
)
)
)