[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-27 d7f4cc0 2/2: ERC: Track: Clarify documentation on tracked buffe
From: |
Amin Bandali |
Subject: |
emacs-27 d7f4cc0 2/2: ERC: Track: Clarify documentation on tracked buffers and add references |
Date: |
Sat, 11 Sep 2021 22:57:57 -0400 (EDT) |
branch: emacs-27
commit d7f4cc0974645cc6a295740afe85c6e21d956119
Author: Olivier Certner <olce.emacs@certner.fr>
Commit: Amin Bandali <bandali@gnu.org>
ERC: Track: Clarify documentation on tracked buffers and add references
* lisp/erc/erc-track.el (erc-modified-channels-alist): Clarify what
the list contains. Add references to variables and functions involved
in displaying tracked buffers from this list.
(erc-make-mode-line-buffer-name): Describe exactly the algorithm, and
reference custom variables that influence it.
---
lisp/erc/erc-track.el | 27 +++++++++++++++++++--------
1 file changed, 19 insertions(+), 8 deletions(-)
diff --git a/lisp/erc/erc-track.el b/lisp/erc/erc-track.el
index b6055b6..66fde69 100644
--- a/lisp/erc/erc-track.el
+++ b/lisp/erc/erc-track.el
@@ -284,14 +284,19 @@ nil - don't add to mode line."
Each element is a list of the form (BUFFER COUNT . FACE) where
BUFFER is a buffer object of the channel the entry corresponds
to, COUNT is a number indicating how often activity was noticed,
-and FACE is a face (or a list of faces) to use when displaying the
-buffer's name.
+and FACE is a face (or a list of faces, combined as usual) to use
+when displaying the buffer's name in the mode line.
-Entries in this list should only happen for buffers where activity occurred
-while the buffer was not visible.
+Entries in this list are only added/updated for buffers that were
+not visible when activity occurred in them, and are removed for
+each buffer as soon as it becomes visible again (or if the server
+is disconnected, provided `erc-track-remove-disconnected-buffers'
+is true).
-See also `erc-track-faces-priority-list',
-`erc-track-faces-normal-list' and `erc-track-showcount'.")
+For how the face is chosen for a buffer, see
+`erc-track-find-face' and `erc-track-priority-faces-only'. For
+how buffers are then displayed in the mode line, see
+`erc-modified-channels-display'.")
(defcustom erc-track-showcount nil
"If non-nil, count of unseen messages will be shown for each channel."
@@ -656,8 +661,14 @@ ARGS are ignored."
"The face to use when mouse is over channel names in the mode line.")
(defun erc-make-mode-line-buffer-name (string buffer &optional faces count)
- "Return STRING as a button that switches to BUFFER when clicked.
-If FACES are provided, color STRING with them."
+ "Returns a button that switches to BUFFER when clicked.
+STRING is the string in the button. It is possibly suffixed with
+the number of unread messages, according to variables
+`erc-track-showcount' and `erc-track-showcount-string'.
+
+If `erc-track-use-faces' is true and FACES are provided, format
+STRING with them. When the mouse hovers above the button, STRING
+is displayed according to `erc-track-mouse-face'."
;; We define a new sparse keymap every time, because 1. this data
;; structure is very small, the alternative would require us to
;; defvar a keymap, 2. the user is not interested in customizing it