GNU bug report logs -
#37925
26.3; Elisp manual: add index entry for sets/kinds of variables
Previous Next
Reported by: Drew Adams <drew.adams <at> oracle.com>
Date: Fri, 25 Oct 2019 19:44:02 UTC
Severity: wishlist
Tags: moreinfo, wontfix
Found in version 26.3
Done: Stefan Kangas <stefan <at> marxist.se>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 37925 in the body.
You can then email your comments to 37925 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#37925
; Package
emacs
.
(Fri, 25 Oct 2019 19:44:02 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Drew Adams <drew.adams <at> oracle.com>
:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org
.
(Fri, 25 Oct 2019 19:44:02 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
These nodes are about particular kinds of variables:
* Buffer-Local Variables
* Completion Variables
* Condition Variables
* Connection Local Variables
* Constant Variables
* Directory Local Variables
* File Local Variables
* Generalized Variables
* Global Variables
* List Variables
* List Variables
* Local Variables
* Mode Line Variables
* Other Font Lock Variables
* Output Variables
* Variables with Restricted Values
* Void Variables
* Warning Variables
Likewise, for options:
* Warning Options
* Choosing Window Options
* Edebug Options
* Network Options
Please consider adding index entries that correspond directly to these
node names. A user should be able to do, for example (and preferably
with or without the hyphen):
i mode-line variables
Today that's not possible.
---
[Additional remark:
The node names are not consistent wrt compound adjectives.
`Buffer-Local' is the only such that uses a hyphen. It's better to be
consistent. (Even better might be to always use a hyphen.)]
In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.17763
Configured using:
`configure --without-dbus --host=x86_64-w64-mingw32
--without-compress-install 'CFLAGS=-O2 -static -g3''
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#37925
; Package
emacs
.
(Sat, 26 Oct 2019 07:03:02 GMT)
Full text and
rfc822 format available.
Message #8 received at 37925 <at> debbugs.gnu.org (full text, mbox):
tags 37925 wishlist moreinfo
thanks
> Date: Fri, 25 Oct 2019 12:43:40 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
>
> Please consider adding index entries that correspond directly to these
> node names. A user should be able to do, for example (and preferably
> with or without the hyphen):
>
> i mode-line variables
>
> Today that's not possible.
Yes, it is possible today, because each variable is indexed by its
name. So, for example "i mode-line TAB" will show the list of all the
variables (and some other related topics as well).
In general, the technique of working with index entries that I
recommend is to try the text you thought about initially, in this case
"mode-line variables", and if that doesn't bring anything useful,
remove some text from the end and try again, with TAB. (That is
assuming the above text is something you really thought about in some
real-life use case, and not a synthetic example of no practical
importance.)
Please consider describing use cases where the name of the variable,
or the results of TAB as above, will not let the user arrive to the
place where he or she needs to be. Otherwise, what you ask for is to
provide one more index entry that begins like many others we already
have and points to the same place, something that is not useful, and
we therefore avoid it.
Thanks.
Added tag(s) moreinfo.
Request was from
Eli Zaretskii <eliz <at> gnu.org>
to
control <at> debbugs.gnu.org
.
(Sat, 26 Oct 2019 07:03:02 GMT)
Full text and
rfc822 format available.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#37925
; Package
emacs
.
(Sat, 26 Oct 2019 15:43:01 GMT)
Full text and
rfc822 format available.
Message #13 received at 37925 <at> debbugs.gnu.org (full text, mbox):
> > Please consider adding index entries that correspond directly to
> > these node names. A user should be able to do, for example (and
> > preferably with or without the hyphen):
> >
> > i mode-line variables
> >
> > Today that's not possible.
>
> Yes, it is possible today, because each variable is indexed by its
> name. So, for example "i mode-line TAB" will show the list of all the
> variables (and some other related topics as well).
That's not the "it" that I said is not possible.
That's an way to find something different:
information about a specific variable, known or
recognized as such.
> In general, the technique of working with index entries that I
> recommend is to try the text you thought about initially, in this case
> "mode-line variables", and if that doesn't bring anything useful,
> remove some text from the end and try again, with TAB. (That is
> assuming the above text is something you really thought about in some
> real-life use case, and not a synthetic example of no practical
> importance.)
You're missing the point, I think. You focus on
`mode-line' because each of the mode-line variables
has prefix `mode-line' in its name. That's not true
of some of the other kinds of variables covered (by
kind) in nodes: list, generalized, constant, output...
Some come close, and TAB with just the first part
would suffice for them. Others do not - `list',
for example.
Please read the bug title (and body). It's about
the nodes for different "sets/kinds of variables".
It's not just about mode-line variables.
Not only that. If you're interested in knowing
about mode-line variables, and you don't know
what they are, or even if there are any, their
individual names as entries won't help you much,
because the names aren't identified in the index
entries as _variable_ names.
In a real (e.g. book) index, an entry such as
`mode-line-remote' would be followed by
", variable". That's done for entry
`mode-line-format, a frame parameter'. But it's
not done for `mode-line-format' (a variable).
Beyond all of that, it's not obvious that there
even are nodes that talk about particular kinds
of variables.
Part of this problem would be alleviated by
having index entries that start with `variable'
for the various kinds covered by their own nodes:
variables, list
variables, completion
variables, generalized
...
These are the only index entries that start with
`variable':
variable
variable aliases
variable definition
variable descriptions
variable limit error
variable watchpoints
variable with constant value
variable write debugging
variable, buffer-local
variable-documentation property
variable-width spaces
Those don't take you to a node that covers
variables of a given kind, except for
`variable with a constant value' and
`variable, buffer-local'.
> Please consider describing use cases where the name of the variable,
> or the results of TAB as above, will not let the user arrive to the
> place where he or she needs to be. Otherwise, what you ask for is to
> provide one more index entry that begins like many others we already
> have and points to the same place, something that is not useful, and
> we therefore avoid it.
See above. For example, `i list TAB' will
not show you anything that suggests a node
about list variables. It won't get you to
node `List Variables'.
And no, entries such as what I suggest do
not "begin like many others we already have
and point to the same place". See above.
If there's already an entry that does that,
then no entry need be added for it. That's
the case for buffer-local variables: we have
entries `variable, buffer-local' and
`buffer-local variables'. It's not the case
in general.
And BTW, we have these entries, which go to
3 different nodes. They're not distinguished
at the level of entries (except for the 2nd
one).
buffer-local variables
buffer-local variables in modes
buffer-local-variables
It would be clearer if the last one were
called `buffer-local-variables, function'.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#37925
; Package
emacs
.
(Sat, 26 Oct 2019 16:27:01 GMT)
Full text and
rfc822 format available.
Message #16 received at 37925 <at> debbugs.gnu.org (full text, mbox):
> Date: Sat, 26 Oct 2019 08:41:59 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 37925 <at> debbugs.gnu.org
>
> > > Please consider adding index entries that correspond directly to
> > > these node names. A user should be able to do, for example (and
> > > preferably with or without the hyphen):
> > >
> > > i mode-line variables
> > >
> > > Today that's not possible.
> >
> > Yes, it is possible today, because each variable is indexed by its
> > name. So, for example "i mode-line TAB" will show the list of all the
> > variables (and some other related topics as well).
>
> That's not the "it" that I said is not possible.
> That's an way to find something different:
> information about a specific variable, known or
> recognized as such.
Why isn't that enough?
> > In general, the technique of working with index entries that I
> > recommend is to try the text you thought about initially, in this case
> > "mode-line variables", and if that doesn't bring anything useful,
> > remove some text from the end and try again, with TAB. (That is
> > assuming the above text is something you really thought about in some
> > real-life use case, and not a synthetic example of no practical
> > importance.)
>
> You're missing the point, I think. You focus on
> `mode-line' because each of the mode-line variables
> has prefix `mode-line' in its name. That's not true
> of some of the other kinds of variables covered (by
> kind) in nodes: list, generalized, constant, output...
I took mode-line because that was your example.
The bug report in its entirety is not useful because it lumps together
several (too many) sections that are almost certainly unrelated, in
terms of why there is no index entry that you decided were necessary.
These matters should be always considered on a case by case basis.
> Please read the bug title (and body).
I had, please don't make nasty assumptions, and if you do, please have
the courtesy of keeping them to yourself.
> Not only that. If you're interested in knowing
> about mode-line variables, and you don't know
> what they are, or even if there are any, their
> individual names as entries won't help you much,
> because the names aren't identified in the index
> entries as _variable_ names.
Why would I want to know about mode-line variables as a group? That
subsection is a hodgepodge of unrelated variables, with nothing to
keep them together. What is the use case for me to want to see all of
them?
> > Please consider describing use cases where the name of the variable,
> > or the results of TAB as above, will not let the user arrive to the
> > place where he or she needs to be. Otherwise, what you ask for is to
> > provide one more index entry that begins like many others we already
> > have and points to the same place, something that is not useful, and
> > we therefore avoid it.
>
> See above. For example, `i list TAB' will
> not show you anything that suggests a node
> about list variables. It won't get you to
> node `List Variables'.
OK, let's take this example. For starters, there are no "list
variables" in Emacs. The section's name is "Modifying List
Variables", which is something else entirely. This section has the
following index entries:
@cindex modify a list
@cindex list modification
In addition, each function described in the section is indexed by its
name. Why would we want to add to that an index entry "list
variables", if it has nothing to do with the section's contents or
even its name?
So please look at each section separately, read its content, and then
tell what index entries you think are missing, and why, and please do
that separately for each section. Arguing about missing index entries
from _node_names_, just because they all end in "Variables", is the
wrong way.
> And BTW, we have these entries, which go to
> 3 different nodes. They're not distinguished
> at the level of entries (except for the 2nd
> one).
>
> buffer-local variables
> buffer-local variables in modes
> buffer-local-variables
They are all different entries, so what's wrong with them? Also, how
is this related to the subject of this bug report?
Reply sent
to
Stefan Kangas <stefan <at> marxist.se>
:
You have taken responsibility.
(Thu, 16 Jan 2020 22:50:02 GMT)
Full text and
rfc822 format available.
Notification sent
to
Drew Adams <drew.adams <at> oracle.com>
:
bug acknowledged by developer.
(Thu, 16 Jan 2020 22:50:02 GMT)
Full text and
rfc822 format available.
Message #21 received at 37925-done <at> debbugs.gnu.org (full text, mbox):
Eli Zaretskii <eliz <at> gnu.org> writes:
> The bug report in its entirety is not useful because it lumps together
> several (too many) sections that are almost certainly unrelated, in
> terms of why there is no index entry that you decided were necessary.
> These matters should be always considered on a case by case basis.
[...]
> So please look at each section separately, read its content, and then
> tell what index entries you think are missing, and why, and please do
> that separately for each section. Arguing about missing index entries
> from _node_names_, just because they all end in "Variables", is the
> wrong way.
>
>> And BTW, we have these entries, which go to
>> 3 different nodes. They're not distinguished
>> at the level of entries (except for the 2nd
>> one).
>>
>> buffer-local variables
>> buffer-local variables in modes
>> buffer-local-variables
>
> They are all different entries, so what's wrong with them? Also, how
> is this related to the subject of this bug report?
More information was requested, but none was given within 12 weeks, so
I'm closing this bug. If this is still an issue, please reply to this
email (use "Reply to all" in your email client) and we can reopen the
bug report.
Best regards,
Stefan Kangas
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#37925
; Package
emacs
.
(Thu, 16 Jan 2020 22:58:01 GMT)
Full text and
rfc822 format available.
Message #24 received at 37925-done <at> debbugs.gnu.org (full text, mbox):
> More information was requested, but none was given within 12 weeks, so
> I'm closing this bug. If this is still an issue, please reply to this
> email (use "Reply to all" in your email client) and we can reopen the
> bug report.
Yes, it's still an issue. But Eli has made it clear
that this won't be fixed. The closing should be as
"wont-fix", to be honest.
Added tag(s) wontfix.
Request was from
Stefan Kangas <stefan <at> marxist.se>
to
control <at> debbugs.gnu.org
.
(Thu, 16 Jan 2020 23:17:02 GMT)
Full text and
rfc822 format available.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org
.
(Fri, 14 Feb 2020 12:24:05 GMT)
Full text and
rfc822 format available.
This bug report was last modified 4 years and 65 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.