bug#8119: 24.0.50; `mark-active' needs its doc string

bug#8119: 24.0.50; `mark-active' needs its doc string

[Drew Adams]

Emacs prior to 24, since Day One:
 
"Non-nil means the mark and region are currently active in this buffer."
 
Emacs 24:
"Not documented as a variable."
 
Bad Emacs.
 
 
In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-02-14 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'
 

bug#8119: 24.0.50; `mark-active' needs its doc string

[Glenn Morris]

retitle 8119 buggy 2011-02-14 trunk build on MS Windows
stop

> Emacs 24:
> "Not documented as a variable."

s/Emacs 24/current trunk/

Anyway, buggy build. 

Current trunk on GNU/Linux:
    
    mark-active is a variable defined in `C source code'.
    Its value is nil
    Local in buffer *scratch*; global value is nil
    
      Automatically becomes buffer-local when set in any fashion.
    
    Documentation:
    Non-nil means the mark and region are currently active in this buffer.

bug#8119: 24.0.50; `mark-active' needs its doc string

[Drew Adams]

> From: Glenn Morris Sent: Friday, February 25, 2011 2:39 PM
> retitle 8119 buggy 2011-02-14 trunk build on MS Windows
> stop
> 
> > Emacs 24:
> > "Not documented as a variable."
> 
> s/Emacs 24/current trunk/

OK.

> Anyway, buggy build.

OK.

> Current trunk on GNU/Linux:
>     mark-active is a variable defined in `C source code'.
>     Its value is nil
>     Local in buffer *scratch*; global value is nil
>       Automatically becomes buffer-local when set in any fashion.
>     Documentation:
>     Non-nil means the mark and region are currently active in 
>     this buffer.

(You've written "current trunk" in two contradictory ways, BTW.
Which is it - not documented or documented?)


If this is a buggy build, then file a bug report saying to that effect.  Or add
that statement to this bug's description (body): "Anyway...".  No problem.

But please do not change the title of this bug.  Even if you are convinced that
the _cause_ of the symptom I reported is a buggy build, the bug-report title
should not be changed.

If you want, create a new bug with your "buggy" title, to refer to a problem
that you discovered.  And then, if you are convinced that this bug is related to
the other, merge the two.  That way, if the merge is mistaken the two can be
dissociated.  And their descriptions/titles anyway remain distinct.

There is no reason to retitle a bug report.  The original title is the OP's way
of describing the problem.  It need not be a description of the underlying cause
of the problem.  It need not even be accurate/correct.  There is never any
reason to simply wipe out that original description, replacing it with one you
think is closer to the mark.

This is not the way bugs are handled - in any bug tracking system I've seen.

bug#8119: 24.0.50; `mark-active' needs its doc string

[Glenn Morris]

"Drew Adams" wrote:

> If this is a buggy build, then file a bug report saying to that
> effect. Or add that statement to this bug's description (body):
> "Anyway...". No problem.
>
> But please do not change the title of this bug. Even if you are
> convinced that the _cause_ of the symptom I reported is a buggy build,
> the bug-report title should not be changed.
>
> If you want, create a new bug with your "buggy" title, to refer to a
> problem that you discovered. And then, if you are convinced that this
> bug is related to the other, merge the two. That way, if the merge is
> mistaken the two can be dissociated. And their descriptions/titles
> anyway remain distinct.
>
> There is no reason to retitle a bug report. The original title is the
> OP's way of describing the problem. It need not be a description of
> the underlying cause of the problem. It need not even be
> accurate/correct. There is never any reason to simply wipe out that
> original description, replacing it with one you think is closer to the
> mark.
>
> This is not the way bugs are handled - in any bug tracking system I've seen.


Well. That certainly is an opinion. I disagree.

IMO the title is a brief phrase that best summarizes what the real issue
is. This is for the convenience of developers in locating bugs to work
on, and for other users in locating reports related to problems they may
be having. The original title is not always the best summary of the real
problem, which is why the retitle command exists.

But rest assured I won't interfere with any more of your reports, at all.

bug#8119: 24.0.50; `mark-active' needs its doc string

[Drew Adams]

> > This is not the way bugs are handled - in any bug tracking 
> > system I've seen.
> 
> Well. That certainly is an opinion. I disagree.

OK, two opinions.  Do you know of a company where bug reports are retitled by
developers along the way, based on their current understanding of the underlying
problem?  Or are ever retitled, by developers or by anyone else?  I don't.  I
cannot imagine how a customer would look upon such a practice (wrt
customer-facing bugs).

Admittedly, the real identifier is the bug number.  And there is metadata for
categorizing bugs, which also helps to identify them.  But customers and others
often search or sort using titles and terms in titles.  User bug reports are
often expressed (including titled) in user terms, whereas the root problem is
often expressed in internal, implementation terms.

In my experience, the improved understanding that developers add to a bug report
gets added to the body (thread) or by recategorizing (metadata, merging etc.).
It does not happen in general by retitling.  What I see is that both the bug
number and the title remain as unchanged identifiers.  People might later refer
to a different bug number because of a merge, but the original number is not
changed - and similarly for titles.

So yes, my reply represents an opinion, but one that reflects pretty widespread
practice AFAICT.

> IMO the title is a brief phrase that best summarizes what the 
> real issue is.  This is for the convenience of developers in
> locating bugs to work on, and for other users in locating reports
> related to problems they may be having. The original title is not
> always the best summary of the real problem, which is why the
> retitle command exists.

