master 190e1fe94b 1/2: EUDC: Update save-query-as-kill name and docstring

[Thomas Fitzsimmons]

branch: master
commit 190e1fe94bcc1968a1c607093b7e03a2dddaac59
Author: Thomas Fitzsimmons <fitzsim@fitzsim.org>
Commit: Thomas Fitzsimmons <fitzsim@fitzsim.org>

    EUDC: Update save-query-as-kill name and docstring
    
    * lisp/net/eudc-vars.el (eudc-server): Fix quoting for checkdoc.
    (eudc-expansion-save-query-as-kill): Rename from
    `eudc-expansion-overwrites-query'.  Define obsolete variable
    alias.  Update comment and documentation.
    * lisp/net/eudc.el (eudc-expand-inline): Rename `replace' argument
    to `save-query-as-kill'.  Update argument documentation.
    * doc/misc/eudc.texi (Inline Query Expansion): Rename
    `eudc-expand-inline' argument.
    * etc/NEWS (EUDC): Document `eudc-expansion-overwrites-query'
    rename to `eudc-expansion-save-query-as-kill'.
---
 doc/misc/eudc.texi    | 18 ++++++++++--------
 etc/NEWS              |  8 ++++++++
 lisp/net/eudc-vars.el | 15 ++++++++++-----
 lisp/net/eudc.el      | 11 ++++++-----
 4 files changed, 34 insertions(+), 18 deletions(-)

diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi
index 7c37ae5505..7de0bdc180 100644
--- a/doc/misc/eudc.texi
+++ b/doc/misc/eudc.texi
@@ -723,17 +723,19 @@ controlled by the variables 
@code{eudc-inline-expansion-format},
 If the query fails for a server, other servers may be tried successively
 until one of them finds a match (@pxref{Multi-server Queries}).
 
-@deffn Command eudc-expand-inline replace-p
+@deffn Command eudc-expand-inline save-query-as-kill-p
 Query the server and expand the query string before point.  The query
 string consists of the buffer substring from the point back to the
-preceding comma, colon or beginning of
-line.  @code{eudc-inline-query-format} controls how individual words
-are mapped onto directory attribute names.  After querying the server
-for the given string, the expansion specified by
+preceding comma, colon or beginning of line.
+@code{eudc-inline-query-format} controls how individual words are
+mapped onto directory attribute names.  After querying the server for
+the given string, the expansion specified by
 @code{eudc-inline-expansion-format} is inserted in the buffer at
-point. If @var{replace-p} is @code{t} then this expansion replaces the
-query string in the buffer.  If @code{eudc-expanding-overwrites-query}
-is non-@code{nil} then the meaning of @var{replace-p} is negated.
+point.  If multiple matches are available, a selection window is
+displayed.  If @var{save-query-as-kill-p} is @code{t} then the query
+string is saved to the kill ring.  If
+@code{eudc-expansion-save-query-as-kill} is non-@code{nil} then the
+meaning of @var{save-query-as-kill-p} is negated.
 @end deffn
 
 @defvar eudc-inline-query-format
diff --git a/etc/NEWS b/etc/NEWS
index 80cf0a2f72..cd3db07e6e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -630,6 +630,14 @@ header before sending a message.
 *** 'texinfo-mode' now has a specialised 'narrow-to-defun' definition.
 It narrows to the current node.
 
+** EUDC
+
++++
+*** 'eudc-expansion-overwrites-query' to 'eudc-expansion-save-query-as-kill'.
+Rename 'eudc-expansion-overwrites-query' to
+'eudc-expansion-save-query-as-kill' to reflect the actual behaviour of
+the customization variable.
+
 ** eww/shr
 
 +++
diff --git a/lisp/net/eudc-vars.el b/lisp/net/eudc-vars.el
index 3122b26cd8..997b9e30fd 100644
--- a/lisp/net/eudc-vars.el
+++ b/lisp/net/eudc-vars.el
@@ -42,7 +42,7 @@ A port number may be specified by appending a colon and a
 number to the name of the server.  Use `localhost' if the directory
 server resides on your computer (BBDB backend).
 
-To specify multiple servers, customize eudc-server-hotlist
+To specify multiple servers, customize `eudc-server-hotlist'
 instead."
   :type  '(choice (string :tag "Server") (const :tag "None" nil)))
 
@@ -179,10 +179,15 @@ must be set in a protocol/server-local fashion, see 
`eudc-server-set' and
             (symbol :menu-tag "Other" :tag "Attribute name"))))
   :version "25.1")
 
-;; Default to nil so that the most common use of eudc-expand-inline,
-;; where replace is nil, does not affect the kill ring.
-(defcustom eudc-expansion-overwrites-query nil
-  "If non-nil, expanding a query overwrites the query string."
+(define-obsolete-variable-alias
+  'eudc-expansion-overwrites-query
+  'eudc-expansion-save-query-as-kill
+  "29.1")
+
+;; Default to nil so that the most common use of `eudc-expand-inline',
+;; where `save-query-as-kill' is nil, does not affect the kill ring.
+(defcustom eudc-expansion-save-query-as-kill nil
+  "If non-nil, expansion saves the query string to the kill ring."
   :type  'boolean
   :version "25.1")
 
diff --git a/lisp/net/eudc.el b/lisp/net/eudc.el
index 6831c4ffe3..dbba69d110 100644
--- a/lisp/net/eudc.el
+++ b/lisp/net/eudc.el
@@ -743,7 +743,7 @@ If none try N - 1 and so forth."
 
 
 ;;;###autoload
-(defun eudc-expand-inline (&optional replace)
+(defun eudc-expand-inline (&optional save-query-as-kill)
   "Query the directory server, and expand the query string before point.
 The query string consists of the buffer substring from the point back to
 the preceding comma, colon or beginning of line.
@@ -751,8 +751,9 @@ The variable `eudc-inline-query-format' controls how to 
associate the
 individual inline query words with directory attribute names.
 After querying the server for the given string, the expansion specified by
 `eudc-inline-expansion-format' is inserted in the buffer at point.
-If REPLACE is non-nil, then this expansion replaces the name in the buffer.
-`eudc-expansion-overwrites-query' being non-nil inverts the meaning of REPLACE.
+If SAVE-QUERY-AS-KILL is non-nil, then save the pre-expansion
+text to the kill ring.  `eudc-expansion-save-query-as-kill' being
+non-nil inverts the meaning of SAVE-QUERY-AS-KILL.
 Multiple servers can be tried with the same query until one finds a match,
 see `eudc-inline-expansion-servers'."
   (interactive)
@@ -769,8 +770,8 @@ see `eudc-inline-expansion-servers'."
         (error "No match")
 
       (if (or
-          (and replace (not eudc-expansion-overwrites-query))
-          (and (not replace) eudc-expansion-overwrites-query))
+          (and save-query-as-kill (not eudc-expansion-save-query-as-kill))
+          (and (not save-query-as-kill) eudc-expansion-save-query-as-kill))
          (kill-ring-save beg end))
       (cond
        ((or (= (length response-strings) 1)