Before I start describing how you use this package, please let me explain some words as they are used in this text:
The interaction with the dictionary server happens in a dictionary buffer. The variable dictionary-use-single-buffer controls if a new buffer is created for each command or if the buffer is reused.
There are five different (documented) ways of invoking the package. By calling dictionary you can start a new dictionary buffer waiting for your commands. dictionary-search will ask for a word a search defaulting to the word at point and present all definitions found.
If you want to lookup the word near the point without further confirmation use the dictionary-lookup-definition function. The last one is dictionary-match-words which will ask for a pattern and display all matching words.
You can also display a popup menu showing the definition for a certain word. You just place the mouse cursor above the word you want to lookup and press the assigned mouse button. The sample definition in section Configuration binds this command to the right mouse button in GNU Emacs and to ctrl + right mouse button in XEmacs. For mouse invocation use dictionary-mouse-popup-matching-words, for assigning to a key combination use the dictionary-popup-matching-words function. The latter function search for the word located at point.
I have tested this feature in Emacs 21 and XEmacs 21. Emacs 20 do not support this kind of popup menus (you will get an error message if you try anyway), XEmacs 20 or prior has not been tested yet.
A new feature of version 1.5 is the tool-tip support. This will only work in GNU Emacs 21 and XEmacs. Please note, the tool-tip mode may slow down your Emacs, especially if you prefer using the mouse.
First you have to define the dictionary for looking up words to display in the tool-tip window. You could use * to search in all dictionaries, however tool-tip window should be rather small. I use an english to german dictionary for myself, which is called eng-deu (you can find out the name if you look into contents of the square brackets within the dictionary buffer; for example, the line From WordNet (r) 1.6[wn]: tells you the name of this dictionary is wn).
(setq dictionary-tooltip-dictionary "eng-deu")
In the GNU Emacs implemention you can decide to activate the tool-tip support either globally (global-dictionary-tooltip-mode) or local to a buffer (dictionary-tooltip-mode).
;; global dictionary-mode
(global-dictionary-tooltip-mode)
;; activate for all text-based modes
(add-hook 'text-mode-hook 'dictionary-tooltip-mode)
In XEmacs you can only use the dictionary-tooltip-mode:
;; activate for all text-based modes
(add-hook 'text-mode-hook 'dictionary-tooltip-mode)
When using the buffer-local dictionary-tooltip-mode, a mode indicator Dict is displayed whenever this minor mode is enabled.
The XEmacs support is not perfect, on my system (using latin-1) the contents of the translation window (implemented with the balloon-help) displays the byte representation of the utf-8 encoding. Suggestions for fixing this are very welcome.
To turn the tool-tip support off, call these functions with a numeric argument of 0.
If you get an error message that the server could not be contacted, please check the values of the variables dictionary-server and dictionary-port. The port should usually be 2628, the default server as distributed is dict.org.
Once a dictionary buffer is created you can close it by simply typing q (dictionary-close) or pressing the [Quit] button on the top. Another, more cruel, way is to use the kill-buffer function which is handled correctly.
The dictionary mode save the window configuration on startup and try to reestablish it when the buffer is being closed.
After a successful search the buffer is divided into two sections. The first one is the button area at the top, the other one is the text buffer displaying the result. By pressing the buttons you can select some functions that are otherwise inaccessible with the mouse.
In the text are each definition is introduced by the name of the database that contains it. In the default configuration this text is in italic face. The definition itself can contains hyper links that are marked using blue foreground and both sensitive to clicking with the mouse and pressing return while being within the link.
Each link selection or otherwise selected new search or match will create a new buffer showing the new result. You can use the [Back] button on the top or the l key (dictionary-previous) to return the previous buffer contents.
Pressing Meta while clicking on a link to start the search will extent the search to all dictionaries (dictionary-default-dictionary to be more precisely).
If you prefer using the keyboard it can be very frustrating to use the cursor key to position the point before pressing return to visit the link is possible. Therefore, I defined the Tab and the n keys to jump to the next link (dictionary-next-link) and the Shift-Tab and p keys to jump to the previous one (dictionary-prev-link). Please note that the Shift-Tab key may be the same as the Tab key when running Emacs within a tty (in contrast to a windowing system like X11). There is no way for a application to differ Shift-Tab from Tab in this case, please use the p key to visit the previous link if you run into this problem.
The search operation can be invoked by using the [Search Definition] button on the top or by pressing s (dictionary-search). It will ask for a word to search and will default to the word near point. This allows you to edit the word before starting the search. The found definitions will be displayed inside the buffer. If no entries could not be found an error message will be displayed.
If you want to quickly lookup the word at the point without further confirmation use the d key (dictionary-lookup-definition). Except for not allowing to edit the search word before asking the server it behaves the same way as the normal search operation.
The match operation is started upon pressing the [Matching Words] button or pressing the m key (dictionary-match-words). It will use the current database and the current strategy and list matching words for the one you entered at the prompt. The output is grouped by dictionary and each found word can be looked up by clicking the word or pressing return. Please note that in some cases not only the requested definition but some similiar definitions are shown. This behaviour is caused by the keyword lookup in the server. E.g., when you ask for the definition of from in Webster you will presented with the definitions of from and Thrust, the latter includes the phrase To thrust away or from which causes the display.
By default all dictionaries (special name is "*") are searched for a word definition or for matching words. You can select a specific word for both modi by pressing the [Select Default Dictionary] button or the D key (dictionary-select-dictionary). You will get a message about successful selection.
If you hold Meta while selecting a dictionary you will get more information displayed instead.
If you want to restore the original behaviour select All dictionaries. The first matching dictionary is a special dictionary (named "!") where the search will stop at the first dictionary with found definitions or matching words.
While searching matching words to the pattern you entered the server can use different comparison algorithm (aka search strategy). Every server provides a default strategy which is internally known as ".".
After pressing the [Select Match Strategy] button or pressing the M key (dictionary-select-strategy) all available strategies on this server are presented. As in the "select dictionary" mode you can select it by pressing the mouse button 2 or typing return.
If you visited a link and want to go back to the previous definition, simply choose the [Back] button or press the l key (dictionary-previous). The buffer contents and cursor position will be restored. If you intented to go beyond the first definition an error message will appear.
If you are totally confused what all the keys do in your dictionary buffer some help will displayed by pressing the h key. Within XEmacs you can exit the help screen by pressing q, in GNU Emacs you have to switch to the help window using C-x o (other-window) first. This help buffer will display the default key bindings only as I had problems with displaying multiple bindings for a single function (e.g., both button2 and return select a link). Any suggestions are welcome.
E-Mail: web-200705@myrkr.in-berlin.de