bug#22314: 25.1.50; Document variable `deactivate-mark' in Elisp manual

bug#22314: 25.1.50; Document variable `deactivate-mark' in Elisp manual

[Drew Adams]

Subject line says it all.  Only the function of the same name is
documented.

In GNU Emacs 25.1.50.1 (i686-pc-mingw32)
 of 2015-12-10
Repository revision: 6148555ee5a3d0139ae517803718b3e0357933c7
Windowing system distributor 'Microsoft Corp.', version 6.1.7601
Configured using:
 'configure --prefix=/c/Devel/emacs/snapshot/trunk --enable-checking=yes
 --enable-check-lisp-object-type --without-compress-install 'CFLAGS=-Og
 -ggdb3' LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#22314: 25.1.50; Document variable `deactivate-mark' in Elisp manual

[Eli Zaretskii]

> Date: Tue, 5 Jan 2016 10:10:00 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> Subject line says it all.

Any special reasons why?  We don't necessarily document every variable
and every function, only those that are important to Lisp programmers.

bug#22314: 25.1.50; Document variable `deactivate-mark' in Elisp manual

[Drew Adams]

> Any special reasons why?  We don't necessarily document every variable
> and every function, only those that are important to Lisp programmers.

A common user question is why the region gets deactivated after the
user's command.  The common way to prevent this is to do this at the
end of the command:

  (setq deactivate-mark nil)

Example user question:
http://emacs.stackexchange.com/q/19275/105

bug#22314: 25.1.50; Document variable `deactivate-mark' in Elisp manual

[Drew Adams]

My bad.  It is already documented.  I didn't notice it because
it is not one of the index entries for `deactivate-mark'.
I think it should be.

bug#22314: 25.1.50; Document variable `deactivate-mark' in Elisp manual

[Nicolas Richard]

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

> My bad.  It is already documented.  I didn't notice it because
> it is not one of the index entries for `deactivate-mark'.
> I think it should be.

In a build from mid-december, doing
    emacs -Q --eval '(info "elisp")'
then hitting 'i deactivate-mark RET'
I'm left at the description of deactivate-mark as a variable. Hitting
',' (as suggested in echo area) brings me to the description of
deactivate-mark as a function, then the description of
deactivate-mark-hook.

-- 
Nicolas Richard

bug#22314: 25.1.50; Document variable `deactivate-mark' in Elisp manual

[Eli Zaretskii]

> Date: Tue, 5 Jan 2016 13:08:22 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 22314@debbugs.gnu.org
> 
> My bad.  It is already documented.  I didn't notice it because
> it is not one of the index entries for `deactivate-mark'.
> I think it should be.

They are both indexed, AFAICS.  Why did you think the variable isn't?
The descriptions appear next to each other, so a single index entry
for both seems like TRT.  Am I missing something?

bug#22314: 25.1.50; Document variable `deactivate-mark' in Elisp manual

[Drew Adams]

> > My bad.  It is already documented.  I didn't notice it because
> > it is not one of the index entries for `deactivate-mark'.
> > I think it should be.
> 
> They are both indexed, AFAICS.  Why did you think the variable
> isn't?
> The descriptions appear next to each other, so a single index entry
> for both seems like TRT.  Am I missing something?

I think you are.  At least for me, with the latest Emacs 25
snapshot I have (2015/12/10), `i deactivate-mark' shows two
index entries, and `,' bounces between them.  They are:
(1) deactivate-mark, the function, and (2) deactivate-mark-hook,
a variable.  Variable `deactivate-mark' is not one of them.

Do you really see something different?

bug#22314: 25.1.50; Document variable `deactivate-mark' in Elisp manual

[Eli Zaretskii]

> Date: Fri, 8 Jan 2016 07:00:28 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 22314@debbugs.gnu.org
> 
> > > My bad.  It is already documented.  I didn't notice it because
> > > it is not one of the index entries for `deactivate-mark'.
> > > I think it should be.
> > 
> > They are both indexed, AFAICS.  Why did you think the variable
> > isn't?
> > The descriptions appear next to each other, so a single index entry
> > for both seems like TRT.  Am I missing something?
> 
> I think you are.  At least for me, with the latest Emacs 25
> snapshot I have (2015/12/10), `i deactivate-mark' shows two
> index entries, and `,' bounces between them.  They are:
> (1) deactivate-mark, the function, and (2) deactivate-mark-hook,
> a variable.  Variable `deactivate-mark' is not one of them.
> 
> Do you really see something different?

I see the same, but I don't understand why that is a problem.  The
function and the variable are described one after the other, and 'i'
puts you on the first of them with the second clearly visible below.
How is that a problem?  And how is it worse than having 2 identical
index entries instead, which point each one to a place several lines
apart?

bug#22314: 25.1.50; Document variable `deactivate-mark' in Elisp manual

[Drew Adams]

