Re: Remove * characters from the front of variable docstrings

Re: Remove * characters from the front of variable docstrings

[Tino Calancha]

This is about discussion in:
https://lists.gnu.org/archive/html/emacs-devel/2012-04/msg00788.html

On Thu, 26 Apr 2012, Stefan Monnier wrote:

>On Thu, 26 Apr 2012, Glenn Morris wrote:
>> However, hasn't some information been lost in the process?

>Yup.  It should only have been applied to defcustoms.

>> Shouldn't it (and other defvars with *s) have been converted to 
defcustoms?

>They should be converted to defcustoms, indeed, and only after that can
>the * be removed.

How about updating `shell-command-default-error-buffer' to a defcustom?
See patch below:

PD: There are more cases in commit fb7ada5f: defvar's
having before doc strings starting with '*', and not being now a 
defcustom.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
From f10d2c98c2d3c6e0e5caf6b970c27c59176036a3 Mon Sep 17 00:00:00 2001
From: Tino Calancha <tino.calancha@gmail.com>
Date: Fri, 23 Sep 2016 19:16:00 +0900
Subject: [PATCH] * lisp/simple.el (shell-command-default-error-buffer): 
Make a
  defcustom.

---
  lisp/simple.el | 9 +++++++--
  1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/lisp/simple.el b/lisp/simple.el
index 7e68baa..196361d 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -3152,11 +3152,16 @@ shell-command-history
  (defvar shell-command-switch (purecopy "-c")
    "Switch used to have the shell execute its command line argument.")

-(defvar shell-command-default-error-buffer nil
+(defcustom shell-command-default-error-buffer nil
    "Buffer name for `shell-command' and `shell-command-on-region' error 
output.
  This buffer is used when `shell-command' or `shell-command-on-region'
  is run interactively.  A value of nil means that output to stderr and
-stdout will be intermixed in the output stream.")
+stdout will be intermixed in the output stream."
+  :type '(choice
+          (const :tag "None" nil)
+          (string "*Shell Command Error*"))
+  :group 'shell
+  :version "25.2")

  (declare-function mailcap-file-default-commands "mailcap" (files))
  (declare-function dired-get-filename "dired" (&optional localp 
no-error-if-not-filep))
-- 
2.9.3


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

In GNU Emacs 25.2.50.1 (x86_64-pc-linux-gnu, GTK+ Version 3.22.0)
  of 2016-09-23
Repository revision: 65dc67c87553bec4c8b36432246b13f09d653118

Remove * characters from the front of variable docstrings

[Glenn Morris]

I was glad to see the "*" chars finally disappearing in trunk r107813.
However, hasn't some information been lost in the process?

For example, in emacs-24 there is:

(defvar texinfo-column-for-description 32
  "*Column at which descriptions start in a Texinfo menu.")

So, this is something I might want to change.

In trunk, it has no *, so there's no indication it is something I might
want to change.
Shouldn't it (and other defvars with *s) have been converted to defcustoms?

Re: Remove * characters from the front of variable docstrings

[Glenn Morris]

Also I just noticed this error; maybe there are similar things:

 bzr diff -r 107812..107813 lisp/org/org-ctags.el

