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

From: Drew Adams <[email-masked]>
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.