]> git.eshelyaron.com Git - emacs.git/commitdiff
; Improve erc-format-privmessage documentation
authorF. Jason Park <jp@neverwas.me>
Sat, 8 Jun 2024 00:08:08 +0000 (17:08 -0700)
committerEshel Yaron <me@eshelyaron.com>
Sun, 9 Jun 2024 05:31:11 +0000 (07:31 +0200)
* etc/ERC-NEWS: Mention that `erc-format-privmessage' has been removed
from the default client's primary code path.  Revise various headlines.
* lisp/erc/erc.el: Bump Compat version to 29.1.4.5.
(erc-format-privmessage): Make appeal for users to contact the mailing
list if they need to modify speaker-message formatting.

(cherry picked from commit c69c822c59f315512ac9a921289761907178e337)

etc/ERC-NEWS
lisp/erc/erc.el

index 1fad62e1999beee8469ea68545942aed5d024865..c541b3e4289e62d291cc5940b52cfa974f803b92 100644 (file)
@@ -100,7 +100,7 @@ one's optionally accessible from the keyboard, just like any other
 side window.  Hit '<RET>' over a nick to spawn a "/QUERY" or a
 "Lastlog" (Occur) session.  See 'erc-nickbar-mode' for more.
 
-** New module to keep tabs on query pals who aren't in your channels.
+** New 'querypoll' module for tracking non-channel query participants.
 ERC has gotten a bit pickier about managing participants in query
 buffers.  "Untracked" correspondents no longer appear automatically in
 membership tables, even if you respond or initiate contact.  Instead,
@@ -112,7 +112,7 @@ Those familiar with the IRCv3 Monitor extension can think of this as
 "fallback code" and a temporary placeholder for the real thing.
 Add 'querypoll' (and 'nickbar') to 'erc-modules' to try it out.
 
-** Option 'erc-timestamp-use-align-to' more versatile.
+** Option 'erc-timestamp-use-align-to' made more versatile.
 While this option has always offered to right-align stamps via the
 'display' text property, it's now more effective at doing so when set
 to a number indicating an offset from the right edge.  Users of the
@@ -143,7 +143,7 @@ connectivity before attempting to reconnect in earnest.  See option
 'erc-server-reconnect-function' and new local module 'services-regain'
 (also experimental) to get started.
 
-** Modules rather than their libraries set major-mode keybindings.
+** Module-based keybinding adjustments for major modes.
 To put it another way, simply loading a built-in module's library no
 longer modifies 'erc-mode-map'.  Instead, modifications occur during
 module setup.  This should not impact most user configs since ERC
@@ -162,7 +162,7 @@ asking users who've customized this option to switch to
 that some other solution, like automatic migration, is justified,
 please make that known on the bug list.
 
-** Module 'noncommands' deprecated, replaced by 'command-indicator'.
+** Module 'command-indicator' revives echoing, replacing 'noncommands'.
 Command-line echoing has returned to ERC after a near decade-long
 hiatus.  This means you can elect to have ERC leave a trail of (most)
 slash-command input submitted at the prompt, in a manner resembling
@@ -202,13 +202,14 @@ s-expressions, which ERC will continue to honor.  Although the default
 lineup remains functionally equivalent, its members have all been
 updated accordingly.
 
-** 'erc-track-faces-priority-list' and 'erc-track-faces-normal-list' slimmed.
-These options have been purged of certain 'button'-related face
-combinations.  Originally added in ERC 5.3, these combinations
-described the effect of "buttonizing" atop faces added by the 'match'
-module, like '(erc-nick-default-face erc-pal-face)'.  However, since
-at least Emacs 27, 'match' has run before 'button' in
-'erc-insert-modify-hook', meaning such permutations aren't possible.
+** A slimmed down 'erc-track-faces-priority-list'.
+This option, along with 'erc-track-faces-normal-list', has been purged
+of certain 'button'-related face combinations.  Originally added in
+ERC 5.3, these combinations described the effect of "buttonizing" atop
+faces added by the 'match' module, like '(erc-nick-default-face
+erc-pal-face)'.  However, since at least Emacs 27, 'match' has run
+before 'button' in 'erc-insert-modify-hook', meaning such permutations
+aren't possible.
 
 More importantly, users who've customized either of these options
 should update them with the new default value of the option
@@ -244,15 +245,14 @@ wherever it happens to reside instead of forcing it to the bottom of a
 window, meaning new input appears above the prompt, scrolling existing
 messages upward to compensate.
 
-** Subtle changes in two fundamental faces.
+** Subtle changes for two fundamental faces.
 Users of the default theme may notice that 'erc-action-face' and
-'erc-notice-face' now appear slightly less bold on systems supporting
-a weight of 'semi-bold'.  This was done to make buttons detectable and
-to spare users from resorting to tweaking these faces, or options like
-'erc-notice-highlight-type', just to achieve this effect.  It's
-currently most prominent in "/ME" messages, where 'erc-action-face'
-sits beneath 'erc-input-face', as well as 'erc-my-nick-face' in the
-speaker portion.
+'erc-notice-face' now appear slightly less bold.  This improves button
+detection and spares users from having to tweak faces (or options,
+like 'erc-notice-highlight-type') just to achieve this effect.  The
+change is currently most noticeable in "/ME" messages, where
+'erc-action-face' appears beneath 'erc-input-face' and
+'erc-my-nick-face'.
 
 ** Fewer nick buttons in QUIT, JOIN, and PART messages.
 Common messages that show a nickname followed by a "userhost" often
@@ -392,7 +392,7 @@ from 't' to the more useful 'erc-prompt', although the property of the
 same name has been retained and now has a value of 'hidden' when
 disconnected.
 
-*** Lists of faces in buttonized text are no longer nested.
+*** Flattened face lists for buttonized text.
 Previously, when "buttonizing" a new region, ERC would combine faces
 by blindly consing the new onto the existing.  In theory, this kept a
 nice record of all modifications to a given region.  However, it also
@@ -691,7 +691,7 @@ that the killing of buffers done on behalf of the option
 'erc-kill-buffer-on-part' has been made more detectable by the flag
 'erc-killing-buffer-on-part-p'.
 
-*** Channel-mode handling has become stricter and more predictable.
+*** Stricter and more predictable channel-mode handling.
 ERC has always processed channel modes using "standardized" letters
 and popular status prefixes.  Starting with this release, ERC will
 begin preferring advertised "CHANMODES" when interpreting letters and
@@ -733,6 +733,13 @@ separate "speaker catalog" keyed by contextual symbols, like
 'query-privmsg', ERC (and eventually everyone) will more easily be
 able to influence how inserted messages take shape in buffers.
 
+As a consequence of this transition, the default client no longer
+calls `erc-format-privmessage' to format speaker messages.  See that
+function's doc string for help adapting to the new system, but please
+keep in mind that discussions are still ongoing regarding its eventual
+public interface.  As usual, anyone interested should get involved by
+writing to the mailing list.
+
 *** New format templates for inserted CTCP ACTION messages.
 In 5.5 and earlier, ERC displayed outgoing CTCP ACTION messages in
 'erc-input-face' alone (before buttonizing).  Incoming ACTION messages
