Elisp: Doc String Markup
This page shows emacs function/command's doc string convention and markup.
describe-function screen. (note the clickable links.)When you lookup a function's doc by Alt+x describe-function 【Ctrl+h f】, you'll notice these features:
- function's parameters are italicized.
- mention of other function's name can be clicked to jump to.
- URL can be clicked to jump to web browser.
- keyboard shortcuts will show correctly even if user have changed it.
To have these features, you need to put markups in your inline string.
Here's a summary:
| Example | Purpose |
|---|---|
ALLCAPS | function argument. |
`sort-lines' | link to other function. |
URL `http://example.org/' | link to URL. |
Info node `(emacs) Dired' | link to Info doc node. |
\\[find-file] | keybinding of a command |
\\<c-mode-map> | No visible effect. Tell emacs to use this keymap for displaying keys in the rest of this doc string. |
\\{c-mode-map} | list of keybindings of a given keymap. |
Example:
(defun something (arg1 arg2) "no more than 67 chars summary here. detail. Mention return value. No indentation. • ARG1 is…. Parameters should be all caps. • See URL `http://example.com/' (clickable url) • See `dired' (clickable function/variable name) • See `(emacs) Dired'. (link to info doc) • Type \\[dired] to go into dired. (key of a command.) • clickable list of all keys of a given keymap name. \\{c-mode-map}" (interactive) (message "%s" "do something.") )
The following are details of each case.
Short Summary in First Line
The first line of your doc string should be a one sentence summary of the function. Because, apropos-command 【Ctrl+h a】 will display just that line.
The first line should be no more than 67 characters.
The doc string should be formatted into lines each about 70 chars, instead of one long line of hundreds chars. (you can use fill-paragraph for this.)
Italized Parameter Names
When your function takes arguments, their names in the inline string should be all CAPS. Example:
(defun read-lines (file-path) "Return a list of lines of a file at FILE-PATH." (with-temp-buffer (insert-file-contents file) (split-string (buffer-string) "\n" t)))
This way, when describe-function displays it, the arg will be automatically italized.
Clickable Function/Variable Names
If your doc mentions another function, user can click on it, so it takes them to that function's doc string. To make it clickable, you need to quote it with `…'. Example:
(defun auto-fill-mode (&optional arg) "Toggle Auto Fill mode. With ARG, turn Auto Fill mode on if and only if ARG is positive. In Auto Fill mode, inserting a space at a column beyond `current-fill-column' automatically breaks the line at a previous space. The value of `normal-auto-fill-function' specifies the function to use for `auto-fill-function' when turning Auto Fill mode on." ;… ))
Some elisp names are both function and variable. (For example, linum-mode). In that case, if you want emacs to link to the function, precede it with the word “function” or any of the word {variable, option, command}. Example:
(defun my-linum-numbering-mode () "… See also: command `linum-mode' and variable `linum-mode'" ;; … )
Clickable URL
To have a clickable URL, do like this:
URL `http://example.org/'. Example:
(defun xlsl-mode () "See URL `http://xahsl.org/sl/ls-emacs.html'." )
Links to Emacs Info Doc
Sometimes you want clickable links to emacs's doc. You can mark it like this:
Info node `(elisp)Font Lock Basics'.
(defun xx () "See Info node `(emacs) Dired'." )
Remember, each page in info doc is identified by a string, for examples: (emacs) Dired, (elisp)Font Lock Basics. The first part in paren is the doc name, followed by the node's name. When you are in info page, pressing c will copy this node's id to the kill-ring.
But also note, emacs's info node may change or disappear with new emacs versions. 〔►see Emacs Manual Node Persistency Issues〕
Auto Generate Shortcut Keys
In your doc string you may need to tell users about pressing a keyboard shortcut to do something. For example, in dired, when you Alt+x describe-mode, the doc says:
“Type C to Copy files.”. If a user has customized dired's keys, the doc string will correctly display the new key.
To make the key of a command automatically show correctly, you need to quote the command name by \\[command_name]. Here's a example from dired:
(defun dired-mode (&optional dirname switches) "\ Mode for \"editing\" directory listings. … Type \\[dired-do-copy] to Copy files. …" )
Sometimes the command you mentioned may have different keys in your mode or in global mode. You can be specific by including \\<key_map_name> before \\[command_name].
The \\<key_map_name> won't be displayed, it just tells emacs what keymap to use for processing the rest of doc string. Example:
(defun dired-mode (&optional dirname switches) "… You can move using the usual cursor motion commands.\\<dired-mode-map> The buffer is read-only. Digits are prefix arguments. Type \\[dired-flag-file-deletion] to flag a file `D' for deletion. Type \\[dired-mark] to Mark a file or subdirectory for later commands. …" )
Auto Generated Keybinding List
A major mode usually has its own set of keyboard shortcuts (its own keymap). For example, in c-mode, Alt+x describe-mode 【Ctrl+h m】, you'll see this:
Key bindings: key binding --- ------- C-c Prefix Command C-d c-electric-delete-forward TAB c-indent-line-or-region …
This is automatically generated. You just need to quote the keymap name by \\{…}. By convention, you put it at the end of your major mode's documentation. Example:
(defun c-mode () "Major mode for editing K&R and ANSI C code. To submit a problem report, enter `\\[c-submit-bug-report]' from a c-mode buffer. This automatically sets up a mail buffer with version information already added. You just need to add a description of the problem, including a reproducible test case, and send the message. To see what version of CC Mode you are running, enter `\\[c-version]'. The hook `c-mode-common-hook' is run with no args at mode initialization, then `c-mode-hook'. Key bindings: \\{c-mode-map}" ;… )
Reference
thanks to jcs for tips.