describe-word(3)

NAME

describe-word - Display a dictionary definition of a word

SYNOPSIS

describe-word "word"

DESCRIPTION

describe-word can be used to interface to an external dictionary to get a definition of a given word. When executed describe-word will use the current word under the cursor as the initial word or will prompt the user if the cursor is not in a word.

The command provides four methods of interfacing with an external dictionary and each language can be configured to use one or more dictionaries, allowing secondary sources to be used if the primary lookup failed. The first interface simply launches an external program which provides the definition in its own user interface, e.g. GoldenDict or MS Bookshelf. A lookup using this interface is always assumed to be successful so this should always be the last one for a language.

The second interface launches an external program which prints out the definition to stdout, MicroEmacs can then pull out the definition and display it in a *describe-word* buffer.

The third interface requires a URL, such as http:// or dict://, which provides the definition when loaded, and a clean-up macro the turns the definition into a readable form.

The last interface requires a dictionary text file, a regex search string and a clean-up macro. describe-word loads the dictionary file and searches for definitions of the given word, adding each one to the output buffer, it then calls the clean-up macro to format the definitions into a more readable form.

NOTES

describe-word is a macro implemented in word.emf.

Due to the size and availability of dictionaries etc. MicroEmacs is released with describe-word set up to use the most appropriate dictionaries available at dict://dict.org/.

describe-word must be setup for each required language, which requires the setting of a .describe-word.<lang-id> variable. The variable must be a MicroEmacs list of dictionary interface configurations, each one being a sub-list to configure the interface to a dictionary source, each sub-list must take one of four forms:

External


To interface with an external program the sub-list has the following items:

|<flags>|<source-name>|<not-used>|<command-line>| 

Where:

<flags>


Is a list of option flags, one of which must be x to indicate an external source. Other flags supported by an external source are i to use an ipipe to launch, this is useful when needing to debug the interface, and s for a single, or shared, output buffer which is only used when ipipe mode is also being used.

<source-name>


Defines the name of the interface, or source, and is only used when ipipe mode is also being used.

<not-used>


The 3rd item is not currently used and should be left empty.

<command-line>


Defines the command-line required to launch the external dictionary program, the <command-line> should contain a %w token which is replaced with the given word, the token will typically also require surrounding %" tokens (i.e. %"%w%") so that if the word contains a space it will be properly quoted in the generated command-line.

Command


To interface with an external program which prints the definition out to stdout, the sub-list has the following items:

|<flags>|<source-name>|<clean-up-macro>|<command-line>| 

Where:

<flags>


Is a list of option flags, one of which must be c to indicate a command source. The only other flags currently supported by a command source is s for a single, or shared, output buffer, without this flag the buffer name includes the word being described.

<source-name>


Defines the name of the interface, or source, which is used in the details given in the first line of the output buffer.

<clean-up-macro>


The clean-up macro has two purposes, firstly if the macro aborts (i.e. calls !abort(4) etc.) it signals to describe-word that the output does not actually contain a definition, for example the output may simply be "No definitions found for <word>". The second purpose is to perform any clean-up and reformatting required to make the output more legible. describe-word provides a simple describe-word-cmd macro which simply aborts if the output contains one line with the line starting with "No definitions found for ".

<command-line>


Defines the command-line required to launch the dictionary program, the <command-line> should contain a %w token which is replaced with the given word, the token will typically also require surrounding %" tokens (i.e. %"%w%") so that if the word contains a space it will be properly quoted in the generated command-line.

URL


To interface with an online dictionary source, the sub-list has the following items:

|<flags>|<source-name>|<clean-up-macro>|<url>| 

Where:

<flags>


Is a list of option flags, one of which must be u to indicate a URL source. The only other flags currently supported by a URL source is s for a single, or shared, output buffer, without this flag the buffer name includes the word being described.

<source-name>


Defines the name of the interface, or source, which is used in the details given in the first line of the output buffer.

<clean-up-macro>


The clean-up macro has two purposes, firstly if the macro aborts (i.e. calls !abort(4) etc.) it signals to describe-word that the output does not actually contain a definition, for example the output may simply be a network error. The second purpose is to perform any clean-up and reformatting required to make the output more legible. describe-word provides a describe-word-dct macro for dict:// URLs which aborts if the output contains less than three lines. It also reformats the output to improve the output in MicroEmacs.

<url>


