bug#29400: 26.0; Add Elisp manual index entry for `defvar' to node `Compiler Errors'

bug#29400: 26.0; Add Elisp manual index entry for `defvar' to node `Compiler Errors'

[Drew Adams]

Node `Compiler Errors' seems to be the only place in the Elisp manual
where we tell users that you can use a vacuous `defvar' (no value) to
suppress a byte-compiler warning about it not being defined.

But this node has no index entry - at least none that has the word
`defvar' in it.  Please add such an entry.

And please either add the same info (about this use of a vacuous
`defvar') to node `Defining Variables' or add a cross-reference from
that node to node `Compiler Errors'.

As it is now, it is not so easy to find this info.



In GNU Emacs 26.0.90 (build 3, x86_64-w64-mingw32)
 of 2017-10-13
Repository revision: 906224eba147bdfc0514090064e8e8f53160f1d4
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#29400: 26.0; Add Elisp manual index entry for `defvar' to node `Compiler Errors'

[Eli Zaretskii]

> Date: Wed, 22 Nov 2017 08:50:33 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> Node `Compiler Errors' seems to be the only place in the Elisp manual
> where we tell users that you can use a vacuous `defvar' (no value) to
> suppress a byte-compiler warning about it not being defined.
> 
> But this node has no index entry - at least none that has the word
> `defvar' in it.  Please add such an entry.

I added some index entries, but I don't understand why you wanted an
index entry with "defvar" in it.  A reader who will look for "defvar"
when they want to find ways of suppressing compiler warnings already
knows that defvar is used for that purpose, so why would they use such
a topic at Info-index's prompt?  That's the opposite of what good
index entries should provide -- they should _lead_ to defvar's
description as the way to suppress warnings when the reader thinks of
"warnings" or some such.

> And please either add the same info (about this use of a vacuous
> `defvar') to node `Defining Variables' or add a cross-reference from
> that node to node `Compiler Errors'.

Done.

bug#29400: 26.0; Add Elisp manual index entry for `defvar' to node `Compiler Errors'

[Drew Adams]

> > Node `Compiler Errors' seems to be the only place in the Elisp manual
> > where we tell users that you can use a vacuous `defvar' (no value) to
> > suppress a byte-compiler warning about it not being defined.
> >
> > But this node has no index entry - at least none that has the word
> > `defvar' in it.  Please add such an entry.
> 
> I added some index entries, 

Thank you.

> but I don't understand why you wanted an
> index entry with "defvar" in it.  A reader who will look for "defvar"
> when they want to find ways of suppressing compiler warnings already
> knows that defvar is used for that purpose, so why would they use such
> a topic at Info-index's prompt?

To find exactly what the manual says about it.

You might know that some Java method is what you want,
but you might want to consult the Java doc again for
details.  Just because you know something about
something that is in the manual doesn't mean that you
never want to check the manual about it again.

Or you might want to get to the doc to be able to point
someone else to it (URL or manual+node-name).  I often
point users to sections of the manual.  And in this
case looking up `defvar' in the index is the first
thing I would do.

Imagining that someone who knows that `defvar' can be
used to suppress some compiler warnings should never
want or need to find where this is covered in the
manual by checking `defvar' in the index suggests a
narrow understanding of indexing - which is not
normally what you show.

> That's the opposite of what good
> index entries should provide -- they should _lead_ to defvar's
> description as the way to suppress warnings when the reader thinks of
> "warnings" or some such.

Looking in the index for `warning' is not the only
reasonable way to use an index for this - see above.

> > And please either add the same info (about this use of a vacuous
> > `defvar') to node `Defining Variables' or add a cross-reference from
> > that node to node `Compiler Errors'.
> 
> Done.

Thanks.

bug#29400: 26.0; Add Elisp manual index entry for `defvar' to node `Compiler Errors'

[Eli Zaretskii]

> Date: Fri, 24 Nov 2017 08:54:39 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 29400-done@debbugs.gnu.org
> 
> > but I don't understand why you wanted an
> > index entry with "defvar" in it.  A reader who will look for "defvar"
> > when they want to find ways of suppressing compiler warnings already
> > knows that defvar is used for that purpose, so why would they use such
> > a topic at Info-index's prompt?
> 
> To find exactly what the manual says about it.

But defvar is described elsewhere, and index entries about it should
lead there.  And after my changes, the description there mentions its
use for suppressing warnings, so I don't think an index entry leading
elsewhere is needed.

> Looking in the index for `warning' is not the only
> reasonable way to use an index for this - see above.

Feel free to suggest other topics, but "defvar" is definitely not one
of them.

bug#29400: 26.0; Add Elisp manual index entry for `defvar' to node `Compiler Errors'

[Drew Adams]

> > > but I don't understand why you wanted an
> > > index entry with "defvar" in it.  A reader who will look for "defvar"
> > > when they want to find ways of suppressing compiler warnings already
> > > knows that defvar is used for that purpose, so why would they use
> > > such a topic at Info-index's prompt?
> >
> > To find exactly what the manual says about it.
> 
> But defvar is described elsewhere, and index entries about it should
> lead there.  And after my changes, the description there mentions its
> use for suppressing warnings, so I don't think an index entry leading
> elsewhere is needed.

That was the point of the bug report.  You have added
mention of supressing warnings to the node that is
indexed by `defvar', which responds to the report.
(And hopefully you will also have added there a link
to the more complete coverage of compiler warnings.)

> > Looking in the index for `warning' is not the only
> > reasonable way to use an index for this - see above.
> 
> Feel free to suggest other topics, but "defvar" is
> definitely not one of them.

You just got through admitting that it is one of them.
You corrected, you say, the node that index-entry
`defvar' points to, by adding info there about
suppressing warnings (and presumably linking to the
node that deals more generally with such warnings and
their suppression).