@@ -747,7 +754,7 @@ default "language catalog" in favor of an entry from the new internal
 by toggling a provided compatibility switch.  See source code around
 the function 'erc-send-action' for details.
 
-*** Miscellaneous changes
+*** Miscellaneous changes.
 In 'erc-button-alist', 'Info-goto-node' has been supplanted by plain
 old 'info', and the "<URL:...>" entry has been removed because it was
 more or less redundant.  In all ERC buffers, the "<TAB>" key is now
index 3f43c3344929959a647650da49271b847dcdfaba..3ccbcd696c5719f4e77fd504a1913512b78be997 100644 (file)
@@ -13,7 +13,7 @@
 ;;               Michael Olson (mwolson@gnu.org)
 ;;               Kelvin White (kwhite@gnu.org)
 ;; Version: 5.6-git
-;; Package-Requires: ((emacs "27.1") (compat "29.1.4.4"))
+;; Package-Requires: ((emacs "27.1") (compat "29.1.4.5"))
 ;; Keywords: IRC, chat, client, Internet
 ;; URL: https://www.gnu.org/software/emacs/erc.html
 
@@ -6186,7 +6186,15 @@ NUH, and the current `erc-response' object.")
   (and erc-channel-users (gethash downcased erc-channel-users)))
 
 (defun erc-format-privmessage (nick msg privp msgp)
-  "Format a PRIVMSG in an insertable fashion."
+  "Format a PRIVMSG in an insertable fashion.
+
+Note that as of version 5.6, the default client no longer calls this
+function.  It instead defers to the `format-spec'-based message-catalog
+system to handle all message formatting.  Anyone needing to influence
+such formatting should describe their use case via \\[erc-bug] or
+similar.  Please do this instead of resorting to things like modifying
+formatting templates to remove speaker brackets (because many modules
+rely on their presence, and cleaner ways exist)."
   (let* ((mark-s (if msgp (if privp "*" "<") "-"))
          (mark-e (if msgp (if privp "*" ">") "-"))
          (str    (format "%s%s%s %s" mark-s nick mark-e msg))
@@ -9680,7 +9688,7 @@ See also `format-spec'."
     erc-networks-shrink-ids-and-buffer-names
     erc-networks-rename-surviving-target-buffer)
   "Invoked whenever a channel-buffer is killed via `kill-buffer'."
-  :package-version '(ERC . "5.6") ; FIXME sync on release
+  :package-version '(ERC . "5.6")
   :group 'erc-hooks
   :type 'hook)