> > I think you are.  At least for me, with the latest Emacs 25
> > snapshot I have (2015/12/10), `i deactivate-mark' shows two
> > index entries, and `,' bounces between them.  They are:
> > (1) deactivate-mark, the function, and (2) deactivate-mark-hook,
> > a variable.  Variable `deactivate-mark' is not one of them.
> >
> > Do you really see something different?
> 
> I see the same, but I don't understand why that is a problem.  The
> function and the variable are described one after the other, and 'i'
> puts you on the first of them with the second clearly visible below.
> How is that a problem?  And how is it worse than having 2 identical
> index entries instead, which point each one to a place several lines
> apart?

It's wrong because it does not move point to the entry.  Nothing
indicates to a user that there in fact 3 entries, not 2.  Whether
you might happen to have the 3rd visible in the same window (and
you might not, depending on your window size), you might well not
notice it there - as I did not.

I would not have filed this bug report if I thought that this
was not a problem.  And as you can see from my initial report,
I in fact mistakenly thought that the variable was not even
documented, because cycling among the index entries did not
take me to it.

I don't see why you wouldn't want to add an index entry for this
variable.  But if you don't feel like it then what can I say?

If the Elisp manual had different indexes, as does the Emacs
manual, then adding it would also let a user find it in the
Variables Index.

Maybe it's not possible to index both, if there is only one
Index?  Dunno.  If you can't, you can't.  If you can (maybe two
entries, with suffixes "(variable)" and "(function)"), that's
better, IMO.

bug#22314: 25.1.50; Document variable `deactivate-mark' in Elisp manual

[Eli Zaretskii]

> Date: Fri, 8 Jan 2016 13:29:42 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 22314@debbugs.gnu.org
> 
> > I see the same, but I don't understand why that is a problem.  The
> > function and the variable are described one after the other, and 'i'
> > puts you on the first of them with the second clearly visible below.
> > How is that a problem?  And how is it worse than having 2 identical
> > index entries instead, which point each one to a place several lines
> > apart?
> 
> It's wrong because it does not move point to the entry.  Nothing
> indicates to a user that there in fact 3 entries, not 2.

The user's eyes should indicate that.  You are splitting hair.

> I would not have filed this bug report if I thought that this
> was not a problem.  And as you can see from my initial report,
> I in fact mistakenly thought that the variable was not even
> documented, because cycling among the index entries did not
> take me to it.

You should have read a bit more than a single line.

> I don't see why you wouldn't want to add an index entry for this
> variable.  But if you don't feel like it then what can I say?

THERE IS ALREADY AN INDEX ENTRY FOR IT!!!!

How many times do I need to tell you that?  Just look at the sources!

> If the Elisp manual had different indexes, as does the Emacs
> manual, then adding it would also let a user find it in the
> Variables Index.

The function is indexed as a function, the variable is indexed as a
variable.  We have @defvar for the variable, which indexes the
variable, and a @defun for the function, which indexes the function.

> Maybe it's not possible to index both, if there is only one
> Index?  Dunno.  If you can't, you can't.  If you can (maybe two
> entries, with suffixes "(variable)" and "(function)"), that's
> better, IMO.

Bug closed.

bug#22314: 25.1.50; Document variable `deactivate-mark' in Elisp manual

[Drew Adams]

> > It's wrong because it does not move point to the entry.  Nothing
> > indicates to a user that there in fact 3 entries, not 2.
> 
> The user's eyes should indicate that.  You are splitting hair.

No, the echoed message that says there are a total of 2 entries
should indicate the number of entries.  And hitting `,' should
move point to each entry in turn.

> > I would not have filed this bug report if I thought that this
> > was not a problem.  And as you can see from my initial report,
> > I in fact mistakenly thought that the variable was not even
> > documented, because cycling among the index entries did not
> > take me to it.
> 
> You should have read a bit more than a single line.

Eli, you can say "you should" all you want.  A user (I)
reported the problem.  If this is a problem for me to find
the (non-existent) index entry then it can be a problem
for others.  Ignore it if you like.

> > I don't see why you wouldn't want to add an index entry for this
> > variable.  But if you don't feel like it then what can I say?
> 
> THERE IS ALREADY AN INDEX ENTRY FOR IT!!!!
> 
> How many times do I need to tell you that?  Just look at the sources!

Why are you shouting?

Whatever you might see in the sources, what concerns me is
what a user sees - the observable behavior.  Observably the
is only one index entry for `deactivate-mark'.

Looking in the index itself shows me that there is a single
entry for `deactivate-mark'.

The echo-area message that gives the total number of
matching entries tells me that there is only one entry
for `deactivate-mark' (the total shown is 2 entries,
and the other one is for `deactivate-mark-hook').

And cycling with `,' moves only between those two entries,
never to a variable entry (that your shouting insists
exists) for `deactivate-mark'.

> > If the Elisp manual had different indexes, as does the Emacs
> > manual, then adding it would also let a user find it in the
> > Variables Index.
> 
> The function is indexed as a function, the variable is indexed as a
> variable.  We have @defvar for the variable, which indexes the
> variable, and a @defun for the function, which indexes the function.

So why is there only one entry for `deactivate-mark' in the
Index?  And why is there only one entry for it when you use
`,' to cycle among all entries?  And why does the echo message
tell you that there are only 2 entries (the ones you visit
when cycling, neither of which is for this variable)?

(I don't want to presume anything, but are you sure you
are not mistaking the existing index entry for variable
`deactivate-mark-hook' for an entry for variable
`deactivate-mark'?)

> > Maybe it's not possible to index both, if there is only one
> > Index?  Dunno.  If you can't, you can't.  If you can (maybe two
> > entries, with suffixes "(variable)" and "(function)"), that's
> > better, IMO.
> 
> Bug closed.

Feel better now?