This page is about the following libraries, which together enhance the Emacs help system:
Each of these libraries provides enhancements to the standard Emacs library of the same name but without the `+’. Library help+20.el is an exception to this naming convention; it enhances standard library help.el for Emacs 20. Library help-macro+.el works for Emacs 20 and later. The other libraries work with Emacs 22 and later.
Pretty much all of the standard help commands (‘describe-face’, ‘describe-function’, ‘describe-variable’,…), as well as the new help commands described below (‘describe-keymap’,…), are enhanced by help-fns+.el (starting with Emacs version 23.2) so that the `*Help*’ window also has a link to the locations in the various manuals (Info) where the given help target is indexed.
For example, if you do ‘C-h f forward-char’, the `*Help*’ buffer has this text, where ‘manuals’ is a link:
For more information check the manuals.
If you click ‘manuals’ you get an Info buffer that is a menu of the index entries for ‘forward-char’ in all of the manuals searched. In the case of function ‘forward-char’ it has two links, one to the ElispManual, one to the EmacsManual:
* forward-char [elisp]: (elisp)Character Motion. * forward-char [emacs]: (emacs)Moving Point.
Which manuals are searched this way for index entries? You control this using user option ‘help-cross-reference-manuals’. You can have Emacs check all manuals on your system or just a specific set of manuals (or no manuals, to turn off this feature). By default, only the Emacs manual and Elisp manual are searched.
If, for example, you customize ‘help-cross-reference-manuals’ so that it searches all manuals, then the manuals link from ‘C-h f forward-char’ will give you an Info menu something like this:
* forward-char [elisp]: (elisp)Character Motion. * forward-char [emacs]: (emacs)Moving Point. * forward-char [mh-e]: (mh-e)Processing Mail Tour.
Obviously, searching the indexes of all manuals takes more time.
Option ‘help-cross-reference-manuals’ also controls whether to check for manual entries before adding the For more information check the manuals. link. By default, there is no check: the link is added even if there might not be any manual entries for the help target. This saves time. When you click the link the target is looked up in the manual indexes, in any case.
Often, key descriptions (names) appearing in help output were provided initially as their associated command names. This provides flexibility, since it is the command that is most important. If a command ‘foobar’ is rebound from its default key then we want the doc to mention the new key.
For instance, a doc string that uses "the key `\\[forward-char]' does..." results in the output the key `C-f' does..., if command ‘forward-char’ is bound to key ‘C-f’.
This association between key and command is lost in the output, however. Starting with Emacs 23, library help-fns+.el enhances such key names by turning them into links to the doc for the corresponding commands. In the above doc string example, the key name ‘C-f’ is a link you can click (or hit ‘RET’ on), to see its doc, that is, the doc for command ‘forward-char’.
This enhancement affects only key names derived using the special doc-string construction `\\[...]’. It has no effect on key names that are hard-coded.
The following new commands are provided:
‘describe-command’ (‘C-h c’) – Same as ‘describe-function’, but only for commands (InteractiveFunctions).‘describe-option’ (‘C-h o’) – Same as ‘describe-variable’, but only for user variables (options).‘describe-option-of-type’ (‘C-h C-o’) – Same as ‘describe-option’, but you first specify the custom type of the option. Completion is available for both the custom type and the option of the chosen type. With a prefix arg, candidate options are not only those whose custom-type definition matches the chosen type, but also those whose current value satisfies the chosen type. So, for example, with a prefix argument, a variable whose value is a string satisfies a type such as (choice (const :tag "None" nil) string), (as does a variable whose value is ‘nil’). This command is particularly useful if you also use Icicles, because you can use substring and regexp matching, and you can use progressive completion to match multiple patterns.‘describe-keymap’ (‘C-h M-k’) – Describe the bindings in a keymap. Enter the keymap variable using completion.‘describe-file’ (‘C-h M-f’) – Display information about a file or directory: its type, permissions, size, time of last access/modification/status change, number of links, UID, GID, inode, and device number. Starting with Emacs 22, if the file is an image file and you have command-line tool ‘exiftool’ installed and in your `$PATH’ or ‘exec-path’, then some EXIF data (metadata) about the image is included. See standard Emacs library image-dired.el for more information about ‘exiftool’.‘describe-buffer’ (‘C-h B’) – Display information about a buffer. This includes the ‘describe-mode’ information for the buffer, but it also includes other info: its file name (if any), mode, size in chars, time/date of last display, whether it is modified (unsaved), and whether it is read-only.help-on-click/key’ (‘C-h RET’) – Super help: it gives help on any key/menu sequence or any object clicked with the mouse. Bind it to, for instance, ‘C-h RET’. The object can be any part of an Emacs window or any name appearing in a buffer. You can do any of the following:‘C-M-s’)‘Files’ > `Open File...’)‘apropos-documentation’ and ‘apropos’ provide information on the name‘pop-to-help-toggle’ (‘C-h M-o’) – Pop to buffer ‘*Help*’ or back to the buffer that sent you to ‘Help*’. Especially useful if you use non-‘nil’ ‘pop-up-frames’ (it raises and selects the Frame).‘save-*Help*-buffer’ (‘C-h C-s’) – (Emacs 20 only) Lets you rename the current *Help* buffer as a new buffer *Help*<N>, <N>=2, 3….‘view-emacs-lisp-news’ (‘C-h C-n’) – (Emacs 20 only) Displays information on recent changes to Emacs Lisp.The following standard Emacs commands have been improved:
‘describe-function’ – Prefix arg means describe a command (InteractiveFunction). Uses ‘symbol-nearest-point’ instead of ‘function-called-at-point’ to provide a default value.‘describe-variable’ – Prefix arg means describe a user variable (option). Uses ‘symbol-nearest-point’ instead of ‘variable-at-point’ to provide a default value.‘where-is’ – Uses ‘symbol-nearest-point’ instead of ‘function-called-at-point’ to provide a default value. Requires that a command be input, not just a function. Removes help window when you’re done with it.‘locate-library’ (‘C-h C-l’) – (Emacs 20 only) Removes help window when you’re done with it.‘describe-key’ – Returns nil if the key sequence is undefined; else returns ‘t’. (This feature is used by command ‘help-on-click/key’.) Lines that would be overly long are filled (Emacs 22 only).‘help-with-tutorial’, ‘describe-project’, ‘view-emacs-news’, ‘view-emacs-FAQ’ – (Emacs 20 only) Uses a separate window/frame. Removes help window when you’re done with it.The following key bindings have been added:
‘C-h C-a’ – `apropos’‘C-h M-a’ – `apropos-documentation’‘C-h C-M-a’ – `tags-apropos’‘C-h B’ – `describe-buffer’‘C-h c’ – `describe-command’ (replaces ‘describe-key-briefly’)‘C-h C-c’ – ‘describe-key-briefly’ (replaces ‘C-h c’)‘C-h M-c’ – `describe-copying’ (replaces (‘C-h C-c’)‘C-h M-k’ – `describe-keymap’‘C-h C-l’ – `locate-library’‘C-h M-l’ – ‘find-function-on-key’‘C-h C-n’ – `view-emacs-lisp-news’ (Emacs 20 only)‘C-h o’ – `describe-option’‘C-h C-o’ – `describe-option-of-type’‘C-h M-o’ – `pop-to-help-toggle’‘C-h C-s’ – `save-*Help*-buffer’ (Emacs 20 only)‘C-h u’ – ‘manual-entry’‘C-h RET’ – ‘help-on-click/key’‘mouse-1’ – ‘mouse-help-on-click’ (not on mode-line)‘mouse-1’ – ‘mouse-help-on-mode-line-click’ (mode-line)Library help-mode+.el enhances the ‘*Help*’ buffer by providing links for libraries that are mentioned there – see HelpModePlus.
The doc string for command ‘help-for-help’ (‘C-h C-h’) was rewritten to be more informative and clearer. Library help-macro+.el enhances macro ‘make-help-screen’ (which is used to create the ‘help-for-help’ display) to play well with frames (e.g. non-‘nil’ ‘pop-up-frames’).
DrewsElispLibraries referenced here: Lisp:help-macro+.el, Lisp:help+.el, Lisp:help+20.el, Lisp:help-fns+.el, Lisp:help-mode+.el