*** lisp/org/org-ctags.el	2012-04-03 12:02:21 +0000
--- lisp/org/org-ctags.el	2012-04-09 13:05:48 +0000
***************
*** 188,194 ****
  Created as a local variable in each buffer.")
  
  (defcustom org-ctags-new-topic-template
!   "* <<%t>>\n\n\n\n\n\n"
    "Text to insert when creating a new org file via opening a hyperlink.
  The following patterns are replaced in the string:
      `%t' - replaced with the capitalized title of the hyperlink"
--- 188,194 ----
  Created as a local variable in each buffer.")
  
  (defcustom org-ctags-new-topic-template
!   " <<%t>>\n\n\n\n\n\n"
    "Text to insert when creating a new org file via opening a hyperlink.
  The following patterns are replaced in the string:
      `%t' - replaced with the capitalized title of the hyperlink"

Re: Remove * characters from the front of variable docstrings

[Glenn Morris]

PS As of today, this error has now been independently propagated to the
emacs-24 branch. Fiddling with such things is really not appropriate for
the emacs-24 branch anyway at this stage. (Unless I misunderstand what
this variable is for.)

Glenn Morris wrote:

> Also I just noticed this error; maybe there are similar things:
>
>  bzr diff -r 107812..107813 lisp/org/org-ctags.el
>
> *** lisp/org/org-ctags.el	2012-04-03 12:02:21 +0000
> --- lisp/org/org-ctags.el	2012-04-09 13:05:48 +0000
> ***************
> *** 188,194 ****
>   Created as a local variable in each buffer.")
>   
>   (defcustom org-ctags-new-topic-template
> !   "* <<%t>>\n\n\n\n\n\n"
>     "Text to insert when creating a new org file via opening a hyperlink.
>   The following patterns are replaced in the string:
>       `%t' - replaced with the capitalized title of the hyperlink"
> --- 188,194 ----
>   Created as a local variable in each buffer.")
>   
>   (defcustom org-ctags-new-topic-template
> !   " <<%t>>\n\n\n\n\n\n"
>     "Text to insert when creating a new org file via opening a hyperlink.
>   The following patterns are replaced in the string:
>       `%t' - replaced with the capitalized title of the hyperlink"

Re: Remove * characters from the front of variable docstrings

[Tassilo Horn]

Glenn Morris <rgm@gnu.org> writes:

> PS As of today, this error has now been independently propagated to the
> emacs-24 branch. Fiddling with such things is really not appropriate for
> the emacs-24 branch anyway at this stage. (Unless I misunderstand what
> this variable is for.)

The asterisk is definitively important here.  If it's gone, the function
using that template won't create a new org (outline) headline as
intended.

Bye,
Tassilo

> Glenn Morris wrote:
>
>> Also I just noticed this error; maybe there are similar things:
>>
>>  bzr diff -r 107812..107813 lisp/org/org-ctags.el
>>
>> *** lisp/org/org-ctags.el	2012-04-03 12:02:21 +0000
>> --- lisp/org/org-ctags.el	2012-04-09 13:05:48 +0000
>> ***************
>> *** 188,194 ****
>>   Created as a local variable in each buffer.")
>>   
>>   (defcustom org-ctags-new-topic-template
>> !   "* <<%t>>\n\n\n\n\n\n"
>>     "Text to insert when creating a new org file via opening a hyperlink.
>>   The following patterns are replaced in the string:
>>       `%t' - replaced with the capitalized title of the hyperlink"
>> --- 188,194 ----
>>   Created as a local variable in each buffer.")
>>   
>>   (defcustom org-ctags-new-topic-template
>> !   " <<%t>>\n\n\n\n\n\n"
>>     "Text to insert when creating a new org file via opening a hyperlink.
>>   The following patterns are replaced in the string:
>>       `%t' - replaced with the capitalized title of the hyperlink"

Re: Remove * characters from the front of variable docstrings

[Bastien]

Tassilo Horn <tassilo@member.fsf.org> writes:

> Glenn Morris <rgm@gnu.org> writes:
>
>> PS As of today, this error has now been independently propagated to the
>> emacs-24 branch. Fiddling with such things is really not appropriate for
>> the emacs-24 branch anyway at this stage. (Unless I misunderstand what
>> this variable is for.)
>
> The asterisk is definitively important here.  If it's gone, the function
> using that template won't create a new org (outline) headline as
> intended.

Fixed in emacs-24, thanks.

-- 
 Bastien

Re: Remove * characters from the front of variable docstrings

[Bastien]

Glenn Morris <rgm@gnu.org> writes:

> PS As of today, this error has now been independently propagated to the
> emacs-24 branch. Fiddling with such things is really not appropriate for
> the emacs-24 branch anyway at this stage. (Unless I misunderstand what
> this variable is for.)

The problem comes from this change:

  http://git.savannah.gnu.org/cgit/emacs.git/diff/lisp/org/org-protocol.el?h=emacs-24&id=0fc749f9

I once overwrote this change during a Org>Emacs merge, then blamed
myself for overwriting such changes, so I backported it carefully into
Org, then into Emacs.

Of course, the initial change is wrong, as Tassilo pointed out.

It is now fixed in emacs-24.

-- 
 Bastien

Re: Remove * characters from the front of variable docstrings

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Date: Thu, 26 Apr 2012 14:08:19 -0400
> 
> 
> I was glad to see the "*" chars finally disappearing in trunk r107813.

I wasn't, FWIW.  Suddenly "M-x set-variable" doesn't work with
variables I was used to since about forever.

RE: Remove * characters from the front of variable docstrings

[Drew Adams]

> > I was glad to see the "*" chars finally disappearing in 
> > trunk r107813.

Why?  Who were those `*' chars hurting?

> I wasn't, FWIW.  Suddenly "M-x set-variable" doesn't work with
> variables I was used to since about forever.

I agree with Eli.  I pointed out the problem prior to the change:
http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00419.html

Others in the thread also disagreed with this change.  Here's a XEmacs
perspective:
http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00455.html

Note that that thread _started_ with the innocuous _question_ of which Emacs
versions require `*' here.  Some 3rd-party Emacs code tries to maintain
compatibility with older Emacs versions.  So it still uses `*' in defcustoms,
which is perfectly normal.

But now you have introduced the bug (still not fixed or even responded to) that
for such definitions the `*' shows up _as part of the help text_ when you use
`C-h v':
http://debbugs.gnu.org/cgi/bugreport.cgi?bug=10475

Yet the fix for that bug is trivial, as the bug report mentions:
(when (eq ?* (elt doc 0)) (setq doc  (substring doc 1)))

On n'arrete pas le progres...  Aren't there more important things to work on
than introducing such bugs and additional hurdles for 3rd-party code?

Re: Remove * characters from the front of variable docstrings

[Glenn Morris]

Eli Zaretskii wrote:

> Suddenly "M-x set-variable" doesn't work with variables I was used to
> since about forever.

Then I guess these are more things that should have been converted to
defcustoms.

Re: Remove * characters from the front of variable docstrings

[Stefan Monnier]

> However, hasn't some information been lost in the process?

Yup.  It should only have been applied to defcustoms.

> Shouldn't it (and other defvars with *s) have been converted to defcustoms?

They should be converted to defcustoms, indeed, and only after that can
the * be removed.


        Stefan