Defines the URL required to get a definition, the <url> should contain either a %w token, which is replaced with the given word in plain text, or %e which is replaced with the given word URL-encoded (also known as percent encoded).

File


To interface with a dictionary text file, the sub-list has the following items:

|<flags>|<source-name>|<clean-up-macro>|<regex-search>|<dict-file>| 

Where:

<flags>


Is a list of option flags, one of which must be f to indicate a file source. Other flags currently supported by a file source are k to keep the dictionary file loaded (improves performance at a cost of increased memory usage), m to indication that the dictionary may contain multiple definitions of the same word, and s for a single, or shared, output buffer, without this flag the buffer name includes the word being described.

<source-name>


Defines the name of the interface, or source, which is used in the details given in the first line of the output buffer.

<clean-up-macro>


The clean-up macro has two purposes, firstly if the macro aborts (i.e. calls !abort(4) etc.) it signals to describe-word that the output does not actually contain a definition. The second purpose is to perform any clean-up and reformatting required to make the output more legible. describe-word provides a describe-word-sln macro which attempts to convert a single line of definition text into a better laid out set of definitions.

<regex-search>


Defines the regex search string required to find the definition of a given word, it must contain a %r token which is replaced with the given word (but regex encoded, i.e. '.' to '\.' etc) and at least on group, the first of which must fully contain the definition.

<dict-file>


The file name of the dictionary, this can be an absolute file name or given without the path if the file is located in a directory in the MicroEmacs $search-path(5).
Each interface sub-list must be wrapped up in the main setup list, which must use a different list separator character.

Note that if spelling has also been setup for the current language, when describe-word fails to find a definition it will use the spell(2) interface to extract the base word (i.e. base of words is word) and search for a definition of the base word. When a language is configured to use multiple interfaces, the actual word and then the base is looked-up in the primary interface before moving to the secondary etc.

EXAMPLE

The following example configures describe-word to use the online dict://dict.org/ WordNet English dictionary:

set-variable .describe-word.enus "!|u|WordNet|describe-word-dct|dict://dict.org/d:%w:wn|!" 

WordNet is a good modern English dictionary, but it has less than 150K word definitions. To improve the likelihood of finding a definition, a secondary source can be added:

set-variable .describe-word.enus "!|u|WordNet|describe-word-dct|dict://dict.org/d:%w:wn|!|u||describe-word-dct|dict://dict.org/d:%w:*|!" 

The changed of wm to * at the end of the dict:// URL requests the dictionary server to search all available dictionaries. Alternatively, if the dict(1) utility is installed, it can be used instead, as follows:

set-variable .describe-word.enus "!|c||describe-word-cmd|dict %\"%w%\"|!" 

Note the enclosing of %w with %" tokens to ensure the correct encoding/formatting of the command-line.

Alternatively, if the GoldenDict(1) utility is installed, the following can be used to simply launch the utility:

set-variable .describe-word.enus "!|x|GoldenDict||goldendict %\"%w%\"|!" 

Note however that MicroEmacs has no way to detect whether a definition was found, so it has to assume it was. As a result this interface should be last as no further interfaces will be used.

If available, the use of a local dictionary text file can greatly improve performance, the dictionary file typically contains the word at the start of a line, followed by a delimiter, such as a tab character, and then the definition in the rest of the line. describe-word can be configured to use such a file as follows:

set-variable .describe-word.enus "!|fkms|My Dictionary File|describe-word-sln|^%r\t\\(.*\\)|mydict.txt|!" 

Where mydict.txt is the name of the dictionary file and is located in the MicroEmacs search path. This could be combined with other sources such as dict.org or GoldenDict, to create a comprehensive dictionary look-up:

set-variable .describe-word.enus "!|fkms|My Dictionary File|describe-word-sln|^%r\t\\(.*\\)|mydict.txt|!|u|WordNet|describe-word-dct|dict://dict.org/d:%w:wn|!|x|GoldenDict||goldendict %\"%w%\"|!" 

The required variables should be added to the user setup file. Notes that, as some interfaces could use '!' or '|' characters in their configuration, MicroEmacs uses different list separator characters, typically \f place of ! and \b instead of |.

SEE ALSO

spell-word(3), spell-buffer(3), find-word(3).

Ref: describe-word(3) File: m3osd009.3 Date: 2026/03/25

(c) Copyright JASSPA 2026