This page is about the following libraries, which together enhance the Emacs help system:
* [[help-macro+.el]]
* [[help+.el]] (or [[help+20.el]], for Emacs 20)
* [[help-fns+.el]]
* [[help-mode+.el]]
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.
[:LinksToManuals]
== Help Commands Provide Links to Manuals ==
Pretty much all of the standard help commands (`describe-face', `describe-function', `describe-variable',...), as well as the new help commands described [[#NewHelpCommands|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.
[:KeyLinks]
== Keys in Help are Linked to Their Doc ==
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.
[:NewHelpCommands]
== New Commands ==
The following new commands are provided:
* '''`describe-command'''' ('''`C-h c'''') -- Same as `describe-function', but only for commands ([[InteractiveFunction]]s).
* '''`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]] (e.g., `ctl-x-map`) using completion. (Non-interactively, the argument can be a [[keymap]] itself or a keymap variable.)
* '''`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:
** type a KeySequence (e.g. `C-M-s')
** choose a menu item (e.g. `Files' > `Open File...')
** click on a ScrollBar
** click on the ModeLine
** click in the MiniBuffer
** click on an Emacs-related name in a buffer: `apropos-documentation' and
`apropos' provide information on the name
** click anywhere else in a buffer: its modes are described
* '''`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*,