add-dictionary(2)

NAME

add-dictionary - Declare existence of a spelling dictionary

SYNOPSIS

n add-dictionary "file"

DESCRIPTION

add-dictionary adds the given dictionary (specified by the given file) to the dictionary list. Note that the file may omit the .edf extension, this is automatically added.

The command accepts a numeric argument 'n' which determines the actions to be undertaken. When n is omitted then the dictionary is marked for loading (on demand) - this is the standard invocation used in the start up files.

If an argument of 0 is given the dictionary is created but it is not marked for loading, this can be used to create an empty dictionary.

If an argument of -1 is given the contents of the dictionary are dumped into the current buffer, used for dictionary maintenance. The two main uses of this command are discussed below.

Dictionary Loading

A call to add-dictionary with no numeric argument does not perform an immediate load of the dictionary, instead the dictionary is only loaded on demand, i.e. when a call to spell(2) (usually via spell-word(3) or spell-buffer(3)) is made, this ensures that the start up time for MicroEmacs does not become too long. When the dictionary is loaded it is checked for efficiency, if found to be inefficient it is automatically optimized and flagged as changed. On exiting MicroEmacs, the user is prompted to save any dictionary that has be altered or optimized.

The spelling search order is made from the last dictionary added to the first, as soon as a word is found in a dictionary the search is halted. This implies that if a word has been defined incorrectly in one dictionary, but correct in another, the order in which the dictionaries are added determines the result.

The number of dictionaries allowed is unlimited but note that any words added are always added to the LAST dictionary. The size of the dictionary is restricted to about 16.7MB, the size is NOT tested when words are added and if this size is exceeded the results are undefined. However, it is unlikely that this limit will be reached, the largest dictionary created to date is 13.5MB.

A new main dictionary may be created as follows:

1)


Find a file containing an ispell(1) compatible list of words.

2)


execute-file(2) spellutl.emf to define macro spell-add-word(3).

3)


Start up MicroEmacs and execute the command add-dictionary giving an appropriate new dictionary name.

4)


Load up the file containing the words and execute the command spell-add-word(3) with a very large argument so all the words are added.

5)


Save the dictionary by either executing the command save-dictionary(2) or exiting.

Dictionary Dump

A call to add-dictionary with a numeric argument n of -1 causes the contents of the given dictionary to be dumped into the current buffer (make sure you are in an empty buffer or *scratch*) where:

xxxx - Good word xxxx with no spell rules allowed
xxxx/abc - Good word xxxx with spell rules abc allowed
xxxx>yyyy - Erroneous word with an auto-replace to yyyy

The dump of the dictionary may be edited, allowing erroneous entries to be removed. The macro file spellutl.emf contains macros edit-dictionary(3) and restore-dictionary(3) which enable the user to edit a dictionary.

NOTES

MicroEmacs is supplied with dictionaries for American and British English, it is strongly suggested that these dictionaries are NOT modified in anyway. Ensure that the dictionary is protected by loading the base dictionaries first, followed by a personal dictionary. New words added during spelling will then be added to the personal dictionary rather than the main dictionary.

EXAMPLE

The MicroEmacs start-up file me.emf executes language.emf which in turn executes command spell-rules-init (located in langutl.emf) which adds the main language rules and dictionary. The command then adds the user's dictionary, this process can be simplified to:

; reset the spell rules 
0 add-spell-rule 
; Now add the American spell rules 
-2 add-spell-rule "A" "" "" "re" "" ; As in enter > reenter 
-2 add-spell-rule "I" "" "" "in" "" ; As in disposed > indisposed 
    . 
    . 
; Now add the main American dictionary 
add-dictionary "lsmenus" 
; Now add the user dictionary 
add-dictionary $MENAME 

SEE ALSO

add-spell-rule(2), save-dictionary(2), spell-add-word(3), edit-dictionary(3), spell-buffer(3).

Ref: add-dictionary(2) File: m2cmd002.2 Date: 2026/03/05

(c) Copyright JASSPA 2026