Doc inconsistency

The documentation for `add-menu-button' starts like this: `add-menu-button' is a compiled Lisp function (add-menu-button MENU-PATH MENU-LEAF &optional BEFORE IN-MENU) Documentation: Add a menu item to some menu, creating the menu first if necessary. If the named item exists already, it is changed. MENU-PATH identifies the menu under which the new menu item should be inserted. It is a list of strings; for example, ("File") names the top-level "File" menu. ("File" "Foo") names a hypothetical submenu of "File". MENU-LEAF is a menubar leaf node. See the documentation of `current-menubar'. [...] Now, I expected the keyword "menubar leaf node" to show up in the documentation of `current-menubar'. No such luck (docs attached). Can anyone enlighten me what this MENU-LEAF means? I need to know to fix an outstanding Dired bug ... `current-menubar' is a simple built-in variable. Documentation: The current menubar. This may be buffer-local. When the menubar is changed, the function `set-menubar-dirty-flag' has to be called for the menubar to be updated on the frame. See `set-menubar' and `set-buffer-menubar'. A menubar is a list of menus and menu-items. A menu is a list of menu items, keyword-value pairs, strings, and submenus. The first element of a menu must be a string, which is the name of the menu. This is the string that will be displayed in the parent menu, if any. For toplevel menus, it is ignored. This string is not displayed in the menu itself. Menu accelerators can be indicated in the string by putting the sequence "%_" before the character corresponding to the key that will invoke the menu or menu item. Uppercase and lowercase accelerators are equivalent. The sequence "%%" is also special, and is translated into a single %. If no menu accelerator is present in the string, XEmacs will act as if the first character has been tagged as an accelerator. Immediately following the name string of the menu, various optional keyword-value pairs are permitted: currently, :filter, :active, :included, and :config. (See below.) If an element of a menu (or menubar) is a string, then that string will be presented as unselectable text. If an element of a menu is a string consisting solely of hyphens, then that item will be presented as a solid horizontal line. If an element of a menu is a string beginning with "--:", it will be presented as a line whose appearance is controlled by the rest of the text in the string. The allowed line specs are system-dependent, and currently work only under X Windows (with Lucid and Motif menubars); otherwise, a solid horizontal line is presented, as if the string were all hyphens. The possibilities are: "--:singleLine" "--:doubleLine" "--:singleDashedLine" "--:doubleDashedLine" "--:noLine" "--:shadowEtchedIn" "--:shadowEtchedOut" "--:shadowEtchedInDash" "--:shadowEtchedOutDash" "--:shadowDoubleEtchedIn" (Lucid menubars only) "--:shadowDoubleEtchedOut" (Lucid menubars only) "--:shadowDoubleEtchedInDash" (Lucid menubars only) "--:shadowDoubleEtchedOutDash" (Lucid menubars only) If an element of a menu is a list, it is treated as a submenu. The name of that submenu (the first element in the list) will be used as the name of the item representing this menu on the parent. If an element of a menubar is `nil', then it is used to represent the division between the set of menubar-items which are flushleft and those which are flushright. Otherwise, the element must be a vector, which describes a menu item. A menu item is of the following form: [ "name" callback :<keyword> <value> :<keyword> <value> ... ] The following forms are also accepted for compatibility, but deprecated: [ "name" callback <active-p> ] [ "name" callback <active-p> <suffix> ] The name is the string to display on the menu; it is filtered through the resource database, so it is possible for resources to override what string is actually displayed. Menu accelerator indicators (the sequence `%_') are also processed; see above. If the name is not a string, it will be evaluated with `eval', and the result should be a string. If the `callback' of a menu item is a symbol, then it must name a command. It will be invoked with `call-interactively'. If it is a list, then it is evaluated with `eval'. In the deprecated forms, <active-p> is equivalent to using the :active keyword, and <suffix> is equivalent to using the :suffix keyword. The possible keywords are: :active <form> The expression is evaluated just before the menu is displayed, and the menu will be selectable only if the result is non-nil. :suffix <form> The expression is evaluated just before the menu is displayed and the resulting string is appended to the displayed name, providing a convenient way of adding the name of a command's ``argument'' to the menu, like ``Kill Buffer NAME''. :keys "string" Normally, the keyboard equivalents of commands in menus are displayed when the `callback' is a symbol. This can be used to specify keys for more complex menu items. It is passed through `substitute-command-keys' first. :style <style> Specifies what kind of object this menu item is: nil A normal menu item. toggle A toggle button. radio A radio button. button A menubar button. The only difference between toggle and radio buttons is how they are displayed. But for consistency, a toggle button should be used when there is one option whose value can be turned on or off, and radio buttons should be used when there is a set of mutually exclusive options. When using a group of radio buttons, you should arrange for no more than one to be marked as selected at a time. :selected <form> Meaningful only when STYLE is `toggle', `radio' or `button'. This specifies whether the button will be in the selected or unselected state. :included <form> This can be used to control the visibility of a menu or menu item. The form is evaluated and the menu or menu item is only displayed if the result is non-nil. :config <symbol> This is an efficient shorthand for :included (memq symbol menubar-configuration) See the variable `menubar-configuration'. :filter <function> A menu filter can only be used at the beginning of a submenu description (i.e. not in a menu item itself). (Remember that most of the keywords can take evaluated expressions as well as constants.) The filter is used to incrementally create a submenu only when it is selected by the user and not every time the menubar is activated. The filter function is passed the list of menu items in the submenu and must return the modified list to be actually used. The filter MUST NOT destructively modify the list of menu items passed to it. It is called only when the menu is about to be displayed, so other menus may already be displayed. Vile and terrible things will happen if a menu filter function changes the current buffer, window, or frame. It also should not raise, lower, or iconify any frames. Basically, the filter function should have no side-effects. :key-sequence keys Used in FSF Emacs as an hint to an equivalent keybinding. Ignored by XEmacs for easymenu.el compatibility. (XEmacs computes this information automatically.) For example: ("%_File" :filter file-menu-filter ; file-menu-filter is a function that takes ; one argument (a list of menu items) and ; returns a list of menu items [ "Save %_As..." write-file t ] [ "%_Revert Buffer" revert-buffer (buffer-modified-p) ] [ "R%_ead Only" toggle-read-only :style toggle :selected buffer-read-only ] ) See menubar-items.el for many more examples. After the menubar is clicked upon, but before any menus are popped up, the functions on the `activate-menubar-hook' are invoked to make top-level changes to the menus and menubar. Note, however, that the use of menu filters (using the :filter keyword) is usually a more efficient way to dynamically alter or sensitize menus. -- Cheers =8-} Mike Friede, Völkerverständigung und überhaupt blabla