GNU bug report logs - #19628
25.0.50; doc of button functions

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 19628 in the body.
You can then email your comments to 19628 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.50; doc of button functions
Date: Mon, 19 Jan 2015 08:20:52 -0800 (PST)

The doc of `make-button', `insert-button', and `insert-text-button' just
mentions "a sequence of PROPERTY VALUE pairs, specifying properties to
add to the button", without saying anything about the text properties
that are special for these functions.  This is true for both the doc
strings and the Elisp manual (node `Making Buttons').

Some text properties, such as `face' and `follow-link' are common, used
generally, and are explained elsewhere.  But others, such as `action',
seem to be special to the button code and these functions.  So they
should be mentioned in this doc.

Property `action' is mentioned for function `button-activate'
(e.g. nodes `Button Properties', `Manipulating Buttons', and `Button
Buffer Commands').  But it and any other properties specific to the
button functions should be called out where we speak of such properties.
Or else such doc should refer to some location where we do specify such
properties.

What's more, the doc strings of `push-button' and `button-activate' need
to mention property `action', just as the Elisp doc for them does.  It
is not sufficient for the doc strings to simply refer to the  "normal
action" of the button, without saying what that means.


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm <at> gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

Message #8 received at 19628 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 19628 <at> debbugs.gnu.org
Subject: Re: bug#19628: 25.0.50; doc of button functions
Date: Tue, 20 Jan 2015 20:17:04 +0200

> Date: Mon, 19 Jan 2015 08:20:52 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> The doc of `make-button', `insert-button', and `insert-text-button' just
> mentions "a sequence of PROPERTY VALUE pairs, specifying properties to
> add to the button", without saying anything about the text properties
> that are special for these functions.  This is true for both the doc
> strings and the Elisp manual (node `Making Buttons').

The node "Making Buttons" in the ELisp manual has a cross-reference to
"Button Properties", where all the properties are described.

> Property `action' is mentioned for function `button-activate'
> (e.g. nodes `Button Properties', `Manipulating Buttons', and `Button
> Buffer Commands').  But it and any other properties specific to the
> button functions should be called out where we speak of such properties.
> Or else such doc should refer to some location where we do specify such
> properties.

Sorry, I don't understand what you find missing in the manual.  Where
the ELisp manual talks about PROPERTY VALUE pairs it immediately
refers to "Button Properties", where you find the details.  What else
is needed in the manual?

> What's more, the doc strings of `push-button' and `button-activate' need
> to mention property `action', just as the Elisp doc for them does.  It
> is not sufficient for the doc strings to simply refer to the  "normal
> action" of the button, without saying what that means.

button-activate already mentioned the property; I fixed the doc string
of push-button.

Message #11 received at 19628 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 19628 <at> debbugs.gnu.org
Subject: RE: bug#19628: 25.0.50; doc of button functions
Date: Tue, 20 Jan 2015 10:51:20 -0800 (PST)

> > The doc of `make-button', `insert-button', and `insert-text-button' just
> > mentions "a sequence of PROPERTY VALUE pairs, specifying properties to
> > add to the button", without saying anything about the text properties
> > that are special for these functions.  This is true for both the doc
> > strings and the Elisp manual (node `Making Buttons').
> 
> The node "Making Buttons" in the ELisp manual has a cross-reference to
> "Button Properties", where all the properties are described.

OK, scratch the part about "true for both the doc strings and the Elisp
manual (node `Making Buttons')".  I somehow missed that xref.

The problem exists for the doc strings, however.

> > Property `action' is mentioned for function `button-activate'
> > (e.g. nodes `Button Properties', `Manipulating Buttons', and `Button
> > Buffer Commands').  But it and any other properties specific to the
> > button functions should be called out where we speak of such properties.
> > Or else such doc should refer to some location where we do specify such
> > properties.
> 
> Sorry, I don't understand what you find missing in the manual.  Where
> the ELisp manual talks about PROPERTY VALUE pairs it immediately
> refers to "Button Properties", where you find the details.  What else
> is needed in the manual?

As I said, in `Manipulating Buttons', for example, the description of
`button-activate' refers to "BUTTON's `action' property".  That property
is not explained there, so there should be a cross-ref from there to the
place where it is described: `Button Properties'.

> > What's more, the doc strings of `push-button' and `button-activate' need
> > to mention property `action', just as the Elisp doc for them does.  It
> > is not sufficient for the doc strings to simply refer to the  "normal
> > action" of the button, without saying what that means.
> 
> button-activate already mentioned the property; I fixed the doc string
> of push-button.

Thanks.

Message #16 received at 19628-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 19628-done <at> debbugs.gnu.org
Subject: Re: bug#19628: 25.0.50; doc of button functions
Date: Tue, 20 Jan 2015 21:23:26 +0200

> Date: Tue, 20 Jan 2015 10:51:20 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 19628 <at> debbugs.gnu.org
> 
> As I said, in `Manipulating Buttons', for example, the description of
> `button-activate' refers to "BUTTON's `action' property".  That property
> is not explained there, so there should be a cross-ref from there to the
> place where it is described: `Button Properties'.

OK, I added a few words about 'action' there.  (Having a
cross-reference just to save a sentence or two didn't sound right.)

Message #19 received at 19628-done <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 19628-done <at> debbugs.gnu.org
Subject: RE: bug#19628: 25.0.50; doc of button functions
Date: Tue, 20 Jan 2015 11:29:14 -0800 (PST)

> OK, I added a few words about 'action' there.  (Having a
> cross-reference just to save a sentence or two didn't sound right.)

Muchas gracias.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.