Function: allout-make-topic-prefix
allout-make-topic-prefix is a byte-compiled function defined in
allout.el.gz.
Signature
(allout-make-topic-prefix &optional PRIOR-BULLET NEW DEPTH INSTEAD NUMBER-CONTROL INDEX)
Documentation
Generate a topic prefix suitable for optional arg DEPTH, or current depth.
All the arguments are optional.
PRIOR-BULLET indicates the bullet of the prefix being changed, or
nil if none. This bullet may be preserved (other options
notwithstanding) if it is on the allout-distinctive-bullets-string,
for instance.
Second arg NEW indicates that a new topic is being opened after the topic at point, if non-nil. Default bullet for new topics, eg, may be set (contingent to other args) to numbered bullets if previous sibling is one. The implication otherwise is that the current topic is being adjusted -- shifted or rebulleted -- and we don't consider bullet or previous sibling.
Third arg DEPTH forces the topic prefix to that depth, regardless of the current topics' depth.
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
(INSTEAD overrides other options, including, eg, a distinctive
PRIOR-BULLET.)
Fifth arg, NUMBER-CONTROL, matters only if allout-numbered-bullet
is non-nil *and* no specific INSTEAD was specified. Then
NUMBER-CONTROL non-nil forces prefix to either numbered or
unnumbered format, depending on the value of the sixth arg, INDEX.
(Note that NUMBER-CONTROL does *not* apply to level 1 topics. Sorry...)
If NUMBER-CONTROL is non-nil and sixth arg INDEX is non-nil then the prefix of the topic is forced to be numbered. Non-nil NUMBER-CONTROL and nil INDEX forces non-numbered format on the bullet. Non-nil NUMBER-CONTROL and non-nil, non-number INDEX means that the index for the numbered prefix will be derived, by counting siblings back to start of level. If INDEX is a number, then that number is used as the index for the numbered prefix (allowing, eg, sequential renumbering to not require this function counting back the index for each successive sibling).
Source Code
;; Defined in /usr/src/emacs/lisp/allout.el.gz
;;;_ - Topic Production
;;;_ > allout-make-topic-prefix (&optional prior-bullet
(defun allout-make-topic-prefix (&optional prior-bullet
new
depth
instead
number-control
index)
;; Depth null means use current depth, non-null means we're either
;; opening a new topic after current topic, lower or higher, or we're
;; changing level of current topic.
;; Instead dominates specified bullet-char.
;;;_ . Doc string:
"Generate a topic prefix suitable for optional arg DEPTH, or current depth.
All the arguments are optional.
PRIOR-BULLET indicates the bullet of the prefix being changed, or
nil if none. This bullet may be preserved (other options
notwithstanding) if it is on the `allout-distinctive-bullets-string',
for instance.
Second arg NEW indicates that a new topic is being opened after the
topic at point, if non-nil. Default bullet for new topics, eg, may
be set (contingent to other args) to numbered bullets if previous
sibling is one. The implication otherwise is that the current topic
is being adjusted -- shifted or rebulleted -- and we don't consider
bullet or previous sibling.
Third arg DEPTH forces the topic prefix to that depth, regardless of
the current topics' depth.
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
\(INSTEAD overrides other options, including, eg, a distinctive
PRIOR-BULLET.)
Fifth arg, NUMBER-CONTROL, matters only if `allout-numbered-bullet'
is non-nil *and* no specific INSTEAD was specified. Then
NUMBER-CONTROL non-nil forces prefix to either numbered or
unnumbered format, depending on the value of the sixth arg, INDEX.
\(Note that NUMBER-CONTROL does *not* apply to level 1 topics. Sorry...)
If NUMBER-CONTROL is non-nil and sixth arg INDEX is non-nil then
the prefix of the topic is forced to be numbered. Non-nil
NUMBER-CONTROL and nil INDEX forces non-numbered format on the
bullet. Non-nil NUMBER-CONTROL and non-nil, non-number INDEX means
that the index for the numbered prefix will be derived, by counting
siblings back to start of level. If INDEX is a number, then that
number is used as the index for the numbered prefix (allowing, eg,
sequential renumbering to not require this function counting back the
index for each successive sibling)."
;;;_ . Code:
;; The options are ordered in likely frequency of use, most common
;; highest, least lowest. Ie, more likely to be doing prefix
;; adjustments than soliciting, and yet more than numbering.
;; Current prefix is least dominant, but most likely to be commonly
;; specified...
(let* (body
numbering
denumbering
(depth (or depth (allout-depth)))
(header-lead allout-header-prefix)
(bullet-char
;; Getting value for bullet char is practically the whole job:
(cond
; Simplest situation -- level 1:
((<= depth 1) (setq header-lead "") allout-primary-bullet)
; Simple, too: all asterisks:
(allout-old-style-prefixes
;; Cheat -- make body the whole thing, null out header-lead and
;; bullet-char:
(setq body (make-string depth
(string-to-char allout-primary-bullet)))
(setq header-lead "")
"")
;; (Neither level 1 nor old-style, so we're space padding.
;; Sneak it in the condition of the next case, whatever it is.)
;; Solicitation overrides numbering and other cases:
((progn (setq body (make-string (- depth 2) ?\ ))
;; The actual condition:
instead)
(let ((got (cond ((stringp instead)
(if (> (length instead) 0)
(allout-solicit-alternate-bullet
depth (substring instead 0 1))))
((characterp instead) (char-to-string instead))
(t (allout-solicit-alternate-bullet depth)))))
;; Gotta check whether we're numbering and got a numbered bullet:
(setq numbering (and allout-numbered-bullet
(not (and number-control (not index)))
(string= got allout-numbered-bullet)))
;; Now return what we got, regardless:
got))
;; Numbering invoked through args:
((and allout-numbered-bullet number-control)
(if (setq numbering (not (setq denumbering (not index))))
allout-numbered-bullet
(if (and prior-bullet
(not (string= allout-numbered-bullet
prior-bullet)))
prior-bullet
(allout-bullet-for-depth depth))))
;;; Neither soliciting nor controlled numbering ;;;
;;; (may be controlled denumbering, tho) ;;;
;; Check wrt previous sibling:
((and new ; only check for new prefixes
(<= depth (allout-depth))
allout-numbered-bullet ; ... & numbering enabled
(not denumbering)
(let ((sibling-bullet
(save-excursion
;; Locate correct sibling:
(or (>= depth (allout-depth))
(allout-ascend-to-depth depth))
(allout-get-bullet))))
(if (and sibling-bullet
(string= allout-numbered-bullet sibling-bullet))
(setq numbering sibling-bullet)))))
;; Distinctive prior bullet?
((and prior-bullet
(allout-distinctive-bullet prior-bullet)
;; Either non-numbered:
(or (not (and allout-numbered-bullet
(string= prior-bullet allout-numbered-bullet)))
;; or numbered, and not denumbering:
(setq numbering (not denumbering)))
;; Here 'tis:
prior-bullet))
;; Else, standard bullet per depth:
((allout-bullet-for-depth depth)))))
(concat header-lead
body
bullet-char
(if numbering
(format "%d" (cond ((and index (numberp index)) index)
(new (1+ (allout-sibling-index depth)))
((allout-sibling-index))))))
)
)