Improve documentation of recent changes in Comint

* lisp/comint.el (comint-insert-previous-argument)
(comint-arguments, comint-insert-previous-argument-from-end):
Doc fixes.
(comint-insert-previous-argument-from-end): Add :version.

* doc/emacs/misc.texi (Shell Ring): Fix a typo in the name of
'comint-insert-previous-argument'.  Document
'comint-insert-previous-argument-from-end'.  (Bug#25271)

* etc/NEWS: Reformat and rephrase the entry for recent Comint
changes.

3 files changed, 46 insertions, 32 deletions

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 7c595388ead..24586eb2813 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -1133,7 +1133,7 @@ Fetch the next subsequent command from the history
 
 @item C-c .
 @kindex C-c . @r{(Shell mode)}
-@findex comint-input-previous-argument
+@findex comint-insert-previous-argument
 Fetch one argument from an old shell command
 (@code{comint-input-previous-argument}).
 
@@ -1180,14 +1180,20 @@ you just repeated.  Then type @key{RET} to reexecute this command.  You
 can reexecute several successive commands by typing @kbd{C-c C-x
 @key{RET}} over and over.
 
-  The command @kbd{C-c .}@: (@code{comint-input-previous-argument})
+  The command @kbd{C-c .}@: (@code{comint-insert-previous-argument})
 copies an individual argument from a previous command, like
-@kbd{@key{ESC} .} in Bash.  The simplest use copies the last argument from the
-previous shell command.  With a prefix argument @var{n}, it copies the
-@var{n}th argument instead.  Repeating @kbd{C-c .} copies from an
-earlier shell command instead, always using the same value of @var{n}
-(don't give a prefix argument when you repeat the @kbd{C-c .}
-command).
+@kbd{@key{ESC} .}@: in Bash and @command{zsh}.  The simplest use
+copies the last argument from the previous shell command.  With a
+prefix argument @var{n}, it copies the @var{n}th argument instead.
+Repeating @kbd{C-c .} copies from an earlier shell commands, always
+using the same value of @var{n}  (don't give a prefix argument when
+you repeat the @kbd{C-c .} command).
+
+@vindex comint-insert-previous-argument-from-end
+  If you set @code{comint-insert-previous-argument-from-end} to a
+non-@code{nil} value, @kbd{C-c .}@: will instead copy the @var{n}th
+argument counting from the last one; this emulates @kbd{@key{ESC} .}@:
+in @command{zsh}.
 
   These commands get the text of previous shell commands from a special
 history list, not from the shell buffer itself.  Thus, editing the shell
diff --git a/etc/NEWS b/etc/NEWS
index 5568e29eb8e..f290e76e445 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -186,24 +186,29 @@ navigation and editing of large files.
 * Changes in Specialized Modes and Packages in Emacs 27.1
 
 ** Browse-url
+
 *** The function 'browse-url-emacs' can now visit a URL in selected window.
 It now treats the optional 2nd argument to mean that the URL should be
 shown in the currently selected window.
 
 ** Comint
-*** 'comint-insert-previous-argument' no longer interprets &.
-This worked strangely in shell-mode in the presence of &&.  And omitting this
-logic makes sense since 'comint-insert-previous-argument' exists to emulate M-.
-in bash and zsh, and neither of those treat & specially.
-
-*** 'comint-insert-previous-argument' knows how to count args
-from the beginning or from the end.  This is useful because
-'comint-insert-previous-argument' exists to emulate M-. in bash and zsh; and
-bash counts from the start while zsh counts from the end.
-
-*** New variable 'comint-insert-previous-argument-from-end' controls whether
-args passed to 'comint-insert-previous-argument' count from the beginning or
-from the end
+
++++
+*** 'C-c .' (comint-insert-previous-argument) no longer interprets '&'.
+This feature caused problems when '&&' was present in the previous
+command.  Since this command emulates 'M-.' in Bash and zsh, neither
+of which treats '&' specially, the feature was removed for
+compatibility with these shells.
+
++++
+*** 'comint-insert-previous-argument' can now count arguments from the end.
+By default, invoking 'C-c .' with a numeric argument N would copy the
+Nth argument, counting from the first one.  But if the new option
+'comint-insert-previous-argument-from-end' is non-nil, it will copy
+the Nth argument counting from the last one.  Thus 'C-c .' can now
+better emulate 'M-.' in both Bash and zsh, since the former counts
+from the beginning of the arguments, while the latter counts from the
+end.
 
 ** Flymake
 
diff --git a/lisp/comint.el b/lisp/comint.el
index 82c547c9760..71a2b5eca55 100644
--- a/lisp/comint.el
+++ b/lisp/comint.el
@@ -1682,8 +1682,9 @@ characters), and are not considered to be delimiters."
 
 (defun comint-arguments (string nth mth)
   "Return from STRING the NTH to MTH arguments.
-NTH and/or MTH can be nil, which means the last argument.  NTH
-and MTH can be <0 to count from the end; -1 means last argument.
+NTH and/or MTH can be nil, which means the last argument.
+NTH and MTH can be negative to count from the end; -1 means
+the last argument.
 Returned arguments are separated by single spaces.  We assume
 whitespace separates arguments, except within quotes and except
 for a space or tab that immediately follows a backslash.  Also, a
@@ -2660,14 +2661,15 @@ text matching `comint-prompt-regexp'."
 (defvar-local comint-insert-previous-argument-last-index nil)
 
 (defcustom comint-insert-previous-argument-from-end nil
-  "If nil, the INDEX argument to
-`comint-insert-previous-argument' refers to the INDEX-th
-argument, counting from the beginning; if non-nil, counting from
-the end.  This exists to emulate the bahavior of `M-number M-.'
-in bash and zsh: in bash, `number' counts from the
-beginning (variable in nil), while in zsh it counts from the end."
+  "If non-nil, `comint-insert-previous-argument' counts args from the end.
+If this variable is nil, the default, `comint-insert-previous-argument'
+counts the arguments from the beginning; if non-nil, it counts from
+the end instead.  This allows to emulate the behavior of `ESC-NUM ESC-.'
+in both Bash and zsh: in Bash, `number' counts from the
+beginning (variable is nil), while in zsh, it counts from the end."
   :type 'boolean
-  :group 'comint)
+  :group 'comint
+  :version "27.1")
 
 (defun comint-insert-previous-argument (index)
   "Insert the INDEXth argument from the previous Comint command-line at point.
@@ -2676,8 +2678,9 @@ necessary to ensure that it's separated from adjacent arguments.
 Interactively, if no prefix argument is given, the last argument is inserted.
 Repeated interactive invocations will cycle through the same argument
 from progressively earlier commands (using the value of INDEX specified
-with the first command).  Values of INDEX<0 count from the end, so INDEX=-1
-is the last argument.  This command is like `M-.' in bash and zsh."
+with the first command).  Values of INDEX < 0 count from the end, so
+INDEX = -1 is the last argument.  This command is like `M-.' in
+Bash and zsh."
   (interactive "P")
   (unless (null index)
     (setq index (prefix-numeric-value index)))