GNU bug report logs - #25069
[PATCH] Improve the doc of eshell-cmpl-* custom variables

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 25069 in the body.
You can then email your comments to 25069 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Hong Xu <hong <at> topbug.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Improve the doc of eshell-cmpl-* custom variables
Date: Tue, 29 Nov 2016 15:17:27 -0800

	* lisp/eshell/em-cmpl.el
	(eshell-cmpl--custom-variable-docstring): Add a new function to
	generate the docstring for custom variables derived from
	pcomplete-* variables.
---

The current eshell-cmpl-* documentation sometimes made me confused --
they actually show the documentation of pcomplete-*. For example,
eshell-cmpl-cycle-completions even has pcomplete-cycle-completions in
its doc without explaining the relationship between them.

This patch makes the relationship clearer.

 lisp/eshell/em-cmpl.el | 55 ++++++++++++++++++++++----------------------------
 1 file changed, 24 insertions(+), 31 deletions(-)

diff --git a/lisp/eshell/em-cmpl.el b/lisp/eshell/em-cmpl.el
index 47467678a68a..e01948cad454 100644
--- a/lisp/eshell/em-cmpl.el
+++ b/lisp/eshell/em-cmpl.el
@@ -136,75 +136,71 @@ eshell-command-completions-alist
   :type '(repeat (cons string regexp))
   :group 'eshell-cmpl)
 
