branch: elpa/annotate
commit 2356f56bfec68210da4d6ad5ef117b285f5c8e0a
Author: cage <cage@invalid>
Commit: cage <cage@invalid>
- fixed type definition of customiziable variables related to font faces of
annotations, we can not know in advance the length of the plists bound to these
variables;
- fixed docstrings, only symbols names are wrapped in `…'.
---
annotate.el | 302 ++++++++++++++++++++++++++++++------------------------------
1 file changed, 150 insertions(+), 152 deletions(-)
diff --git a/annotate.el b/annotate.el
index be99622935..baa5b35bd9 100644
--- a/annotate.el
+++ b/annotate.el
@@ -86,8 +86,8 @@ See https://github.com/bastibe/annotate.el/ for
documentation."
:type 'file)
(defcustom annotate-file-buffer-local nil
- "If non nil (default `nil'), for each annotated file `filename', a database
-`filename.notes', containing the annotations, is generated in the
+ "If non nil (default `NIL'), for each annotated file 'filename', a database
+'filename.notes', containing the annotations, is generated in the
same directory that contains `filename'."
:type 'string)
@@ -100,13 +100,13 @@ name of the local database annotation"
(:underline "#92EEF1")
(:underline "#F192EE"))
"List of faces for annotated text."
- :type '(repeat (list symbol string)))
+ :type '(repeat (plist)))
(defcustom annotate-annotation-text-faces '((:background "#EEF192"
:foreground "black")
(:background "#92EEF1"
:foreground "black")
(:background "#F192EE"
:foreground "black"))
"List of faces for annotation's text."
- :type '(repeat (list symbol string symbol string)))
+ :type '(repeat (plist)))
(defface annotate-prefix
'((t (:inherit default)))
@@ -224,7 +224,7 @@ annotate-print-annotation-under-cursor is non nil"
"The delay (in seconds) after an annotation id printed in the
minibuffer, when the pursor is placed over an annotated text.
-This variable works only if `annotate-print-annotation-under-cursor' is non
nil"
+This variable works only if ANNOTATE-PRINT-ANNOTATION-UNDER-CURSOR is non nil"
:type 'float)
(defcustom annotate-warn-if-hash-mismatch t
@@ -406,8 +406,7 @@ in the customizable colors lists:
'annotate-error)
(cl-defmacro annotate-with-disable-read-only (&body body)
- "Run `BODY' with `READ-ONLY-MODE' temporary disabled."
- (declare (indent 0))
+ "Run BODY with `READ-ONLY-MODE' temporary disabled."
(let ((read-mode-p (gensym)))
`(let ((,read-mode-p (if buffer-read-only
1
@@ -425,7 +424,7 @@ in the customizable colors lists:
(defun annotate-initialize-maybe ()
"Initialize annotate mode only if buffer's major mode is not in the
blacklist.
-See `annotate-blacklist-major-mode'."
+See ANNOTATE-BLACKLIST-MAJOR-MODE."
(cl-flet ((shutdown ()
(setq annotate-mode t)
(annotate-shutdown)
@@ -442,7 +441,7 @@ See `annotate-blacklist-major-mode'."
(shutdown))))))
(cl-defun annotate-buffer-checksum (&optional (object (current-buffer)))
- "Calculate an hash for the argument `OBJECT'."
+ "Calculate an hash for the argument OBJECT."
(secure-hash 'md5 object))
(defun annotate-end-of-line-pos ()
@@ -458,37 +457,37 @@ position (so that it is unchanged after this function is
called)."
(point)))
(defun annotate-annotated-text-empty-p (annotation)
- "Does this `ANNOTATION' contains annotated text?"
+ "Does this ANNOTATION contains annotated text?"
(= (overlay-start annotation)
(overlay-end annotation)))
(defun annotate-annotation-set-face (annotation face)
- "Set property face to `FACE' for `ANNOTATION'."
+ "Set property face to FACE for ANNOTATION."
(overlay-put annotation 'face face))
(defun annotate-annotation-face (annotation)
- "Get property face from `ANNOTATION'."
+ "Get property face from ANNOTATION."
(overlay-get annotation 'face))
(defun annotate-annotation-set-annotation-face (annotation face)
- "Set property annotation-face to `FACE' for `ANNOTATION'."
+ "Set property annotation-face to FACE for ANNOTATION."
(overlay-put annotation 'annotation-face face))
(defun annotate-annotation-property-annotation-face (annotation)
- "Get property annotation-face from `ANNOTATION'."
+ "Get property annotation-face from ANNOTATION."
(overlay-get annotation 'annotation-face))
(defun annotate-annotation-set-annotation-text (annotation annotation-text)
- "Set the annotation's content for `ANNOTATION` to `ANNOTATION-TEXT`."
+ "Set the annotation's content for ANNOTATION to ANNOTATION-TEXT."
(overlay-put annotation 'annotation annotation-text))
(defun annotate-annotation-get-annotation-text (annotation)
- "Get the annotation's content for `ANNOTATION`."
+ "Get the annotation's content for ANNOTATION."
(overlay-get annotation 'annotation))
(defun annotate-annotation-set-position (annotation position)
- "Set the annotation's position policy for `ANNOTATION'
-to the value bound to `POSITION'."
+ "Set the annotation's position policy for ANNOTATION
+to the value bound to POSITION."
(overlay-put annotation 'annotate-position position))
(defun annotate-annotation-get-position (annotation)
@@ -496,33 +495,33 @@ to the value bound to `POSITION'."
(overlay-get annotation 'annotate-position))
(defun annotate-overlay-maybe-set-position (overlay position)
- "Set the annotation's position policy for `ANNOTATION' to the value bound
-to `POSITION',but only if the value of the property \\='position is not null."
+ "Set the annotation's position policy for OVERLAY to the value bound
+to POSITION,but only if the value of the property `position' is not null."
(when position
(annotate-annotation-set-position overlay position)))
(defun annotate-chain-last-ring (chain)
- "Get the last ring of `CHAIN'."
+ "Get the last ring of CHAIN."
(car (last chain)))
(defun annotate--remap-chain-pos (annotations)
- "Remap `ANNOTATIONS' as an annotation \"chain\".
+ "Remap ANNOTATIONS as an annotation \"chain\".
An annotation is a collection of one or more overlays that
-contains the property `ANNOTATE-PROP-CHAIN-POSITION'.
+contains the property `annotate-prop-chain-position'.
-The value of `ANNOTATE-PROP-CHAIN-POSITION' in each chain is an
+The value of `annotate-prop-chain-position' in each chain is an
integer starting from:
-`ANNOTATE-PROP-CHAIN-POS-MARKER-FIRST' and *always* ending with
+`annotate-prop-chain-pos-marker-first' and *always* ending with
-`ANNOTATE-PROP-CHAIN-POS-MARKER-LAST'
+`annotate-prop-chain-pos-marker-last'
This means that a value of said property for a chain that
contains only an element is equal to
-`ANNOTATE-PROP-CHAIN-POS-MARKER-LAST'.
+`annotate-prop-chain-pos-marker-last'.
-This function ensure this constrains for the chain `ANNOTATION'
+This function ensure this constrains for the chain ANNOTATION
belong."
(cond
((< (length annotations)
@@ -575,11 +574,11 @@ modified (for example a newline is inserted)."
(defun on-window-size-change (_frame)
"The function to call when window-size-change-functions is called,
-note that the argument `FRAME' is ignored"
+note that the argument _FRAME is ignored"
(font-lock-flush))
(defun annotate--filepath->local-database-name (filepath)
- "Generates the file path of the local database form `FILEPATH'."
+ "Generates the file path of the local database form FILEPATH."
(concat (file-name-nondirectory filepath)
"."
annotate-buffer-local-database-extension))
@@ -596,10 +595,10 @@ local version (i.e. a different database for each
annotated file"
(defun annotate-timer-print-annotation-function ()
"Print annotation under point in the minibuffer.
-Used by the timer set in `annotate--maybe-make-timer-print-annotation'.
+Used by the timer set in ANNOTATE--MAYBE-MAKE-TIMER-PRINT-ANNOTATION.
-See also the customizable variables: `annotate-echo-annotation-timer' and
-`annotate-print-annotation-under-cursor'."
+See also the customizable variables: ANNOTATE-ECHO-ANNOTATION-TIMER and
+ANNOTATE-PRINT-ANNOTATION-UNDER-CURSOR."
(with-current-buffer (current-buffer)
(when annotate-mode
(when-let* ((annotation (annotate-annotation-at (point))))
@@ -670,23 +669,22 @@ Used when the mode is deactivated."
(1 (annotate--change-guard)))))))
(defun annotate-overlay-filled-p (overlay)
- "Does this `OVERLAY' contains an \"annotation\" property?"
+ "Does this OVERLAY contains an \"annotation\" property?"
(and overlay
(overlayp overlay)
(annotate-annotation-get-annotation-text overlay)))
(defun annotationp (overlay)
- "Is `OVERLAY' an annotation?"
+ "Is OVERLAY an annotation?"
(annotate-overlay-filled-p overlay))
(cl-defmacro annotate-ensure-annotation ((overlay) &body body)
- "Runs `BODY' only if `OVERLAY' is an annotation (i.e. passes annotationp)."
- (declare (indent 1))
+ "Runs BODY only if OVERLAY is an annotation (i.e. passes annotationp)."
`(and (annotationp ,overlay)
(progn ,@body)))
(defun annotate--position-on-annotated-text-p (pos)
- "Does `POS' (as buffer position) corresponds to a character
+ "Does POS (as buffer position) corresponds to a character
that belong to some annotated text?"
(let ((annotation (annotate-annotation-at pos)))
(if annotation
@@ -740,14 +738,14 @@ that belong to some annotated text?"
(defun annotate-delete-chains-in-region (from to)
"Deletes all the chains enclosed in the range specified by
-positions `FROM' and `TO'."
+positions FROM and TO."
(let* ((enclosed-chains (annotate-annotations-chain-in-range from to)))
(dolist (chain enclosed-chains)
(annotate--delete-annotation-chain (cl-first chain)))))
(defun annotate-count-newline-in-region (from to)
"Counts the number of newlines character (?\n) in range
-specified by `FROM' and `TO'."
+specified by FROM and TO."
(cl-count-if (lambda (a) (char-equal a ?\n))
(buffer-substring-no-properties from to)))
@@ -774,10 +772,10 @@ specified by `FROM' and `TO'."
(defun annotate-annotate (&optional color-index)
"Create, modify, or delete annotation.
-if `COLOR-INDEX' is not null must be an index that adresses an element both in
-- `annotate-highlight-faces'
+if COLOR-INDEX is not null must be an index that adresses an element both in
+- ANNOTATE-HIGHLIGHT-FACES
and
-- `annotate-annotation-text-faces'"
+- ANNOTATE-ANNOTATION-TEXT-FACES"
(interactive "P")
(when color-index
(setf color-index (min (max (1- color-index) 0)
@@ -1207,7 +1205,7 @@ between the overlay and the annotation, the \"display\"
property of
the newline is properly disposed of.
The second match will get `ANNOTATE--ANNOTATION-BUILDER' as its
-\"display\" property, which makes the newline look like an
+`display' property, which makes the newline look like an
annotation plus the newline."
(goto-char (next-overlay-change (point)))
(if (>= (point) limit)
@@ -1234,8 +1232,8 @@ annotation plus the newline."
start-word)
(defun annotate-group-by-width (text maximum-width)
- "Groups `TEXT' in a list formed by chunks of maximum size equal
-to `MAXIMUM-WIDTH'."
+ "Groups TEXT in a list formed by chunks of maximum size equal
+to MAXIMUM-WIDTH."
(cl-labels ((next-word (words)
(or (cl-first words)
""))
@@ -1307,8 +1305,8 @@ to `MAXIMUM-WIDTH'."
grouped))))
(cl-defun annotate-safe-subseq (seq from to &optional (value-if-limits-invalid
seq))
- "Return a substring of `SEQ' or `VALUE-IF-LIMITS-INVALID'
-sequence if `FROM' or `TO' are invalids."
+ "Return a substring of SEQ or VALUE-IF-LIMITS-INVALID
+sequence if FROM or TO are invalids."
(cond
((< to from)
value-if-limits-invalid)
@@ -1320,7 +1318,7 @@ sequence if `FROM' or `TO' are invalids."
(cl-subseq seq from to))))
(defun annotate-lineate (text line-width)
- "Breaks `TEXT' into lines to fit in the annotation space with width
`LINE-WIDTH'."
+ "Breaks TEXT into lines to fit in the annotation space with width
LINE-WIDTH."
(cl-labels ((pad (string max-width add-newline-p)
(if (null string)
""
@@ -1358,12 +1356,12 @@ sequence if `FROM' or `TO' are invalids."
(list (pad last-line max-width nil)))))))
(cl-defun annotate--split-lines (text &optional (separator "\n"))
- "Return `TEXT' splitted by `SEPARATOR' (default: \"\n\")."
+ "Return TEXT splitted by SEPARATOR (default: \"\n\")."
(save-match-data
(split-string text separator)))
(defun annotate--join-with-string (strings junction)
- "Join list of string in `STRINGS' using string `JUNCTION'."
+ "Join list of string in STRINGS using string JUNCTION."
(cl-reduce (lambda (a b) (concat a junction b))
strings))
@@ -1372,12 +1370,12 @@ sequence if `FROM' or `TO' are invalids."
end-of-line
annotation-on-is-own-line-p)
"Pads or breaks annotation text (as property of
-`ANNOTATION-OVERLAY' so that all lines have the same width.
+ANNOTATION-OVERLAY so that all lines have the same width.
If annotation is a placed on the margin of a window (that is
-`ANNOTATION-ON-IS-OWN-LINE-P' is
+ANNOTATION-ON-IS-OWN-LINE-P is
nil) the text is broken (regardless of words) to fit on the side
-of the window using `BEGIN-OF-LINE' `END-OF-LINE'.
+of the window using BEGIN-OF-LINE END-OF-LINE.
If annotation is a note that is placed in its own line the text is padded
with spaces so that a \"box\" surround the text without seams, e.g:
@@ -1522,7 +1520,7 @@ a a**"
(defun annotate--remove-annotation-property (_begin end)
"Cleans up annotation properties associated within a region
-surrounded by `BEGIN' and `END'."
+surrounded by _BEGIN and END."
(when (and annotate-mode
(> (buffer-size) 0))
(with-silent-modifications
@@ -1546,7 +1544,7 @@ surrounded by `BEGIN' and `END'."
(defun annotate-annotations-overlay-in-range (from-position to-position)
"Return the annotations overlays that are enclosed in the range
-defined by `FROM-POSITION' and `TO-POSITION'."
+defined by FROM-POSITION and TO-POSITION."
(let ((annotations ())
(counter (max 0 (1- from-position))))
(catch 'scan-loop
@@ -1566,7 +1564,7 @@ defined by `FROM-POSITION' and `TO-POSITION'."
(defun annotate-annotations-chain-in-range (from-position to-position)
"Return the annotations (chains) that are enclosed in the range
-defined by `FROM-POSITION' and `TO-POSITION'."
+defined by FROM-POSITION and TO-POSITION."
(let ((annotations (annotate-annotations-overlay-in-range from-position
to-position))
(chains ()))
(cl-loop for annotation in annotations do
@@ -1575,8 +1573,8 @@ defined by `FROM-POSITION' and `TO-POSITION'."
(reverse chains)))
(defun annotate--change-guard ()
- "Return a `facespec` with an `insert-behind-hooks` property
-that strips dangling `display` properties of text insertions if
+ "Return a `facespec' with an `insert-behind-hooks' property
+that strips dangling `display' properties of text insertions if
text is inserted. This cleans up after newline insertions between
an overlay and it's annotation."
(list 'face
@@ -1585,8 +1583,8 @@ an overlay and it's annotation."
'(annotate--remove-annotation-property)))
(defun annotate-prefix-lines (prefix text &optional omit-trailing-null)
- "Prepend `PREFIX' to each line in `TEXT'.
-If `OMIT-TRAILING-NULL' is non null, empty line at the end of
+ "Prepend PREFIX to each line in TEXT.
+If OMIT-TRAILING-NULL is non null, empty line at the end of
text will be discarded."
(let ((lines (annotate--split-lines text "\n")))
(when omit-trailing-null
@@ -1604,7 +1602,7 @@ buffer is not on info-mode"
(annotate-guess-filename-for-dump Info-current-file nil))
(cl-defun annotate-indirect-buffer-p (&optional (buffer (current-buffer)))
- "Returns non nil if `BUFFER' (default the current buffer) is an indirect
buffer."
+ "Returns non nil if BUFFER (default the current buffer) is an indirect
buffer."
(buffer-base-buffer buffer))
(defun annotate-indirect-buffer-current-p ()
@@ -1624,7 +1622,7 @@ buffer is not on info-mode"
(cl-defun annotate-guess-filename-for-dump (filename
&optional
(return-filename-if-not-found-p t))
- "Guess an acceptable file name suitable for metadata database from
`FILENAME'."
+ "Guess an acceptable file name suitable for metadata database from FILENAME."
(cond
((annotate-string-empty-p filename)
nil)
@@ -1643,7 +1641,7 @@ buffer is not on info-mode"
found))))
(defun annotate-make-annotation-dump-entry (filename file-annotations checksum)
- "Make an annotation record: see `ANNOTATE-LOAD-ANNOTATIONS'."
+ "Make an annotation record: see `annotate-load-annotations'."
(list filename
file-annotations
checksum))
@@ -1695,15 +1693,15 @@ essentially what you get from:
(cl-second annotation))
(defun annotate--interval-left-limit (a)
- "Given an annotation record `A' returns the left limit of the annotated
text."
+ "Given an annotation record A returns the left limit of the annotated text."
(cl-first a))
(defun annotate--interval-right-limit (a)
- "Given an annotation record `A' returns the right limit of the annotated
text."
+ "Given an annotation record A returns the right limit of the annotated text."
(cl-second a))
(defun annotate--make-interval (left-limit right-limit)
- "Make an interval from `LEFT-LIMIT' and `RIGHT-LIMIT'."
+ "Make an interval from LEFT-LIMIT and RIGHT-LIMIT."
(list left-limit right-limit))
(defun annotate-annotation-interval (annotation)
@@ -1730,7 +1728,7 @@ essentially what you get from:
(nth 2 annotation))
(defun annotate-annotated-text (annotation)
- "Get the annotated text of an annotation. The arg `ANNOTATION' must be a
single
+ "Get the annotated text of an annotation. The arg ANNOTATION must be a single
annotation field got from a file dump of all annotated buffers,
essentially what you get from:
\(annotate-annotations-from-dump (nth index (annotate-load-annotations))))."
@@ -1746,7 +1744,7 @@ essentially what you get from:
(cl-defun annotate--dump-indirect-buffer (annotations &optional
(indirect-buffer (current-buffer)))
"Clone an annotated indirect buffer into a new buffer.
-`ANNOTATIONS' containd the annotations and `INDIRECT-BUFFER'
+ANNOTATIONS containd the annotations and INDIRECT-BUFFER
\(default the current buffer) is the buffer to be cloned."
(when annotations
(let* ((new-buffer-name (generate-new-buffer-name (concat (buffer-name
indirect-buffer)
@@ -1929,7 +1927,7 @@ example:
(message annotate-message-annotation-loaded))))))
(defun annotate-db-clean-records (records-db)
- "Remove records from arg `RECORDS-DB' that have empty annotation, example:
+ "Remove records from arg RECORDS-DB that have empty annotation, example:
\\='((\"/foo/bar.dat\" nil \"abababababababababababababab\")
(\"/foo/baz.dat\" ((0 9 \"note\" \"annotated\"))
\"abababababababababababababab\"))
@@ -1950,7 +1948,7 @@ annotation."
(annotate-dump-annotation-data db)))
(defun annotate--expand-record-path (record)
- "Expand file component of `RECORD'."
+ "Expand file component of RECORD."
(let* ((short-filename (annotate-filename-from-dump record))
(annotations (annotate-annotations-from-dump record))
(file-checksum (annotate-checksum-from-dump record))
@@ -1964,7 +1962,7 @@ annotation."
file-checksum)))
(defun annotate--deserialize-database-file (file)
- "Return a sexp from the annotation database contained in `FILE'."
+ "Return a sexp from the annotation database contained in FILE."
(with-temp-buffer
(let* ((annotations-file file)
(attributes (file-attributes annotations-file)))
@@ -1985,7 +1983,7 @@ annotation."
(annotate--deserialize-database-file annotate-file)))
(defun annotate-dump-annotation-data (data &optional save-empty-db)
- "Save `DATA' into annotation file."
+ "Save DATA into annotation file."
(cond
((or save-empty-db
data)
@@ -2030,9 +2028,9 @@ annotation."
record-filename
annotation-beginning
annotation-ending)
- "Remove from database `DB-RECORDS' the annotation identified by
-the triplets `RECORD-FILENAME', `ANNOTATION-BEGINNING' and
- `ANNOTATION-ENDING'; if such annotation does exists."
+ "Remove from database DB-RECORDS the annotation identified by
+the triplets RECORD-FILENAME, ANNOTATION-BEGINNING and
+ ANNOTATION-ENDING; if such annotation does exists."
(with-matching-annotation-fns
(record-filename
annotation-beginning
@@ -2055,9 +2053,9 @@ the triplets `RECORD-FILENAME', `ANNOTATION-BEGINNING' and
annotation-beginning
annotation-ending
replacing-text)
- "Replace the text of annotation from database `DB-RECORDS'
-identified by the triplets `RECORD-FILENAME',
- `ANNOTATION-BEGINNING' and `ANNOTATION-ENDING'; if such
+ "Replace the text of annotation from database DB-RECORDS
+identified by the triplets RECORD-FILENAME,
+ ANNOTATION-BEGINNING and ANNOTATION-ENDING; if such
annotation does exists."
(with-matching-annotation-fns
(record-filename
@@ -2086,7 +2084,7 @@ identified by the triplets `RECORD-FILENAME',
db-records))))
(defun annotate-db-annotations-starts-before-p (a b)
- "Non nil if annotation `A' starts before `B'.
+ "Non nil if annotation A starts before B.
In this context annotation means annotation loaded from local
database not the annotation shown in the buffer (therefore these
@@ -2111,13 +2109,13 @@ functions)."
(delete-overlay ov))))
(defun annotate-string-empty-p (a)
- "Is the arg `A' an empty string or null?"
+ "Is the arg A an empty string or null?"
(or (null a)
(string= "" a)))
(defun annotate-annotation-prop-get (annotation property)
- "Get property `PROPERTY' from annotation `ANNOTATION'. If
-`ANNOTATION' does not pass `annotationp' returns nil."
+ "Get property PROPERTY from annotation ANNOTATION. If
+ANNOTATION does not pass `annotationp' returns nil."
(annotate-ensure-annotation (annotation)
(overlay-get annotation property)))
@@ -2132,13 +2130,13 @@ in a chain of annotations."
(overlay-put annotation annotate-prop-chain-position pos))
(defun annotate-chain-last-p (annotation)
- "Non nil if `ANNOTATION' is the last element of a chain of annotations."
+ "Non nil if ANNOTATION is the last element of a chain of annotations."
(let ((value (annotate-annotation-get-chain-position annotation)))
(and value
(cl-equalp value annotate-prop-chain-pos-marker-last))))
(defun annotate-chain-first-p (annotation)
- "Non nil if `ANNOTATION' is the first element, or the only
+ "Non nil if ANNOTATION is the first element, or the only
of a chain of annotations."
(let* ((chain-pos (annotate-annotation-get-chain-position
annotation))
(annotation-start (overlay-start annotation))
@@ -2153,7 +2151,7 @@ of a chain of annotations."
annotate-prop-chain-pos-marker-last))))))
(defun annotate-chain-first (annotation)
- "Find first element of the chain where `ANNOTATION' belongs."
+ "Find first element of the chain where ANNOTATION belongs."
(cond
((null annotation)
nil)
@@ -2165,7 +2163,7 @@ of a chain of annotations."
(annotate-chain-first previous-annotation)))))
(defun annotate-chain-last (annotation)
- "Find last element of the chain where `ANNOTATION' belongs."
+ "Find last element of the chain where ANNOTATION belongs."
(cond
((null annotation)
nil)
@@ -2177,19 +2175,19 @@ of a chain of annotations."
(annotate-chain-last next-annotation)))))
(defun annotate-chain-first-at (pos)
- "Find first element of the chain of annotation that overlap point `POS'."
+ "Find first element of the chain of annotation that overlap point POS."
(let ((annotation (annotate-annotation-at pos)))
(annotate-ensure-annotation (annotation)
(annotate-chain-first annotation))))
(defun annotate-chain-last-at (pos)
- "Find last element of the chain of annotation that overlap point `POS'."
+ "Find last element of the chain of annotation that overlap point POS."
(let ((annotation (annotate-annotation-at pos)))
(annotate-ensure-annotation (annotation)
(annotate-chain-last annotation))))
(defun annotate-chain-at (pos)
- "Find the chain of overlays where point `POS' belongs."
+ "Find the chain of overlays where point POS belongs."
(let ((annotation (annotate-annotation-at pos)))
(annotate-ensure-annotation (annotation)
(annotate-find-chain annotation))))
@@ -2205,7 +2203,7 @@ in a chain of annotations as last."
(annotate-annotation-chain-position annotation
annotate-prop-chain-pos-marker-last))
(defun annotate-find-chain (annotation)
- "Find all ANNOTATION that are parts of the chain where `ANNOTATION' belongs."
+ "Find all ANNOTATION that are parts of the chain where ANNOTATION belongs."
(annotate-ensure-annotation (annotation)
(cl-labels ((find-next-annotation (pos)
(annotate-annotation-at (next-overlay-change pos))))
@@ -2229,41 +2227,41 @@ in a chain of annotations as last."
(reverse results))))))
(defun annotate-annotations-chain-at (pos)
- "Find all annotation that are parts of the chain that overlaps at `POS'."
+ "Find all annotation that are parts of the chain that overlaps at POS."
(annotate-find-chain (annotate-annotation-at pos)))
(defun annotate-chain-hide-text (chain)
- "Sets an overlay properties of the last ring of `CHAIN' so that
+ "Sets an overlay properties of the last ring of CHAIN so that
the annotation's text will not be rendered."
(let ((last-ring (annotate-chain-last-ring chain)))
(overlay-put last-ring 'hide-text t)))
(defun annotate-chain-show-text (chain)
- "Sets an overlay properties of the last ring of `CHAIN' so that
+ "Sets an overlay properties of the last ring of CHAIN so that
the annotation's text will be rendered."
(let ((last-ring (annotate-chain-last-ring chain)))
(overlay-put last-ring 'hide-text nil)))
(defun annotate-chain-hide-text-p (chain)
- "Non nil if the annotation's text contained in the last ring of `CHAIN'
+ "Non nil if the annotation's text contained in the last ring of CHAIN
must not be rendered."
(let ((last-ring (annotate-chain-last (cl-first chain))))
(annotate-tail-overlay-hide-text-p last-ring)))
(defun annotate-tail-overlay-hide-text-p (overlay)
- "Get the property for hiding the annotation text from `OVERLAY'."
+ "Get the property for hiding the annotation text from OVERLAY."
(overlay-get overlay 'hide-text))
(defun annotate-create-annotation (start end annotation-text annotated-text
&optional color-index position)
- "Create a new annotation for selected region (from `START' to `END'.
+ "Create a new annotation for selected region (from START to END.
-Here the argument `ANNOTATION-TEXT' is the string that appears
+Here the argument ANNOTATION-TEXT is the string that appears
on the margin of the window and \"annotated-text\" is the string
that is underlined.
If this function is called from procedure
-\"annotate-load-annotations\" the argument `ANNOTATED-TEXT'
+\"annotate-load-annotations\" the argument ANNOTATED-TEXT
should be not null. In this case we know that an annotation
existed in a text interval defined in the database
metadata (the database located in the file specified by the
@@ -2279,11 +2277,11 @@ interval and, if found, the buffer is annotated right
there.
The searched interval can be customized setting the variable:
\"annotate-search-region-lines-delta\".
-`COLOR-INDEX`, if non-null (default nil), is used as index to address
+COLOR-INDEX, if non-null (default nil), is used as index to address
elements both in `annotate-color-index-from-dump'
and `annotate-color-index-from-dump' to specify annotation appearance.
-Finally `POSITION` indicates the positioning policy for the annotation,
+Finally POSITION indicates the positioning policy for the annotation,
if null the value bound to `annotate-annotation-position-policy' is
used."
(cl-labels ((face-annotation-shifting-point (position
shifting-direction-function)
@@ -2461,23 +2459,23 @@ used."
(font-lock-fontify-block 1))))))
(defun annotate-overlay-put-echo-help (overlay text)
- "Set the property `HELP-ECHO' to `TEXT' in overlay `OVERLAY'."
+ "Set the property `HELP-ECHO' to TEXT in overlay OVERLAY."
(overlay-put overlay 'help-echo text))
(defun annotate-overlay-get-echo-help (overlay)
- "Set the property `HELP-ECHO' from overlay `OVERLAY'."
+ "Set the property `HELP-ECHO' from overlay OVERLAY."
(overlay-get overlay 'help-echo))
(defun annotate-overlay-maybe-set-help-echo (overlay annotation-text)
- "Set the property `HELP-ECHO' to `TEXT' in overlay `OVERLAY' if
+ "Set the property `HELP-ECHO' to ANNOTATION-TEXT in overlay OVERLAY if
the annotations should be shown in a popup fashion.
-See the variable: `ANNOTATE-USE-ECHO-AREA'."
+See the variable: ANNOTATE-USE-ECHO-AREA."
(when annotate-use-echo-area
(annotate-overlay-put-echo-help overlay annotation-text)))
(defun annotate--delete-annotation-chain (annotation)
- "Delete `ANNOTATION' from a buffer and the chain it belongs to.
+ "Delete ANNOTATION from a buffer and the chain it belongs to.
This function is not part of the public API."
(annotate-ensure-annotation (annotation)
@@ -2493,7 +2491,7 @@ This function is not part of the public API."
(delete-overlay single-element)))))))
(defun annotate--delete-annotation-chain-ring (annotation-ring)
- "Delete overlay of `ANNOTATION-RING' from a buffer.
+ "Delete overlay of ANNOTATION-RING from a buffer.
A ring is a single element of an annotation chain.
@@ -2508,7 +2506,7 @@ This function is not part of the public API."
(defun annotate-delete-chain-element (annotation)
"Delete a ring (a ring is a single element of an ANNOTATION chain.)
-from a chain where `ANNOTATION' belong."
+from a chain where ANNOTATION belong."
(annotate-ensure-annotation (annotation)
(let* ((chain (annotate-find-chain annotation))
(first-of-chain-p (annotate-chain-first-p annotation))
@@ -2526,7 +2524,7 @@ from a chain where `ANNOTATION' belong."
(annotate-annotation-set-chain-last annotation-before))))))))
(defun annotate--cut-left-annotation (annotation)
- "Trims `ANNOTATION' exactly one character from the start."
+ "Trims ANNOTATION exactly one character from the start."
(annotate-ensure-annotation (annotation)
(let* ((chain (annotate-find-chain annotation))
(first-annotation (annotate-chain-first annotation))
@@ -2544,7 +2542,7 @@ from a chain where `ANNOTATION' belong."
(move-overlay first-annotation new-starting-pos
first-annotation-ending-pos))))))
(defun annotate--cut-right-annotation (annotation &optional refontify-buffer)
- "Trims `ANNOTATION' exactly one character from the end."
+ "Trims ANNOTATION exactly one character from the end."
(annotate-ensure-annotation (annotation)
(let* ((chain (annotate-find-chain annotation))
(last-annotation (annotate-chain-last annotation))
@@ -2579,7 +2577,7 @@ This function is not part of the public API."
(y-or-n-p annotate-confirm-deleting-annotation-prompt)))
(cl-defun annotate-delete-annotation (&optional (point (point)))
- "Command to delete an annotation, `POINT' is the buffer
+ "Command to delete an annotation, POINT is the buffer
position where to look for annotation (default the cursor
point)."
(interactive)
@@ -2597,7 +2595,7 @@ This function is not part of the public API."
(y-or-n-p (format annotate-confirm-appending-newline-prompt (buffer-name))))
(defun annotate-change-annotation (pos)
- "Change annotation at `POS'. If empty, delete annotation."
+ "Change annotation at POS. If empty, delete annotation."
(let* ((highlight (annotate-annotation-at pos))
(annotation-text (read-from-minibuffer annotate-annotation-prompt
(annotate-annotation-get-annotation-text highlight))))
@@ -2632,7 +2630,7 @@ This function is not part of the public API."
(defun annotate-annotation-at (pos)
"Return the annotations (overlay where (annotationp overlay) -> t)
-at positions `POS' or nil if no annotations exists at pos.
+at positions POS or nil if no annotations exists at pos.
NOTE this assumes that annotations never overlaps so the list of
all annotations can contains only one element maximum."
@@ -2641,7 +2639,7 @@ all annotations can contains only one element maximum."
(cl-first all)))
(defun annotate-previous-annotation-ends (pos)
- "Return the previous annotation that ends before `POS' or nil if no
annotation
+ "Return the previous annotation that ends before POS or nil if no annotation
was found.
NOTE this assumes that annotations never overlaps."
(cl-labels ((previous-annotation-ends (start)
@@ -2658,12 +2656,12 @@ NOTE this assumes that annotations never overlaps."
(previous-annotation-ends pos)))))
(defun annotate-previous-annotation (annotation)
- "Return the annotation before `ANNOTATIONS' or nil if no such
+ "Return the annotation before ANNOTATIONS or nil if no such
annotation exists."
(annotate-previous-annotation-ends (overlay-start (annotate-chain-first
annotation))))
(defun annotate-next-annotation-starts (pos)
- "Return the next annotation that starts after `POS' or nil if no annotation
+ "Return the next annotation that starts after POS or nil if no annotation
was found.
NOTE this assumes that annotations never overlaps."
(cl-labels ((next-annotation-ends (start)
@@ -2680,7 +2678,7 @@ NOTE this assumes that annotations never overlaps."
(next-annotation-ends pos)))))
(defun annotate-next-annotation (annotation)
- "Return the annotation after `ANNOTATIONS' or nil if no such
+ "Return the annotation after ANNOTATIONS or nil if no such
annotation exists."
(annotate-next-annotation-starts (overlay-end (annotate-chain-last
annotation))))
@@ -2741,8 +2739,8 @@ the point. This is needed as `THING-AT-POINT' family of
(defun annotate-make-annotation (beginning ending annotation annotated-text)
"Make an annotation record that represent an annotation
-starting at `BEGINNING', terminate at `ENDING' with annotation
-content `ANNOTATION' and annotated text `ANNOTATED-TEXT'."
+starting at BEGINNING, terminate at ENDING with annotation
+content ANNOTATION and annotated text ANNOTATED-TEXT."
(list beginning ending annotation annotated-text))
(defun annotate-all-annotations ()
@@ -2779,12 +2777,12 @@ The format is suitable for database dump."
all-annotations))))
(defun annotate-info-root-dir-p (filename)
- "Is the name of this file (`FILENAME') equals to the info root node?"
+ "Is the name of this file (FILENAME) equals to the info root node?"
(string= filename
annotate-info-root-name))
(defun annotate-guess-file-format (filename)
- "Try to guess the file format from `FILENAME'.
+ "Try to guess the file format from FILENAME.
Non nil if the file format is supported from \"annotate\" in a more
sophisticated way than plain text."
(cl-labels ((file-contents ()
@@ -2872,7 +2870,7 @@ Compatibility wrapper for the function `info-setup' and
`info-pop-to-buffer'."
(goto-char (button-get button 'go-to))))))))
(defun annotate-update-visited-buffer-maybe (filename)
- "Reload annotation mode in the buffer visiting `FILENAME', if such buffer
exists."
+ "Reload annotation mode in the buffer visiting FILENAME, if such buffer
exists."
(let ((visited-buffer (find-buffer-visiting filename)))
(when visited-buffer ;; a buffer is visiting the file
(with-current-buffer visited-buffer
@@ -2922,11 +2920,11 @@ pressed."
(annotate-show-annotation-summary query nil nil)))))
(cl-defun annotate-wrap-text (text &optional (wrapper "\""))
- "Wrap string `TEXT' with string `WRAPPER'."
+ "Wrap string TEXT with string WRAPPER."
(concat wrapper text wrapper))
(cl-defun annotate-unwrap-text (text &optional (wrapper "\"") (left-side t))
- "Remove `WRAPPER' at both ends from `TEXT'."
+ "Remove WRAPPER at both ends from TEXT."
(let ((results text)
(wrapper-length (length wrapper)))
(when (>= (length text)
@@ -2947,7 +2945,7 @@ pressed."
(cl-defun annotate-show-annotation-summary (&optional arg-query
cut-above-point (save-annotations t))
"Show a summary of all the annotations in a temp buffer, the
results can be filtered with a simple query language: see
-`ANNOTATE-SUMMARY-FILTER-DB'."
+ANNOTATE-SUMMARY-FILTER-DB."
(interactive)
(cl-labels ((ellipsize (text prefix-string)
(let* ((prefix-length (string-width prefix-string))
@@ -3121,7 +3119,7 @@ results can be filtered with a simple query language: see
summary window is shown.")
(defvar annotate-summary-query-current-token nil
- "Holds the next token of the query in `ANNOTATE-SUMMARY-QUERY'.")
+ "Holds the next token of the query in ANNOTATE-SUMMARY-QUERY.")
(defun annotate-summary-query-lexer-symbol (res)
"The symbol identifying the token (e.g. \\='and)."
@@ -3133,20 +3131,20 @@ summary window is shown.")
(defun annotate-summary-query-lexer-start (res)
"The starting point of the substring of
-`annotate-summary-query' for this token."
+ANNOTATE-SUMMARY-QUERY for this token."
(elt res 2))
(defun annotate-summary-query-lexer-end (res)
"The ending point of the substring of
-`annotate-summary-query' for this token."
+ANNOTATE-SUMMARY-QUERY for this token."
(elt res 3))
(cl-defun annotate-summary-lexer (&optional (look-ahead-p nil))
- "The lexer for `annotate-summary-query'.
+ "The lexer for ANNOTATE-SUMMARY-QUERY.
This function, when called, will produce the next token from
-`annotate-summary-query'; a token is a substring with a well
+ANNOTATE-SUMMARY-QUERY; a token is a substring with a well
defined meaning according to our grammar.
For example this string:
@@ -3175,9 +3173,9 @@ The format is a proper list where:
- third and fourth element (currently unused)
the substring limits for this token (as returned by
- `match-beginning' and `match-end'.
+ MATCH-BEGINNING and MATCH-END.
-Note that spaces are ignored and all the tokens except `re' must
+Note that spaces are ignored and all the tokens except 're' must
not be prefixed with a backslash to match. So, for example not ->
will match the token type \\='not but \not will match the token \\='re;
this way we can \"protect\" a regexp that contains reserved
@@ -3186,14 +3184,14 @@ keyword (aka escaping).
The special value :no-more-token is returned after the whole
input is processed.
-Calling this function with value of LOOK-AHEAD-P nil will `CONSUME' the
-token from `annotate-summary-query' (i.e. that string is modified).
+Calling this function with value of LOOK-AHEAD-P nil will consume the
+token from ANNOTATE-SUMMARY-QUERY (i.e. that string is modified).
example:
\"a and b\" -> \"and b\", \\='(re \"a\" 0 1)
when LOOK-AHEAD-P is not nil the token is recognized but not cut away
-from `annotate-summary-query'.
+from ANNOTATE-SUMMARY-QUERY.
example:
\"a and b\" -> \"a and b\", \\='(re \"a\" 0 1)"
@@ -3240,12 +3238,12 @@ example:
res)))))
(defun annotate-summary-query-parse-end-input-p (token)
- "Non nil if there are no more tokens in `ANNOTATE-SUMMARY-QUERY'."
+ "Non nil if there are no more tokens in ANNOTATE-SUMMARY-QUERY."
(eq token :no-more-tokens))
(defun annotate-summary-token-symbol-match (looking-symbol token)
- "Return non nil if `LOOKING-SYMBOL' is \"eq\" to the symbol
-component of `TOKEN'."
+ "Return non nil if LOOKING-SYMBOL is \"eq\" to the symbol
+component of TOKEN."
(eq looking-symbol
(annotate-summary-query-lexer-symbol token)))
@@ -3276,8 +3274,8 @@ Arguments:
- filter-fn is a function that accept two parameters: the regular
expression to match (a token of type \\='re, see the lexer
- `ANNOTATE-SUMMARY-LEXER' and a single annotation record (see
- `ANNOTATE-LOAD-ANNOTATIONS').
+ ANNOTATE-SUMMARY-LEXER and a single annotation record (see
+ ANNOTATE-LOAD-ANNOTATIONS).
This function will reject (its value is nil) records that do
not match the annotation.
@@ -3403,7 +3401,7 @@ Arguments:
(operator filter-fn annotation matchp)))))
;; if we are here the lexer can not find any more tokens in the query
;; just return the value of res
- res)))) ; end of `(if (not (annotate-summary-query-parse-end-input-p
look-ahead))'
+ res)))) ; end of '(if (not (annotate-summary-query-parse-end-input-p
look-ahead))'
(defun annotate-summary-query-parse-expression ()
"Parse rule for expression:
@@ -3434,7 +3432,7 @@ NOT := \"not\"
DELIMITER := \" ; ASCII 34 (dec) 22 (hex)
Note: this function returns the annotation part of the record, see
-`ANNOTATE-LOAD-ANNOTATIONS'."
+ANNOTATE-LOAD-ANNOTATIONS."
(lambda (annotation query file-filter-fn note-filter-fn)
(let ((annotate-summary-query query) ; save the query
(query-notes-only nil)) ; the query for just the notes
@@ -3525,7 +3523,7 @@ Note: this function returns the annotation part of the
record, see
(defun annotate-summary-filter-db (annotations-dump query
remove-annotations-cutoff-point)
"Filter an annotation database with a query.
-The argument `QUERY' is a string that respect a simple syntax:
+The argument QUERY is a string that respect a simple syntax:
- [file-mask] [(and | or) [not] regex-note [(and | or) [not] regexp-note ...]]
@@ -3632,11 +3630,11 @@ annotate minor mode active."
refresh all the annotations contained in each buffer where
annotate minor mode is active.
-if `DATABASE-FILE-PATH' is nil (the default) a prompt asking for
+if DATABASE-FILE-PATH is nil (the default) a prompt asking for
a file containing database is presented to the user, otherwise
the value of this argument is used.
-If `FORCE-LOAD' is non nil no prompt asking user for confirmation
+If FORCE-LOAD is non nil no prompt asking user for confirmation
about loading the new file is shown.
Note: this function will attempt to load (compile and
@@ -3667,9 +3665,9 @@ code, always use load files from trusted sources!"
;;; merging database
(defun annotate--merge-interval (a b)
- "Merge two annotation interval `A' and `B'.
+ "Merge two annotation interval A and B.
-The new interval is expanded so that includes `A' and `B'."
+The new interval is expanded so that includes A and B."
(let ((new-left-limit (min (annotate--interval-left-limit a)
(annotate--interval-left-limit b)))
(new-right-limit (max (annotate--interval-right-limit a)
@@ -3678,7 +3676,7 @@ The new interval is expanded so that includes `A' and
`B'."
new-right-limit)))
(defun annotate--db-annotations-overlaps-p (annotation-a annotation-b)
- "Return non nil if `ANNOTATION-A' and `ANNOTATION-B' overlaps."
+ "Return non nil if ANNOTATION-A and ANNOTATION-B overlaps."
(let ((interval-a (annotate-annotation-interval annotation-a))
(interval-b (annotate-annotation-interval annotation-b)))
(not (or (< (annotate--interval-right-limit interval-b)
@@ -3688,7 +3686,7 @@ The new interval is expanded so that includes `A' and
`B'."
(defun annotate--db-merge-annotations (host guest)
"Merge annotation GUEST into annotation HOST.
-Uses `annotate--merge-interval'."
+Uses ANNOTATE--MERGE-INTERVAL."
(when (annotate--db-annotations-overlaps-p host guest)
(let* ((interval-host (annotate-annotation-interval host))
(interval-guest (annotate-annotation-interval guest))
@@ -3703,8 +3701,8 @@ Uses `annotate--merge-interval'."
(annotate-make-annotation left right new-annotation-text
new-annotated-text))))
(defun annotate--db-remove-overlap-annotations (annotations &optional accum)
- "Recursively merges overlapping annotations in `ANNOTATIONS'
-using `ANNOTATE--DB-MERGE-ANNOTATIONS'."
+ "Recursively merges overlapping annotations in ANNOTATIONS
+using ANNOTATE--DB-MERGE-ANNOTATIONS."
(if (= (length annotations) 1)
(push (cl-first annotations) accum)
(let* ((probe (cl-first annotations))
@@ -3725,7 +3723,7 @@ using `ANNOTATE--DB-MERGE-ANNOTATIONS'."
(annotate--db-remove-overlap-annotations rest-annotations (push probe
accum))))))
(defun annotate--db-merge-databases (db-1 db-2 &optional accum)
- "Recursively merge database `DB-1' and `DB-2'."
+ "Recursively merge database DB-1 and DB-2."
(cl-labels ((find-same-file-record (record annotations-db)
(let ((record-filename (annotate-filename-from-dump record)))
(cl-find-if (lambda (a)
