From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#37925: 26.3; Elisp manual: add index entry for sets/kinds of variables Date: Sat, 26 Oct 2019 19:26:04 +0300 Message-ID: <83o8y3tqw3.fsf@gnu.org> References: <> <<838sp8vvjx.fsf@gnu.org>> <6ead854d-970c-43b0-a799-9d0082fd35ba@default> Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="57892"; mail-complaints-to="usenet@blaine.gmane.org" Cc: 37925@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Oct 26 18:27:18 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iOOuL-000Ewu-SI for geb-bug-gnu-emacs@m.gmane.org; Sat, 26 Oct 2019 18:27:17 +0200 Original-Received: from localhost ([::1]:40728 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iOOuK-0005qw-M9 for geb-bug-gnu-emacs@m.gmane.org; Sat, 26 Oct 2019 12:27:16 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59502) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iOOu7-0005bs-NS for bug-gnu-emacs@gnu.org; Sat, 26 Oct 2019 12:27:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iOOu5-0002pJ-QZ for bug-gnu-emacs@gnu.org; Sat, 26 Oct 2019 12:27:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:60830) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iOOu5-0002pF-NW for bug-gnu-emacs@gnu.org; Sat, 26 Oct 2019 12:27:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1iOOu5-0002EI-Hf for bug-gnu-emacs@gnu.org; Sat, 26 Oct 2019 12:27:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 26 Oct 2019 16:27:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 37925 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: moreinfo Original-Received: via spool by 37925-submit@debbugs.gnu.org id=B37925.15721071868516 (code B ref 37925); Sat, 26 Oct 2019 16:27:01 +0000 Original-Received: (at 37925) by debbugs.gnu.org; 26 Oct 2019 16:26:26 +0000 Original-Received: from localhost ([127.0.0.1]:41418 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iOOtW-0002DI-0M for submit@debbugs.gnu.org; Sat, 26 Oct 2019 12:26:26 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:50396) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iOOtU-0002D5-Fx for 37925@debbugs.gnu.org; Sat, 26 Oct 2019 12:26:24 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:43133) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1iOOtP-0002dk-5L; Sat, 26 Oct 2019 12:26:19 -0400 Original-Received: from [176.228.60.248] (port=3429 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1iOOtN-0006R1-No; Sat, 26 Oct 2019 12:26:18 -0400 In-reply-to: <6ead854d-970c-43b0-a799-9d0082fd35ba@default> (message from Drew Adams on Sat, 26 Oct 2019 08:41:59 -0700 (PDT)) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:170214 Archived-At: > Date: Sat, 26 Oct 2019 08:41:59 -0700 (PDT) > From: Drew Adams > Cc: 37925@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?