This manual describes the Emacs package Dict (or
dict.el), which provides an
interface for querying RFC2229 dictionary servers and displaying word
Dict is currently available from its Git repository. To clone the latest version, run:
git clone git://git.eshelyaron.com/dict.git
M-x package-install-file to install
dict.el from the
cloned repository as a package.
Displaying Word Definitions
Dict defines a single autoloaded command for displaying word definitions:
- Command: dict-describe-word
- Prompt for a word and display its definition.
This command prompts for a word in the minibuffer, obtains its
definition from a dictionary server, and displays it in a
buffer. (See Help in the Emacs manual.)
dict-describe-word uses dictionary matches for the word at point, if
any, as the minibuffer’s “future history” (see Minibuffer History).
This means that you can display the definition of the word at point by
M-x dict-describe-word RET RET.
Dictionary servers usually support several dictionaries that you can query.
When Dict asks the dictionary server for a word definition, it needs to specify
in which dictionary the server should look. The dictionary Dict uses is
determined by the user option
dict-dictionary. By default this is set to
nil, which says to prompt for a supported dictionary the first time you invoke
Similarly, the user option
dict-strategy specifies a dictionary matching
strategy for finding completion candidates. This is set to
nil by default,
dict-dictionary, which means that
dict-describe-word prompts also for a
supported matching strategy the first time you use it.
You can customize
dict-strategy to appropriate values
dict-describe-word to inhibit these prompts on first use.
(Also see Customizing Dict for more customization options.)
The following user options affect the behavior of
- User Option: dict-server-host
- Host name or IP address of the
dictionary server to use. Defaults to
nil, which means to first try “localhost”, and if no local server is available then fallback to the host specified by
- User Option: dict-default-server-host
- Remote dictionary server to
use when there is no local server and
nil. Defaults to “dict.org”.
- User Option: dict-server-port
- Port number to use for connecting to the dictionary server. Defaults to 2628.
- User Option: dict-dictionary
- Name of the dictionary to query, which must be
supported by the dictionary server. Default to
nil, which means to prompt for a supported dictionary on the first invocation of
- User Option: dict-dictionary-prompt
- Prompt string to use when prompting for a dictionary. Defaults to “Set dictionary”.
- User Option: dict-strategy
- Name of the dictionary matching strategy to use,
which must be supported by the dictionary server. Default to
nil, which means to prompt for a supported strategy on the first invocation of
- User Option: dict-strategy-prompt
- Prompt string to use when prompting for a matching strategy. Defaults to “Set matching strategy”.
- User Option: dict-process-name
- Name to use for the dictionary server connection process. Defaults to “dict”.
- User Option: dict-process-buffer-name
- Name of the buffer to use for the dictionary server connection process output. Defaults to “*dict output*”.
- User Option: dict-display-definition-function
- Function to use for
displaying word definitions. The function must take two string arguments, the
word and its definition, and display the definition to the user. Defaults to
dict-display-definition-in-help-buffer, which displays the definition in a
Dict provides the following functions for querying dictionary servers from Elisp:
- Function: dict-match-word word
- Return a list of dictionary matches for WORD.
- Function: dict-define-word word
- Return the dictionary definition of
nilif not defined.
dict-match-word queries the dictionary server for words
that match a given input in the dictionary specified by the user option
dict-dictionary, based on the matching strategy specified by the
dict-define-word retrieves and returns
the definition of a given word in the dictionary specified by
dict-dictionary as a string, or it returns
nil if the dictionary
server doesn’t find a definition for that word.
The best way to extend Dict with bespoke commands for your workflow, is to
define wrappers around
dict-describe-word that supply specific words or
locally bind some user options to specific values. For example, the following
command looks up the definition of the word at point in the WordNet dictionary
(defun my/wordnet-definition-for-word-at-point (word) (interactive (list (word-at-point))) (let ((dict-dictionary "wn")) (dict-describe-word word)))
To create a command that displays definitions in the echo area (see Echo Area),
dict-display-definition-function to an appropriate function:
(defun my/echo-word-definition (word) (interactive (list (dict-read-word))) (let ((dict-display-definition-function (lambda (_word definition) (message definition)))) (dict-describe-word word)))
Note the use of the function
dict-read-word in the above definition.
This helper function prompts for a word defined in dictionary, with
completion, using the word at point as the minibuffer’s “future
history”. This is also what
dict-describe-word uses to prompt for a
word when you call it interactively.
Here’s an example configuration for Dict:
(with-eval-after-load 'dict ;; some settings (setq dict-server-host "dict.org" dict-dictionary "gcide" dict-strategy "prefix")) (keymap-global-set "M-#" #'dict-describe-word)
If you install Dict as a package then
dict-describe-word is autoloaded on
demand, so there’s no need to
require anything before you use it.
Motivation Behind Dict
The main motivation behind the development of Dict was to resolve some
issues that the author came across with the
dictionary.el package that
ships with Emacs. This package, initially written by Torsten Hilbrich
to support both GNU Emacs and XEmacs, was added as a library to Emacs
core in version 28.
In their essence, Dict and
dictionary.el have similar goals and they
both operate in a similar manner–getting word definitions from RFC2229
servers, and displaying them in an Emacs buffer.
Dict’s differentiation comes from its simplicity and extensibility–while
dictionary.el defines a bespoke major mode and interface for browsing word
definitions, Dict leverages Emacs’s Help mode by default, and lets you extend
and control every aspect of its behavior via customization options.
dict.el is also shorter than
dictionary.el–just under 300 lines of code!