[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#19628: 25.0.50; doc of button functions
From: |
Drew Adams |
Subject: |
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.