Subject: Re: bug#19628: 25.0.50; doc of button functions

From: Eli Zaretskii <[email-masked]>
Date: Tue, 20 Jan 2015 20:17:04 +0200

> Date: Mon, 19 Jan 2015 08:20:52 -0800 (PST)
> From: Drew Adams <[email-masked]>
> 
> 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.