;;; allout.el --- extensive outline mode for use alone and with other modes
-;; Copyright (C) 1992-1994, 2001-2013 Free Software Foundation, Inc.
+;; Copyright (C) 1992-1994, 2001-2016 Free Software Foundation, Inc.
;; Author: Ken Manheimer <ken dot manheimer at gmail...>
;; Maintainer: Ken Manheimer <ken dot manheimer at gmail...>
;;; Code:
+(declare-function epa-passphrase-callback-function
+ "epa" (context key-id handback))
+
;;;_* Dependency loads
(require 'overlay)
(eval-when-compile
(defcustom allout-command-prefix "\C-c "
"Key sequence to be used as prefix for outline mode command key bindings.
-Default is '\C-c<space>'; just '\C-c' is more short-and-sweet, if you're
+Default is `\C-c<space>'; just `\C-c' is more short-and-sweet, if you're
willing to let allout use a bunch of \C-c keybindings."
:type 'string
:group 'allout-keybindings
that are not prefixed.
Use vector format for the keys:
- - put literal keys after a '?' question mark, eg: '?a', '?.'
+ - put literal keys after a `?' question mark, eg: `?a', `?.'
- enclose control, shift, or meta-modified keys as sequences within
parentheses, with the literal key, as above, preceded by the name(s)
of the modifiers, eg: [(control ?a)]
preceding command key.
Use vector format for the keys:
- - put literal keys after a '?' question mark, eg: '?a', '?.'
+ - put literal keys after a `?' question mark, eg: `?a', `?.'
- enclose control, shift, or meta-modified keys as sequences within
parentheses, with the literal key, as above, preceded by the name(s)
of the modifiers, eg: [(control ?a)]
"Default allout outline layout specification.
This setting specifies the outline exposure to use when
-`allout-layout' has the local value `t'. This docstring describes the
+`allout-layout' has the local value t. This docstring describes the
layout specifications.
A list value specifies a default layout for the current buffer,
See `allout-plain-bullets-string' for the standard, alternating
bullets.
-You must run `set-allout-regexp' in order for outline mode to
+You must run `allout-set-regexp' in order for outline mode to
adopt changes of this value.
DO NOT include the close-square-bracket, `]', on either of the bullet
Allout outline mode will use the mode-specific `allout-mode-leaders' or
comment-start string, if any, to lead the topic prefix string, so topic
headers look like comments in the programming language. It will also use
-the comment-start string, with an '_' appended, for `allout-primary-bullet'.
+the comment-start string, with an `_' appended, for `allout-primary-bullet'.
String values are used as literals, not regular expressions, so
do not escape any regular-expression characters.
:group 'allout)
;;;_ - allout-title
(defcustom allout-title '(or buffer-file-name (buffer-name))
- "Expression to be evaluated to determine the title for LaTeX
-formatted copy."
+ "Expression to evaluate to determine the title for LaTeX formatted copy."
:type 'sexp
+ :risky t
:group 'allout)
;;;_ - allout-line-skip
(defcustom allout-line-skip ".05cm"
automatically activated. The layout dictated by the value will be used to
set the initial exposure when `allout-mode' is activated.
-\*You should not setq-default this variable non-nil unless you want every
+*You should not setq-default this variable non-nil unless you want every
visited file to be treated as an allout file.*
The value would typically be set by a file local variable. For
\(This is the layout used for the allout.el source file.)
`allout-default-layout' describes the specification format.
-`allout-layout' can additionally have the value `t', in which
+`allout-layout' can additionally have the value t, in which
case the value of `allout-default-layout' is used.")
(make-variable-buffer-local 'allout-layout)
;;;###autoload
Any line whose beginning matches this regexp is considered a
heading. This var is set according to the user configuration vars
-by `set-allout-regexp'.")
+by `allout-set-regexp'.")
(make-variable-buffer-local 'allout-regexp)
;;;_ = allout-bullets-string
(defvar allout-bullets-string ""
"A string dictating the valid set of outline topic bullets.
-This var should *not* be set by the user -- it is set by `set-allout-regexp',
+This var should *not* be set by the user -- it is set by `allout-set-regexp',
and is produced from the elements of `allout-plain-bullets-string'
and `allout-distinctive-bullets-string'.")
(make-variable-buffer-local 'allout-bullets-string)
for to seek topics at depth one.
This var is set according to the user configuration vars by
-`set-allout-regexp'. It is prepared with format strings for two
+`allout-set-regexp'. It is prepared with format strings for two
decimal numbers, which should each be one less than the depth of the
topic prefix to be matched.")
(make-variable-buffer-local 'allout-depth-specific-regexp)
"Regular expression to match a heading line prefix for depth one.
This var is set according to the user configuration vars by
-`set-allout-regexp'. It is prepared with format strings for two
+`allout-set-regexp'. It is prepared with format strings for two
decimal numbers, which should each be one less than the depth of the
topic prefix to be matched.")
(make-variable-buffer-local 'allout-depth-one-regexp)
(defvar allout-line-boundary-regexp ()
"`allout-regexp' prepended with a newline for the search target.
-This is properly set by `set-allout-regexp'.")
+This is properly set by `allout-set-regexp'.")
(make-variable-buffer-local 'allout-line-boundary-regexp)
;;;_ = allout-bob-regexp
(defvar allout-bob-regexp ()
(make-variable-buffer-local 'allout-header-subtraction)
;;;_ = allout-plain-bullets-string-len
(defvar allout-plain-bullets-string-len (length allout-plain-bullets-string)
- "Length of `allout-plain-bullets-string', updated by `set-allout-regexp'.")
+ "Length of `allout-plain-bullets-string', updated by `allout-set-regexp'.")
(make-variable-buffer-local 'allout-plain-bullets-string-len)
;;;_ = allout-doublecheck-at-and-shallower
being followed by a legitimate item of excessively greater depth.
The classic example of a mistaken item, for a standard allout
-outline configuration, is a body line that begins with an '...'
+outline configuration, is a body line that begins with an `...'
ellipsis. This happens to contain a legitimate depth-2 header
-prefix, constituted by two '..' dots at the beginning of the
+prefix, constituted by two `..' dots at the beginning of the
line. The only thing that can distinguish it *in principle* from
a legitimate one is if the following real header is at a depth
that is discontinuous from the depth of 2 implied by the
(interactive "sNew lead string: ")
(setq allout-header-prefix header-lead)
(setq allout-header-subtraction (1- (length allout-header-prefix)))
- (set-allout-regexp))
+ (allout-set-regexp))
;;;_ X allout-lead-with-comment-string (header-lead)
(defun allout-lead-with-comment-string (&optional header-lead)
"Set the topic-header leading string to specified string.
comment-start
(not (eq 'force allout-reindent-bodies)))
(setq allout-reindent-bodies nil)))
-;;;_ > set-allout-regexp ()
-(defun set-allout-regexp ()
+;;;_ > allout-set-regexp ()
+(defun allout-set-regexp ()
"Generate proper topic-header regexp form for outline functions.
Works with respect to `allout-plain-bullets-string' and
"[^" allout-primary-bullet "]"))
"\\)"
))))
+(define-obsolete-function-alias 'set-allout-regexp 'allout-set-regexp "25.2")
;;;_ : Menu bar
(defvar allout-mode-exposure-menu)
(defvar allout-mode-editing-menu)
(defvar allout-mode-navigation-menu)
(defvar allout-mode-misc-menu)
-(defun produce-allout-mode-menubar-entries ()
+(defun allout-produce-mode-menubar-entries ()
(require 'easymenu)
(easy-menu-define allout-mode-exposure-menu
allout-mode-map-value
buffer-local value, then it is left as nil on resumption.
The pairs are lists whose car is the name of the variable and car of the
-cdr is the new value: '(some-var some-value)'. The pairs can actually be
+cdr is the new value: `(some-var some-value)'. The pairs can actually be
triples, where the third element qualifies the disposition of the setting,
as described further below.
-If the optional third element is the symbol 'extend, then the new value
+If the optional third element is the symbol `extend', then the new value
created by `cons'ing the second element of the pair onto the front of the
existing value.
-If the optional third element is the symbol 'append, then the new value is
+If the optional third element is the symbol `append', then the new value is
extended from the existing one by `append'ing a list containing the second
element of the pair onto the end of the existing value.
Extension, and resumptions in general, should not be used for hook
-functions -- use the 'local mode of `add-hook' for that, instead.
+functions -- use the `local' mode of `add-hook' for that, instead.
The settings are stored on `allout-mode-prior-settings'."
(while pairs
It consists of an encrypted random string useful only to verify that a
passphrase entered by the user is effective for decryption. The passphrase
-itself is \*not* recorded in the file anywhere, and the encrypted contents
+itself is *not* recorded in the file anywhere, and the encrypted contents
are random binary characters to avoid exposing greater susceptibility to
search attacks.
buffer with name derived from derived from that
of current buffer -- \"*BUFFERNAME exposed*\".
\\[allout-flatten-exposed-to-buffer] `allout-flatten-exposed-to-buffer'
- Like above 'copy-exposed', but convert topic
+ Like above `copy-exposed', but convert topic
prefixes to section.subsection... numeric
format.
\\[customize-variable] allout-auto-activation
subsequent decryption attempts until the cache times-out. That
can take several minutes. (Decryption of other entries is not
affected.) Upgrade your EasyPG version, if you can, and you can
-deliberately clear your gpg-agent's cache by sending it a '-HUP'
+deliberately clear your gpg-agent's cache by sending it a `-HUP'
signal.
See `allout-toggle-current-subtree-encryption' function docstring
(allout-infer-header-lead-and-primary-bullet)
(allout-infer-body-reindent)
- (set-allout-regexp)
+ (allout-set-regexp)
(allout-add-resumptions '(allout-encryption-ciphertext-rejection-regexps
allout-line-boundary-regexp
extend)
extend))
(allout-compose-and-institute-keymap)
- (produce-allout-mode-menubar-entries)
+ (allout-produce-mode-menubar-entries)
(add-to-invisibility-spec '(allout . t))
use-layout
(and (not (string= allout-auto-activation "activate"))
(if (string= allout-auto-activation "ask")
- (if (y-or-n-p (format "Expose %s with layout '%s'? "
- (buffer-name)
- use-layout))
+ (if (y-or-n-p (format-message
+ "Expose %s with layout `%s'? "
+ (buffer-name) use-layout))
t
(message "Skipped %s layout." (buffer-name))
nil)
t)))
(save-excursion
- (message "Adjusting '%s' exposure..." (buffer-name))
+ (message "Adjusting `%s' exposure..." (buffer-name))
(goto-char 0)
(allout-this-or-next-heading)
(condition-case err
(progn
(apply 'allout-expose-topic (list use-layout))
- (message "Adjusting '%s' exposure... done."
+ (message "Adjusting `%s' exposure... done."
(buffer-name)))
;; Problem applying exposure -- notify user, but don't
;; interrupt, eg, file visit:
;;;_ > allout-overlay-insert-in-front-handler (ol after beg end
;;; &optional prelen)
-(defun allout-overlay-insert-in-front-handler (ol after beg end
- &optional prelen)
+(defun allout-overlay-insert-in-front-handler (ol after beg _end
+ &optional _prelen)
"Shift the overlay so stuff inserted in front of it is excluded."
(if after
;; ??? Shouldn't moving the overlay should be unnecessary, if overlay
;;;_ > allout-overlay-interior-modification-handler (ol after beg end
;;; &optional prelen)
(defun allout-overlay-interior-modification-handler (ol after beg end
- &optional prelen)
+ &optional _prelen)
"Get confirmation before making arbitrary changes to invisible text.
We expose the invisible text and ask for confirmation. Refusal or
(allout-overlay-interior-modification-handler
overlay nil beg end nil))))))
;;;_ > allout-isearch-end-handler (&optional overlay)
-(defun allout-isearch-end-handler (&optional overlay)
+(defun allout-isearch-end-handler (&optional _overlay)
"Reconcile allout outline exposure on arriving in hidden text after isearch.
Optional OVERLAY parameter is for when this function is used by
allout-recent-prefix-beginning
allout-header-subtraction)))
allout-recent-prefix-beginning)
-;;;_ > nullify-allout-prefix-data ()
-(defsubst nullify-allout-prefix-data ()
+;;;_ > allout-nullify-prefix-data ()
+(defsubst allout-nullify-prefix-data ()
"Mark allout prefix data as being uninformative."
(setq allout-recent-prefix-end (point)
allout-recent-prefix-beginning (point)
allout-recent-depth
(progn
;; Oops, no prefix, nullify it:
- (nullify-allout-prefix-data)
+ (allout-nullify-prefix-data)
;; ... and return 0:
0)))))
;;;_ > allout-current-depth ()
; and maybe not preferable.
))
;;;_ > allout-chart-siblings (&optional start end)
-(defun allout-chart-siblings (&optional start end)
+(defun allout-chart-siblings (&optional _start _end)
"Produce a list of locations of this and succeeding sibling topics.
Effectively a top-level chart of siblings. See `allout-chart-subtree'
for an explanation of charts."
nil))
)
;;;_ > allout-up-current-level (arg)
-(defun allout-up-current-level (arg)
+(defun allout-up-current-level (_arg)
"Move out ARG levels from current visible topic."
(interactive "p")
(let ((start-point (point)))
"Go back to the first sibling at this level, visible or not."
(allout-end-of-level 'backward))
;;;_ > allout-end-of-level (&optional backward)
-(defun allout-end-of-level (&optional backward)
+(defun allout-end-of-level (&optional _backward)
"Go to the last sibling at this level, visible or not."
(let ((depth (allout-depth)))
(let* ((default-bullet (or (and (stringp current-bullet) current-bullet)
(allout-bullet-for-depth depth)))
- (sans-escapes (regexp-sans-escapes allout-bullets-string))
+ (sans-escapes (allout-regexp-sans-escapes allout-bullets-string))
choice)
(save-excursion
(goto-char (allout-current-bullet-pos))
- (setq choice (solicit-char-in-string
- (format "Select bullet: %s ('%s' default): "
- sans-escapes
- (allout-substring-no-properties default-bullet))
+ (setq choice (allout-solicit-char-in-string
+ (format-message
+ "Select bullet: %s (`%s' default): "
+ sans-escapes
+ (allout-substring-no-properties default-bullet))
sans-escapes
t)))
(message "")
(save-match-data
(let* ((inhibit-field-text-motion t)
(depth (+ (allout-current-depth) relative-depth))
- (opening-on-blank (if (looking-at "^\$")
+ (opening-on-blank (if (looking-at "^$")
(not (setq before nil))))
;; bunch o vars set while computing ref-topic
opening-numbered
(if (or allout-former-auto-filler allout-use-hanging-indents)
(funcall use-auto-fill-function)))))
;;;_ > allout-reindent-body (old-depth new-depth &optional number)
-(defun allout-reindent-body (old-depth new-depth &optional number)
+(defun allout-reindent-body (old-depth new-depth &optional _number)
"Reindent body lines which were indented at OLD-DEPTH to NEW-DEPTH.
Optional arg NUMBER indicates numbering is being added, and it must
(if next (goto-char next)))))
(set-buffer-modified-p was-modified))))
;;;_ > allout-yank-processing ()
-(defun allout-yank-processing (&optional arg)
+(defun allout-yank-processing (&optional _arg)
"Incidental allout-specific business to be done just after text yanks.
- - exposes the body of the corresponding topic.
Examples:
-\(allout-expose-topic '(-1 : 0))
+\(allout-expose-topic \\='(-1 : 0))
Close this and all following topics at current level, exposing
only their immediate children, but close down the last topic
at this current level completely.
-\(allout-expose-topic '(-1 () : 1 0))
+\(allout-expose-topic \\='(-1 () : 1 0))
Close current topic so only the immediate subtopics are shown;
show the children in the second to last topic, and completely
close the last one.
-\(allout-expose-topic '(-2 : -1 *))
+\(allout-expose-topic \\='(-2 : -1 *))
Expose children and grandchildren of all topics at current
level except the last two; expose children of the second to
last and completely open the last one."
;;_ > allout-process-exposed (&optional func from to frombuf
;;; tobuf format)
(defun allout-process-exposed (&optional func from to frombuf tobuf
- format start-num)
+ format _start-num)
"Map function on exposed parts of current topic; results to another buffer.
All args are options; default values itemized below.
;; Specified but not a buffer -- get it:
(let ((got (get-buffer frombuf)))
(if (not got)
- (error (concat "allout-process-exposed: source buffer "
- frombuf
- " not found."))
+ (error "allout-process-exposed: source buffer %s not found."
+ frombuf)
(setq frombuf got))))
;; not specified -- default it:
(setq frombuf (current-buffer)))
LISTIFIED is a list representing each topic header and body:
- \`(depth prefix text)'
+ `(depth prefix text)'
-or \`(depth prefix text bullet-plus)'
+or `(depth prefix text bullet-plus)'
If `bullet-plus' is specified, it is inserted just after the entire prefix."
(setq listified (cdr listified))
;;;_ - LaTeX formatting
;;;_ > allout-latex-verb-quote (string &optional flow)
-(defun allout-latex-verb-quote (string &optional flow)
+(defun allout-latex-verb-quote (string &optional _flow)
"Return copy of STRING for literal reproduction across LaTeX processing.
Expresses the original characters (including carriage returns) of the
string across LaTeX processing."
environment. Leaves point at the end of the line."
(let ((inhibit-field-text-motion t))
(beginning-of-line)
- (let ((beg (point))
+ (let (;(beg (point))
(end (point-at-eol)))
(save-match-data
(while (re-search-forward "\\\\"
(set-buffer buffer)
(insert "\n\\end{document}\n"))
;;;_ > allout-latexify-one-item (depth prefix bullet text)
-(defun allout-latexify-one-item (depth prefix bullet text)
+(defun allout-latexify-one-item (depth _prefix bullet text)
"Insert LaTeX commands for formatting one outline item.
Args are the topics numeric DEPTH, the header PREFIX lead string, the
(defun allout-toggle-current-subtree-encryption (&optional keymode-cue)
"Encrypt clear or decrypt encoded topic text.
-Allout uses Emacs 'epg' library to perform encryption. Symmetric
+Allout uses Emacs `epg' library to perform encryption. Symmetric
and keypair encryption are supported. All encryption is ascii
armored.
encryption are encrypted. See `allout-encrypt-unencrypted-on-saves'
for auto-encryption specifics.
-\*NOTE WELL* that automatic encryption that happens during saves will
+*NOTE WELL* that automatic encryption that happens during saves will
default to symmetric encryption -- you must deliberately (re)encrypt key-pair
encrypted topics if you want them to continue to use the key-pair cipher.
recipients with the file, by selecting no recipients in the
dialog.
-Encryption and decryption uses the Emacs 'epg' library.
+Encryption and decryption uses the Emacs `epg' library.
Encrypted text will be ascii-armored.
(declare-function epg-decrypt-string "epg" (context cipher))
(declare-function epg-encrypt-string "epg"
(context plain recipients &optional sign always-trust))
-(declare-function epg-user-id-string "epg" (user-id))
-(declare-function epg-key-user-id-list "epg" (key))
+(declare-function epg-user-id-string "epg" (user-id) t)
+(declare-function epg-key-user-id-list "epg" (key) t)
;;;_ > allout-encrypt-string (text decrypt allout-buffer keymode-cue
;;; &optional rejected)
subsequent decryption attempts until the cache times-out. That
can take several minutes. (Decryption of other entries is not
affected.) Upgrade your EasyPG version, if you can, and you can
-deliberately clear your gpg-agent's cache by sending it a '-HUP'
+deliberately clear your gpg-agent's cache by sending it a `-HUP'
signal."
(require 'epg)
"Return the point of the next topic pending encryption, or nil if none.
Such a topic has the `allout-topic-encryption-bullet' without an
-immediately following '*' that would mark the topic as being encrypted.
+immediately following `*' that would mark the topic as being encrypted.
It must also have content."
(let (done got content-beg)
(save-match-data
;; we had to wait for this 'til now so prior topics are
;; encrypted, any relevant text shifts are in place:
editing-point (- current-mark-position
- (count-trailing-whitespace-region
+ (allout-count-trailing-whitespace-region
bo-subtree current-mark-position))))
(allout-toggle-subtree-encryption)
(if (not was-modified)
;;;###autoload
(defalias 'outlinify-sticky 'outlineify-sticky)
;;;###autoload
-(defun outlineify-sticky (&optional arg)
+(defun outlineify-sticky (&optional _arg)
"Activate outline mode and establish file var so it is started subsequently.
See `allout-layout' and customization of `allout-auto-activation'
(if (allout-goto-prefix)
t
(allout-open-topic 2)
- (insert (concat "Dummy outline topic header -- see"
- "`allout-mode' docstring: `^Hm'."))
+ (insert (substitute-command-keys
+ (concat "Dummy outline topic header -- see"
+ " `allout-mode' docstring: `\\[describe-mode]'.")))
(allout-adjust-file-variable
"allout-layout" (or allout-layout '(-1 : 0))))))
;;;_ > allout-file-vars-section-data ()
got)
(dolist (sym configvar-value)
(if (not (boundp sym))
- (if (yes-or-no-p (format "%s entry `%s' is unbound -- remove it? "
- configvar-name sym))
+ (if (yes-or-no-p (format-message
+ "%s entry `%s' is unbound -- remove it? "
+ configvar-name sym))
(delq sym (symbol-value configvar-name)))
(push (symbol-value sym) got)))
(reverse got)))
(allout-end-of-current-subtree)
(exchange-point-and-mark))
;;;_ : UI:
-;;;_ > solicit-char-in-string (prompt string &optional do-defaulting)
-(defun solicit-char-in-string (prompt string &optional do-defaulting)
+;;;_ > allout-solicit-char-in-string (prompt string &optional do-defaulting)
+(defun allout-solicit-char-in-string (prompt string &optional do-defaulting)
"Solicit (with first arg PROMPT) choice of a character from string STRING.
Optional arg DO-DEFAULTING indicates to accept empty input (CR)."
got)
)
;;;_ : Strings:
-;;;_ > regexp-sans-escapes (string)
-(defun regexp-sans-escapes (regexp &optional successive-backslashes)
+;;;_ > allout-regexp-sans-escapes (string)
+(defun allout-regexp-sans-escapes (regexp &optional successive-backslashes)
"Return a copy of REGEXP with all character escapes stripped out.
-Representations of actual backslashes -- '\\\\\\\\' -- are left as a
+Representations of actual backslashes -- `\\\\\\\\' -- are left as a
single backslash.
Optional arg SUCCESSIVE-BACKSLASHES is used internally for recursion."
(if (or (not successive-backslashes) (= 2 successive-backslashes))
;; Include first char:
(concat (substring regexp 0 1)
- (regexp-sans-escapes (substring regexp 1)))
+ (allout-regexp-sans-escapes (substring regexp 1)))
;; Exclude first char, but maintain count:
- (regexp-sans-escapes (substring regexp 1) successive-backslashes))))
-;;;_ > count-trailing-whitespace-region (beg end)
-(defun count-trailing-whitespace-region (beg end)
+ (allout-regexp-sans-escapes (substring regexp 1) successive-backslashes))))
+;;;_ > allout-count-trailing-whitespace-region (beg end)
+(defun allout-count-trailing-whitespace-region (beg end)
"Return number of trailing whitespace chars between BEG and END.
If BEG is bigger than END we return 0."
"Isearch (regexp) for topic with bullet BULLET."
(interactive)
(if (not bullet)
- (setq bullet (solicit-char-in-string
+ (setq bullet (allout-solicit-char-in-string
"ISearch for topic with bullet: "
- (regexp-sans-escapes allout-bullets-string))))
+ (allout-regexp-sans-escapes allout-bullets-string))))
(let ((isearch-regexp t)
(isearch-string (concat "^"