master 8af96d831ff 1/2: ; Address some ambiguities in ERC's documentation

[F. Jason Park]

branch: master
commit 8af96d831ffd7144a28145ed024418143fde857b
Author: F. Jason Park <jp@neverwas.me>
Commit: F. Jason Park <jp@neverwas.me>

    ; Address some ambiguities in ERC's documentation
    
    * doc/misc/erc.texi: Change name of example function from
    `erc-my-enable-read-indicator-on-join' to
    `erc-my-enable-keep-place-indicator-on-join'.  Fix example functions
    `erc-cmd-TRACK' and `erc-cmd-UNTRACK' to work with server buffers as
    well as target buffers.
    * etc/ERC-NEWS: Revise `keep-place' entry and make headlines less
    redundant.
    * lisp/erc/erc.el (erc-accidental-paste-threshold-seconds): Fix
    portion of existing wording that was more likely interpreted as a
    single multiline submission, whereas the intended meaning is three
    separate submissions.
---
 doc/misc/erc.texi | 27 ++++++++++++++++-----------
 etc/ERC-NEWS      | 23 ++++++++++++-----------
 lisp/erc/erc.el   |  4 +++-
 3 files changed, 31 insertions(+), 23 deletions(-)

diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index 63ea94d9b2e..2e216629a1d 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -1218,15 +1218,14 @@ you aren't familiar with @samp{use-package} or have no 
interest in
 learning it.  For our purposes, it's just a means of presenting
 configuration details in a tidy, standardized format.  If it helps,
 just pretend it's some make-believe, pseudo configuration language.
-Although the syntax below is easy enough to intuit and adapt to your
-setup, you may wish to keep the following in mind (or @pxref{Top,,,
-use-package,}):
+And while the syntax below is easy enough to intuit and adapt to your
+setup, you may wish to keep the following in mind:
 
 @itemize @bullet
 @item
 Each @code{use-package} ``declaration'' focuses on a library
 ``feature'', which is just a symbol you'd normally @code{require} in
-your config @pxref{Named Features,,, elisp,}).
+your config.
 
 @item
 Emacs loads anything in a @code{:config} section @emph{after} loading
@@ -1235,6 +1234,10 @@ whatever library @code{provide}s the declaration's 
feature.
 @item
 Everything in a @code{:custom} or @code{:custom-face} section is
 basically something you'd find in your @code{custom-file}.
+
+@item
+For more info, @pxref{Named Features,,, elisp,}, or @pxref{Top,,,
+use-package,}.
 @end itemize
 
 @noindent
@@ -1300,12 +1303,12 @@ settings (@pxref{Sample configuration via Customize}).
 
 (use-package erc-goodies
   ;; Turn on read indicators when joining channels.
-  :hook (erc-join . my-erc-enable-read-indicator-on-join))
+  :hook (erc-join . my-erc-enable-keep-place-indicator-on-join))
 
 (defvar my-erc-read-indicator-channels '("#emacs")
   "Channels in which to show a `keep-place-indicator'.")
 
