(Pop-Up Menus): Correct and clarify description of `x-popup-menu'.

(Dialog Boxes): Clarify description of `x-popup-dialog'.

1 files changed, 22 insertions, 13 deletions

diff --git a/lispref/frames.texi b/lispref/frames.texi
index 712f05df597..d56c071ad1e 100644
--- a/lispref/frames.texi
+++ b/lispref/frames.texi
@@ -1360,8 +1360,9 @@ This function displays a pop-up menu and returns an indication of
 what selection the user makes.
 
 The argument @var{position} specifies where on the screen to put the
-menu.  It can be either a mouse button event (which says to put the menu
-where the user actuated the button) or a list of this form:
+top left corner of the menu.  It can be either a mouse button event
+(which says to put the menu where the user actuated the button) or a
+list of this form:
 
 @example
 ((@var{xoffset} @var{yoffset}) @var{window})
@@ -1369,7 +1370,8 @@ where the user actuated the button) or a list of this form:
 
 @noindent
 where @var{xoffset} and @var{yoffset} are coordinates, measured in
-pixels, counting from the top left corner of @var{window}'s frame.
+pixels, counting from the top left corner of @var{window}.  @var{window}
+may be a window or a frame.
 
 If @var{position} is @code{t}, it means to use the current mouse
 position.  If @var{position} is @code{nil}, it means to precompute the
@@ -1377,8 +1379,13 @@ key binding equivalents for the keymaps specified in @var{menu},
 without actually displaying or popping up the menu.
 
 The argument @var{menu} says what to display in the menu.  It can be a
-keymap or a list of keymaps (@pxref{Menu Keymaps}).  Alternatively, it
-can have the following form:
+keymap or a list of keymaps (@pxref{Menu Keymaps}).  In this case, the
+return value is the list of events corresponding to the user's choice.
+(This list has more than one element if the choice occurred in a
+submenu.)  Note that @code{x-popup-menu} does not actually execute the
+command bound to that sequence of events.
+
+Alternatively, @var{menu} can have the following form:
 
 @example
 (@var{title} @var{pane1} @var{pane2}...)
@@ -1388,11 +1395,13 @@ can have the following form:
 where each pane is a list of form
 
 @example
-(@var{title} (@var{line} . @var{item})...)
+(@var{title} @var{item1} @var{item2}...)
 @end example
 
-Each @var{line} should be a string, and each @var{item} should be the
-value to return if that @var{line} is chosen.
+Each item should normally be a cons cell @code{(@var{line} . @var{value})},
+where @var{line} is a string, and @var{value} is the value to return if
+that @var{line} is chosen.  An item can also be a string; this makes a
+non-selectable line in the menu.
 @end defun
 
   @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
@@ -1443,9 +1452,9 @@ which looks like the list that specifies a single pane for
 
 The return value is @var{value} from the chosen alternative.
 
-An element of the list may be just a string instead of a cons cell
-@code{(@var{string} . @var{value})}.  That makes a box that cannot
-be selected.
+As for @code{x-popup-menu}, an element of the list may be just a
+string instead of a cons cell @code{(@var{string} . @var{value})}.
+That makes a box that cannot be selected.
 
 If @code{nil} appears in the list, it separates the left-hand items from
 the right-hand items; items that precede the @code{nil} appear on the
@@ -1455,8 +1464,8 @@ items appear on each side.
 
 Dialog boxes always appear in the center of a frame; the argument
 @var{position} specifies which frame.  The possible values are as in
-@code{x-popup-menu}, but the precise coordinates don't matter; only the
-frame matters.
+@code{x-popup-menu}, but the precise coordinates or the individual
+window don't matter; only the frame matters.
 
 In some configurations, Emacs cannot display a real dialog box; so
 instead it displays the same items in a pop-up menu in the center of the