bug#21594: 25.0.50; (elisp): node `Variable Definitions' is not reachable by `i variable definition'

bug#21594: 25.0.50; (elisp): node `Variable Definitions' is not reachable by `i variable definition'

[Drew Adams]

The problem is more the node name than the index entry.  The node title,
within the node, is `Defining Customization Variables', which is much
better.

I imagine that the node name was picked because the node is a subnode of
node `Customization', but that is not a good enough reason.
`Info-goto-node' handles the nodes of a manual in a flat way.

A node named `Variable Definitions' should cover all of defvar,
defconst, and defcustom.  Likewise, an index entry named `variable
definition'.  IOW, someone hunting for info about variable definitions
should be able to get to general info about all kinds of variable
definitions.



In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-09-23
Bzr revision: 325200ac1dcf5bed6918ea827d8a48d89487e083
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-pc-mingw32 --enable-checking=yes,glyphs'

bug#21594: 25.0.50; (elisp): node `Variable Definitions' is not reachable by `i variable definition'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> The problem is more the node name than the index entry.  The node title,
> within the node, is `Defining Customization Variables', which is much
> better.
>
> I imagine that the node name was picked because the node is a subnode of
> node `Customization', but that is not a good enough reason.
> `Info-goto-node' handles the nodes of a manual in a flat way.
>
> A node named `Variable Definitions' should cover all of defvar,
> defconst, and defcustom.  Likewise, an index entry named `variable
> definition'.  IOW, someone hunting for info about variable definitions
> should be able to get to general info about all kinds of variable
> definitions.

I'm not quite sure what you want to have done here.  As you say, that
node isn't really about "variable definitions", so it seems like a very
good thing that "variable definition" doesn't take you there, but to
"12.5 Defining Global Variables", which makes more sense.

Or is this something that has been fixed in the intervening years?

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

bug#21594: 25.0.50; (elisp): node `Variable Definitions' is not reachable by `i variable definition'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Thu, 01 Aug 2019 21:07:48 +0200
> Cc: 21594@debbugs.gnu.org
> 
> > The problem is more the node name than the index entry.  The node title,
> > within the node, is `Defining Customization Variables', which is much
> > better.
> >
> > I imagine that the node name was picked because the node is a subnode of
> > node `Customization', but that is not a good enough reason.
> > `Info-goto-node' handles the nodes of a manual in a flat way.
> >
> > A node named `Variable Definitions' should cover all of defvar,
> > defconst, and defcustom.  Likewise, an index entry named `variable
> > definition'.  IOW, someone hunting for info about variable definitions
> > should be able to get to general info about all kinds of variable
> > definitions.
> 
> I'm not quite sure what you want to have done here.

I think this report simply reads too much into the name of a node.  A
node's name is a label, and needs to satisfy several requirements, so
it isn't always as accurate as the section name.

I don't think we need to do anything about this issue.  There's no
real problem here.  There are several index entries leading to this
node that readers could use, and the assumption that someone might
look up this node by its name, or be surprised that only defcustoms
are described there, is misguided, IMO.

bug#21594: 25.0.50; (elisp): node `Variable Definitions' is not reachable by `i variable definition'

[Drew Adams]

> I'm not quite sure what you want to have done here.  As you say, that
> node isn't really about "variable definitions", so it seems like a very
> good thing that "variable definition" doesn't take you there, but to
> "12.5 Defining Global Variables", which makes more sense.