-(defun my-erc-enable-read-indicator-on-join ()
+(defun my-erc-enable-keep-place-indicator-on-join ()
   "Enable read indicators for certain queries or channels."
   (when (member (erc-default-target) my-erc-read-indicator-channels)
     (erc-keep-place-indicator-mode +1)))
@@ -1313,14 +1316,16 @@ settings (@pxref{Sample configuration via Customize}).
 ;; Handy commands from the Emacs Wiki.
 (defun erc-cmd-TRACK (&optional target)
   "Start tracking TARGET or that of current buffer."
-  (setq erc-track-exclude (delete (or target (erc-default-target))
-                                  erc-track-exclude)))
+  (setq erc-track-exclude
+        (delete (or target (erc-default-target) (current-buffer))
+                erc-track-exclude)))
 
 (defun erc-cmd-UNTRACK (&optional target)
   "Stop tracking TARGET or that of current buffer."
-  (setq erc-track-exclude (cl-pushnew (or target (erc-default-target))
-                                      erc-track-exclude
-                                      :test #'equal)))
+  (setq erc-track-exclude
+        (cl-pushnew (or target (erc-default-target) (current-buffer))
+                    erc-track-exclude
+                    :test #'equal)))
 
 @end lisp
 
diff --git a/etc/ERC-NEWS b/etc/ERC-NEWS
index cd0b8e5f823..4c881e32ab4 100644
--- a/etc/ERC-NEWS
+++ b/etc/ERC-NEWS
@@ -15,13 +15,14 @@ GNU Emacs since Emacs version 22.1.
 * Changes in ERC 5.6
 
 ** Module 'keep-place' has gained a more flamboyant cousin.
-Remember your place in ERC buffers a bit more easily while retaining
-the freedom to look around.  Optionally sync the indicator to any
-progress made when you haven't yet caught up to the live stream.  See
-options 'erc-keep-place-indicator-style' and friends, and try M-x
+Remember your place in ERC buffers more easily while retaining the
+freedom to look around, all with the help of a configurable, visible
+indicator.  Optionally sync the indicator to any progress made when
+you haven't yet caught up to the live stream.  See options
+'erc-keep-place-indicator-style' and friends, and try M-x
 keep-place-indicator-mode to see it in action.
 
-** Module 'fill' now offers a style based on 'visual-line-mode'.
+** Module 'fill' offers a style based on 'visual-line-mode'.
 This fill style mimics the "hanging indent" look of 'erc-fill-static'
 and provides some movement and editing commands to optionally tame the
 less familiar aspects of 'visual-line' behavior.  An interactive
@@ -29,7 +30,7 @@ helper called 'erc-fill-wrap-nudge' allows for dynamic 
"refilling" of
 buffers on the fly.  Set 'erc-fill-function' to 'erc-fill-wrap' to get
 started.
 
-** A new module for nickname highlighting has joined ERC.
+** A module for nickname highlighting has joined ERC.
 Automatic nickname coloring has come to ERC core.  Users familiar with
 'erc-hl-nicks', from which this module directly descends, will already
 be familiar with its suite of handy options.  By default, each
@@ -140,7 +141,7 @@ This is especially handy when using the option 
'erc-fill-wrap-merge'
 to omit repeated speaker tags, which can make message boundaries less
 detectable by tired eyes.
 
-** Some keybindings are now set by modules rather than their libraries.
+** Modules rather than their libraries set major-mode keybindings.
 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
@@ -149,7 +150,7 @@ previously created.  Note that while all affected bindings 
still
 reside in 'erc-mode-map', future built-in modules will use their own
 minor-mode maps, and new third-party modules should do the same.
 
-** The option 'erc-timestamp-format-right' has been deprecated.
+** Option 'erc-timestamp-format-right' deprecated.
 Having to account for this option prevented other ERC modules from
 easily determining what right-hand stamps would look like before
 insertion, which is knowledge needed for certain UI decisions.  The
@@ -270,7 +271,7 @@ encouraged to keep a module's name aligned with its group's 
as well as
 the provided feature of its containing library, if only for the usual
 reasons of namespace hygiene and discoverability.
 
-*** ERC now supports arbitrary CHANTYPES.
+*** ERC supports arbitrary CHANTYPES.
 Specifically, channels can be prefixed with any predesignated
 character, mainly to afford more flexibility to specialty services,
 like bridges to other protocols.
@@ -281,7 +282,7 @@ specify a subcommand to actually carry out anything of 
consequence.
 Built-in modules can now provide more detailed help for a particular
 subcommand by telling ERC to defer to a specialized handler.
 
-*** Longtime quasi modules have been made proper.
+*** Longtime quasi modules made proper.
 The 'fill' module is now defined by 'define-erc-module'.  The same
 goes for ERC's imenu integration, which has 'imenu' now appearing in
 the default value of 'erc-modules'.
@@ -299,7 +300,7 @@ third-party code, the key takeaway is that more 
'font-lock-face'
 properties encountered in the wild may be combinations of faces rather
 than lone ones.
 
-*** Prompt input is split before 'erc-pre-send-functions' has a say.
+*** Prompt input split before 'erc-pre-send-functions' gets a say.
 Hook members are now treated to input whose lines have already been
 adjusted to fall within the allowed length limit.  For convenience,
 third-party code can request that the final input be "re-filled" prior
diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index 03c21059a92..eca6a90d706 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -6350,7 +6350,9 @@ This option mainly prevents text accidentally entered 
into Emacs
 from being sent to the server.  Offending sources include
 terminal multiplexers, desktop-automation scripts, and anything
 capable of rapidly submitting successive lines of prompt input.
-For example, entering \"one\\ntwo\\nthree\\n\" will send \"one\"
+For example, if you could somehow manage to type \"one \\`RET'
+two \\`RET' three \\`RET'\" at the prompt in less than
+`erc-accidental-paste-threshold-seconds', ERC would send \"one\"
 to the server, leave \"two\" at the prompt, and insert \"three\"
 into an \"overflow\" buffer.  See `erc-inhibit-multiline-input'
 and `erc-warn-about-blank-lines' for suppression involving input