+(defun eshell-cmpl--custom-variable-docstring (pcomplete-var)
+  "Generate the docstring of a variable derived from a pcomplete-* variable."
+  (format "%s\n\nIts value is assigned to `%s' locally
+after eshell starts."
+          (documentation-property pcomplete-var
+                                  'variable-documentation)
+          (symbol-name pcomplete-var)))
+
 (defcustom eshell-cmpl-file-ignore "~\\'"
-  (documentation-property 'pcomplete-file-ignore
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-file-ignore)
   :type (get 'pcomplete-file-ignore 'custom-type)
   :group 'eshell-cmpl)
 
 (defcustom eshell-cmpl-dir-ignore "\\`\\(\\.\\.?\\|CVS\\)/\\'"
-  (documentation-property 'pcomplete-dir-ignore
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-dir-ignore)
   :type (get 'pcomplete-dir-ignore 'custom-type)
   :group 'eshell-cmpl)
 
 (defcustom eshell-cmpl-ignore-case (eshell-under-windows-p)
-  (documentation-property 'pcomplete-ignore-case
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-ignore-case)
   :type (get 'pcomplete-ignore-case 'custom-type)
   :group 'eshell-cmpl)
 
 (defcustom eshell-cmpl-autolist nil
-  (documentation-property 'pcomplete-autolist
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-autolist)
   :type (get 'pcomplete-autolist 'custom-type)
   :group 'eshell-cmpl)
 
 (defcustom eshell-cmpl-suffix-list (list ?/ ?:)
-  (documentation-property 'pcomplete-suffix-list
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-suffix-list)
   :type (get 'pcomplete-suffix-list 'custom-type)
   :group 'pcomplete)
 
 (defcustom eshell-cmpl-recexact nil
-  (documentation-property 'pcomplete-recexact
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-recexact)
   :type (get 'pcomplete-recexact 'custom-type)
   :group 'eshell-cmpl)
 
 (defcustom eshell-cmpl-man-function 'man
-  (documentation-property 'pcomplete-man-function
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-man-function)
   :type (get 'pcomplete-man-function 'custom-type)
   :group 'eshell-cmpl)
 
 (defcustom eshell-cmpl-compare-entry-function 'file-newer-than-file-p
-  (documentation-property 'pcomplete-compare-entry-function
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-compare-entry-function)
   :type (get 'pcomplete-compare-entry-function 'custom-type)
   :group 'eshell-cmpl)
 
 (defcustom eshell-cmpl-expand-before-complete nil
-  (documentation-property 'pcomplete-expand-before-complete
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-expand-before-complete)
   :type (get 'pcomplete-expand-before-complete 'custom-type)
   :group 'eshell-cmpl)
 
 (defcustom eshell-cmpl-cycle-completions t
-  (documentation-property 'pcomplete-cycle-completions
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-cycle-completions)
   :type (get 'pcomplete-cycle-completions 'custom-type)
   :group 'eshell-cmpl)
 
 (defcustom eshell-cmpl-cycle-cutoff-length 5
-  (documentation-property 'pcomplete-cycle-cutoff-length
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-cycle-cutoff-length)
   :type (get 'pcomplete-cycle-cutoff-length 'custom-type)
   :group 'eshell-cmpl)
 
 (defcustom eshell-cmpl-restore-window-delay 1
-  (documentation-property 'pcomplete-restore-window-delay
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-restore-window-delay)
   :type (get 'pcomplete-restore-window-delay 'custom-type)
   :group 'eshell-cmpl)
 
@@ -212,15 +208,13 @@ eshell-command-completion-function
   (function
    (lambda ()
      (pcomplete-here (eshell-complete-commands-list))))
-  (documentation-property 'pcomplete-command-completion-function
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-command-completion-function)
   :type (get 'pcomplete-command-completion-function 'custom-type)
   :group 'eshell-cmpl)
 
 (defcustom eshell-cmpl-command-name-function
   'eshell-completion-command-name
-  (documentation-property 'pcomplete-command-name-function
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-command-name-function)
   :type (get 'pcomplete-command-name-function 'custom-type)
   :group 'eshell-cmpl)
 
@@ -231,13 +225,12 @@ eshell-default-completion-function
 	     (pcomplete-dirs-or-entries
 	      (cdr (assoc (funcall eshell-cmpl-command-name-function)
 			  eshell-command-completions-alist)))))))
-  (documentation-property 'pcomplete-default-completion-function
-			  'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-default-completion-function)
   :type (get 'pcomplete-default-completion-function 'custom-type)
   :group 'eshell-cmpl)
 
 (defcustom eshell-cmpl-use-paring t
-  (documentation-property 'pcomplete-use-paring 'variable-documentation)
+  (eshell-cmpl--custom-variable-docstring 'pcomplete-use-paring)
   :type (get 'pcomplete-use-paring 'custom-type)
   :group 'eshell-cmpl)
 
-- 
2.1.4

Message #8 received at 25069 <at> debbugs.gnu.org (full text, mbox):

From: npostavs <at> users.sourceforge.net
To: Hong Xu <hong <at> topbug.net>
Cc: 25069 <at> debbugs.gnu.org
Subject: Re: bug#25069: [PATCH] Improve the doc of eshell-cmpl-* custom
 variables
Date: Sat, 10 Jun 2017 08:10:55 -0400

Hong Xu <hong <at> topbug.net> writes:

> +          (documentation-property pcomplete-var
> +                                  'variable-documentation)

We should pass non-nil for the RAW argument to stop references like
\[pcomplete-cycle] from being substituted too soon.

Message #11 received at 25069 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> users.sourceforge.net>
To: Hong Xu <hong <at> topbug.net>
Cc: 25069 <at> debbugs.gnu.org
Subject: Re: bug#25069: [PATCH] Improve the doc of eshell-cmpl-* custom
 variables
Date: Thu, 02 Nov 2017 20:51:55 -0400

tags 25069 fixed
close 25069 26.1
quit

npostavs <at> users.sourceforge.net writes:

> Hong Xu <hong <at> topbug.net> writes:
>
>> +          (documentation-property pcomplete-var
>> +                                  'variable-documentation)
>
> We should pass non-nil for the RAW argument to stop references like
> \[pcomplete-cycle] from being substituted too soon.

Added RAW arg, pushed to emacs-26.

[1: ac0bb9a192]: 2017-11-02 20:38:09 -0400
  Improve the doc of eshell-cmpl-* custom variables (Bug#25069)
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=ac0bb9a192f1e5de4ddc938b71e5a49d36e48a2d

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.