Index entry `variable definition' takes you to 12.5,
and it did previously as well.  That's good, as far
as it goes.

The point of the bug report is this:

Node `Variable Definitions' is misnamed.  It is
only about _option_ definitions.  It does not
correspond to index entry `variable definitions'
(which is a good thing).

The title in the node itself is better: `Defining
Customization Variables'.  Please consider making
a change like that for the node itself (but see
below, for a node name that's arguably better).

(Someone looking for variable definitions, i.e.,
defining variables, and who might, therefore, use
index entry `variable definitions', will not find
anything about user options (`defcustom').

That's unfortunate perhaps, but there's no way
around that if we want a book (a tree, not a graph),
and we want the `defcustom' info to be where it is
now, which makes sense.

At least a user will find a link in node `Defining
Variables', to go to node `Variable Definitions'
for info about `defcustom'.)

The requested change is to the node name of
`Variable Definitions'.  Consider changing it to
`Defining User Options' or `Defining Customization
Variables'.

(But we don't really call them by the latter name.
When we use "variable" instead of "option" for
them we usually say "custom variable" or
"customizable variable".)

bug#21594: 25.0.50; (elisp): node `Variable Definitions' is not reachable by `i variable definition'

[Drew Adams]

> A node's name is a label, and needs to satisfy
> several requirements, so it isn't always as
> accurate as the section name.

True enough.  And one of those requirements is
to be able to use `g' to get to it.  A node's
name is something that users see and use.  It's
not just an internal label.

> the assumption that someone might look up this
> node by its name, or be surprised that only
> defcustoms are described there, is misguided, IMO.

No one made such an assumption, if by "look up"
you mean only `i'.

The node name is important, and in this case
it's not good.

Use `i' and you get to the right node for
`variable definition'.  No problem there.

Use `g' with completion and you get to the
wrong node for the same input.

And you might use substring or multiple-pattern
completion, with input like `var' and `def',
and the result of completion will be `Variable 
Definitions', which you will naturally think
takes you to a node about that.

Completion shows you all matches for your input.
Scanning the candidates quickly is another way
to get to a node.  It's not about `g' instead
of `i'.  It's that `g' is also useful, and node
names should be helpful, not misleading.

bug#21594: 25.0.50; (elisp): node `Variable Definitions' is not reachable by `i variable definition'

[Eli Zaretskii]

> Date: Thu, 1 Aug 2019 13:07:20 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: drew.adams@oracle.com, 21594@debbugs.gnu.org
> 
> > the assumption that someone might look up this
> > node by its name, or be surprised that only
> > defcustoms are described there, is misguided, IMO.
> 
> No one made such an assumption, if by "look up"
> you mean only `i'.

But you just did:

> Use `i' and you get to the right node for
> `variable definition'.  No problem there.
> 
> Use `g' with completion and you get to the
> wrong node for the same input.

My point is exactly that this is a wrong analogy.  When one uses 'g',
one needs to know the node's name in advance, not use that name as a
means for searching for some specific subject.  The latter is done
via 'i'.

> It's that `g' is also useful, and node names should be helpful, not
> misleading.

They are, but by definition much less so than 'i'.

And let's please stop this discussion here by agreeing to disagree,
OK?

bug#21594: 25.0.50; (elisp): node `Variable Definitions' is not reachable by `i variable definition'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> And let's please stop this discussion here by agreeing to disagree,
> OK?

Doesn't sound to me, either, that there's anything to fix here, so I'm
closing this bug report.

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

bug#21594: 25.0.50; (elisp): node `Variable Definitions' is not reachable by `i variable definition'

[Drew Adams]

> > Use `g' with completion and you get to the
> > wrong node for the same input.
> 
> My point is exactly that this is a wrong analogy.  When one uses 'g',
> one needs to know the node's name in advance, not use that name as a
> means for searching for some specific subject.  The latter is done
> via 'i'.

No, it is not either-or.

`g' - especially given better completion,
e.g. substring completion - is a useful way
to jump to a node.  Especially for a node
you might know exists, but whose exact name
you might not recall.

You do _not_ "need to know the node's name
in advance".

Just as you don't need to know the exact
name of a function or variable when you use
apropos commands.  When you type some input,
`g' completion shows you node-name matches.

Let's say you're quite familiar with node
`Some Terms'.  You remember that it's about
terms and terminology.  You might even
recall that the node name involves "term".

`i term' won't get you there.  In the
Index there are many matches for "term"
(24 with substring matching, 20 with
prefix matching).  And none of those
entries take you to node `Some Terms'.

(You'll find `Some Terms' listed in the
Index, but it's not an index entry.  It's
listed only as the node name for entry
`typographic conventions'.)

But `g term' will get you there (if you
have substring completion) - instantly.

That's just one example.  And it shouldn't
be necessary to provide it.  It should be
obvious that matching node names as a way
to get to nodes can be handy.

(And the lesson of that example, for this
bug, is not to suggest that we should have
an index entry that includes "term" in this
sense of the word.  Whether that might help
is irrelevant here.)

The point is that `g' is also a way to get
around, and it does not require that you
know an exact node name.

`i' is what it is.  It remains one of the
best ways to locate something.  It's not
the only way, and it's not invariably the
best way. Other ways include Isearch and
`g'.  A hammer is a great tool, but it's
not the only one.

> > It's that `g' is also useful, and node
> > names should be helpful, not misleading.
> 
> They are, but by definition much less so than 'i'.

_This_ node name is particularly misleading,
unhelpful.

This report is not for an abstract debate
about `i' versus `g'.  Defending `i' is
irrelevant here.  I agree with you about its
general utility.

This bug is about one particular node name
that's not helpful.  It's about fixing this
name, getting one that is more useful, less
misleading.

Is there a good reason not to fix this node
name?  I haven't seen any put forward, so far.

Instead of insisting on a false all-or-nothing
choice between `i' and `g', why don't we just
fix this particular node name?  Reason?

bug#21594: 25.0.50; (elisp): node `Variable Definitions' is not reachable by `i variable definition'

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

How about changing the node name to Customization Definitions
or User Option Definitions?

I suggest defining the term "user option" in the parent node,
the chapter Customization Settings.


-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#21594: 25.0.50; (elisp): node `Variable Definitions' is not reachable by `i variable definition'

[Drew Adams]

> How about changing the node name to Customization Definitions
> or User Option Definitions?

Yes, thank you.  How about it?

There are several such possibilities.  Both
of those you suggest are fine.

I suggested also `Defining User Options' and
`Defining Customization Variables' (the current
title, inside the node).  (But if we do go with
"option" then the title too should reflect that.)

Nearly anything suggesting defcustom, option
definition, or custom variable definition.

The main thing is to avoid `Variable Definitions',
which invites confusion.

> I suggest defining the term "user option" in the parent node,
> the chapter Customization Settings.

I guess you mean instead of in node `Variable
Definitions', where it's defined now.

That too makes sense, as there we currently
introduce the term "customization items" and
we speak of customizing variables and faces,
without saying that the former are options.
(But the menu refers to user options.)

bug#21594: 25.0.50; (elisp): node `Variable Definitions' is not reachable by `i variable definition'

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > I suggest defining the term "user option" in the parent node,
  > > the chapter Customization Settings.

  > I guess you mean instead of in node `Variable
  > Definitions', where it's defined now.

Or perhaps in both nodes.  Whatever seems better.

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)