GNU bug report logs - #1478
23.0.60; doc string of custom-unlispify-*

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 1478 in the body.
You can then email your comments to 1478 AT debbugs.gnu.org in the normal way.

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

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <emacs-pretest-bug <at> gnu.org>
Subject: 23.0.60; doc string of custom-unlispify-*
Date: Tue, 2 Dec 2008 16:00:21 -0800

1. The doc string of `custom-unlispify-menu-entries' says only this:
 
 "Display menu entries as words instead of symbols if non-nil."
 
What menu entries? Which menu?
 
It took me a while, searching and experimenting, to find that this is
about the `Custom' menu's submenus. Please clarify what this is for in
the doc string.

2. The doc string of `custom-unlispify-tag-names' says only this:

 "Display tag names as words instead of symbols if non-nil."

What's a tag name? This won't make much sense to an Emacs user who isn't savvy
to Emacs Lisp, `defcustom' :type, and :tag. Please explain this
better. A simple illustrative example never hurts: show what happens if
it's nil vs if it's non-nil.

These doc strings are all the user has to go on, since these options are not
described in any manual.
 

In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-11-24 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include
-fno-crossjumping'
 

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 1478 <at> debbugs.gnu.org
Subject: Re: 23.0.60; doc string of custom-unlispify-*
Date: Sun, 10 Jul 2011 14:57:14 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> 1. The doc string of `custom-unlispify-menu-entries' says only this:
>
>  "Display menu entries as words instead of symbols if non-nil."
>
> What menu entries? Which menu?
>
> It took me a while, searching and experimenting, to find that this is
> about the `Custom' menu's submenus. Please clarify what this is for in
> the doc string.

I disagree.  The grouping is `custom-menu', so what else could it be
referring to?  This would be like if all dired variables and commands
had doc strings starting with "In Dired...".

> 2. The doc string of `custom-unlispify-tag-names' says only this:
>
>  "Display tag names as words instead of symbols if non-nil."
>
> What's a tag name? This won't make much sense to an Emacs user who isn't savvy
> to Emacs Lisp, `defcustom' :type, and :tag. Please explain this
> better. A simple illustrative example never hurts: show what happens if
> it's nil vs if it's non-nil.

This is for (very special) people who want to customize the Customize
low-level thingamabobs.  I think they probably know what a tag is, if
they want to change it.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <1478 <at> emacsbugs.donarmstrong.com>, <emacs-pretest-bug <at> gnu.org>
Subject: RE: bug#1478: 23.0.60; doc string of custom-unlispify-*
Date: Sun, 10 Jul 2011 10:13:59 -0700

1. I did not receive Lars's message explaining why he thinks this is not a bug.
Something wrong with the bug tracker?  I received a `close' message that said
nothing more than it is closed.  I had to go to the web site to see Lars's
message.


2. I disagree with everything Lars wrote about this bug.

a. This is about _doc strings_.  It is not about the Customize UI.

b. `custom-unlispify-menu-entries': Please mention in the doc string what menu
is involved, and which menu entries.

c. `custom-unlispify-tag-names': No, this is not only "for (very special) people
who want to Customize low-level thingamabobs."

Just because you might not be interested in understanding this function, do not
assume that someone who wants to understand it intends to customize low-level
Customize thingamabobs.

I, as one user who wants to understand this, and who went to the trouble to file
a detailed bug report about missing info, do not know what is meant by a "tag"
in this context.

I have no intention of changing a tag (esp. since I don't even know what is
being referred to here by that name).   But I want to understand this doc
string.

These doc strings are for users.  So far, they are not comprehensible.

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <1478 <at> emacsbugs.donarmstrong.com>, <1478 <at> debbugs.gnu.org>
Subject: RE: bug#1478: 23.0.60; doc string of custom-unlispify-*
Date: Sun, 10 Jul 2011 10:22:08 -0700

> 1. I did not receive Lars's message explaining why he thinks
> this is not a bug.  Something wrong with the bug tracker?
> I received a `close' message that said nothing more than it
> is closed.  I had to go to the web site to see Lars's message.

I take back that part.  I got the message.  Might have been a little problem
because it was being sent to two different bug-tracker addresses - dunno.

The rest of my reply stands, however.

Message #35 received at 1478-close <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 1478-close <at> debbugs.gnu.org
Subject: Re: bug#1478: 23.0.60; doc string of custom-unlispify-*
Date: Tue, 02 Aug 2011 18:10:33 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> 2. I disagree with everything Lars wrote about this bug.

I still agree with myself, so I'm closing this report.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Previous Next

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