bug#1478: 23.0.60; doc string of custom-unlispify-*

bug#1478: 23.0.60; doc string of custom-unlispify-*

[Drew Adams]

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'
 

bug#1478: 23.0.60; doc string of custom-unlispify-*

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@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/

bug#1478: 23.0.60; doc string of custom-unlispify-*

[Drew Adams]

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.

bug#1478: 23.0.60; doc string of custom-unlispify-*

[Drew Adams]

> 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.

bug#1478: 23.0.60; doc string of custom-unlispify-*

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@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/