The original title is not always the best summary of the real problem - agreed
100%.  But that's not the role of the title.  The title summarizes the OP's view
of the problem as originally reported - for better or worse.  And later
retitlings are not necessarily the best summary of the real problem either.

> But rest assured I won't interfere with any more of your 
> reports, at all.

Do what you feel you need to do, Glenn, but it's not about you, or me.  My reply
was an attempt to improve the process - just as yours was, no doubt.  As you
said, we have different opinions; that's all.  I think retitling for such a case
hurts more than helps; you don't agree.

That's not a reason to sulk or go off in a huff.  I appreciate your hard work,
as does everyone else.  My point was only about retitling - and it was not only
about bugs that I report.  It certainly was not personal.  No one is asking that
you take your marbles and go home.  I hope you will reconsider about helping on
bugs I submit, whether or not you reconsider wrt retitling bugs.

Think of my argument as a question, if you like: What is the policy wrt
retitling?  I gave an argument against it (in general) - I think it gets in the
way more than it helps.  Your reply gives an argument in support of it.  But
what is the policy?  When is it considered appropriate to use the `retitle'
command?

bug#8119: 24.0.50; `mark-active' needs its doc string

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Sat, 26 Feb 2011 06:18:55 -0800
> Cc: 
> 
> > But rest assured I won't interfere with any more of your 
> > reports, at all.
> 
> Think of my argument as a question, if you like: What is the policy wrt
> retitling?

I think Glenn's arguments are entirely valid.  If there needs to be
policy, Glenn is the first one we should ask, because he does most of
the mundane work with the bug-tracker.

FWIW, I see no harm at all in retitling, and I do see a certain value
in having the title express the essence of the bug report.

bug#8119: 24.0.50; `mark-active' needs its doc string

[Drew Adams]

> > Think of my argument as a question, if you like:
> > What is the policy wrt retitling?
> 
> I think Glenn's arguments are entirely valid.

No one suggested otherwise.

> If there needs to be policy, Glenn is the first one we
> should ask, because he does most of the mundane work with
> the bug-tracker.

Fine.  But bug tracking is for users as well as developers.
Please keep that in mind when setting the policy.
It is not only about who does the bug-tracking mundane work.
Or at least it should not be (IMHO).

> FWIW, I see no harm at all in retitling, and I do see a certain
> value in having the title express the essence of the bug report.

And do you see such a policy as the general practice elsewhere?  What others do
elsewhere need not limit or guide us, but it can sometimes help to look over the
fence.

bug#8119: 24.0.50; `mark-active' needs its doc string

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <rgm@gnu.org>, <8119@debbugs.gnu.org>
> Date: Sat, 26 Feb 2011 07:27:20 -0800
> 
> > FWIW, I see no harm at all in retitling, and I do see a certain
> > value in having the title express the essence of the bug report.
> 
> And do you see such a policy as the general practice elsewhere?

On my daytime job, I frequently retitle bug reports, because many of
my co-workers don't know how to express themselves in English too
well.  I have yet to see anyone complain about that; all of the
correspondence about bugs quotes their numbers anyway.

bug#8119: 24.0.50; `mark-active' needs its doc string

[Drew Adams]

> > > FWIW, I see no harm at all in retitling, and I do see a certain
> > > value in having the title express the essence of the bug report.
> > 
> > And do you see such a policy as the general practice elsewhere?
> 
> On my daytime job, I frequently retitle bug reports, because many of
> my co-workers don't know how to express themselves in English too
> well.

OK, good to know.

FWIW, my experience has been the opposite; bugs are not retitled.
They often get clarified, corrected, reclassified, and merged, but not retitled
AFAICT.

It thus happens that one sees some bug titles that bear little apparent relation
to the ultimate diagnosis (not to mention diagnoses along the way).  The titles
remain as originally posted, whether posted internally or by a customer.

> I have yet to see anyone complain about that; all of the
> correspondence about bugs quotes their numbers anyway.

Yes, as I said, the bug number is the primary and unique identifier, and as such
it nearly always appears in correspondence.

But as Glen pointed out, titles can be used for searching, and replacing a user
name of a problem by a developer name for it doesn't necessarily help users
search for it.  It might help some users, but it might well disadvantage others,
including the OP.

bug#8119: 24.0.50; `mark-active' needs its doc string

[Eli Zaretskii]

> Date: Fri, 25 Feb 2011 17:38:32 -0500
> From: Glenn Morris <rgm@gnu.org>
> Cc: 
> 
> retitle 8119 buggy 2011-02-14 trunk build on MS Windows
> stop
> 
> > Emacs 24:
> > "Not documented as a variable."
> 
> s/Emacs 24/current trunk/
> 
> Anyway, buggy build. 
> 
> Current trunk on GNU/Linux:
>     
>     mark-active is a variable defined in `C source code'.
>     Its value is nil
>     Local in buffer *scratch*; global value is nil
>     
>       Automatically becomes buffer-local when set in any fashion.
>     
>     Documentation:
>     Non-nil means the mark and region are currently active in this buffer.

Confirmed, I see the same as Glenn with yesterday's build of the trunk
on Windows.

bug#8119: 24.0.50; `mark-active' needs its doc string

[Andreas Schwab]

Fixed here:

2011-02-21  Ben Key  <bkey76@gmail.com>  (tiny change)

	* make-docfile.c (scan_c_file): Adapt DEFVAR_PER_BUFFER case to
	the new BVAR macro.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."