2 Emacs package for talking to a dictionary server
6 In December 1998 I installed the dictd server, which can be used to
7 access several dictionaries using a simple protocol as defined in
8 RFC 2229 (Text Version).
10 As my primary working environment is XEmacs 21, I decided to write
11 an Emacs-Lisp package for accessing this dictionary server. The older
12 webster.el didn't worked with the newer protocol. After starting the
13 implementation I was pointed to an already existing implementation,
14 but this was basically a wrapper to the dict client program and didn't
15 have all the features I wanted and have now been implemented in this
18 If you didn't received this file from its original location you can
19 visit it at http://www.myrkr.in-berlin.de/dictionary.html
23 The dictionary mode provides the following features:
24 * looking up word definitions in all dictionaries
25 * search for matching word
26 * words/phrases marked with { } in the dictionary definitions are
27 recognized as hyper links and browseable
28 * easy selection of dictionary and search strategy
29 * backward moving through the visited definitions
30 * in the latest versions of GNU Emacs and XEmacs you get support for
32 * in GNU Emacs 21 and XEmacs 21 you can lookup words by simply
33 pointing the mouse cursor to them (tool-tips)
37 I have tested the package with a native GNU Emacs 19.34.1 and
38 XEmacs 20.4. I implemented some hacks to work with the very very
39 old custom.el file in the above GNU Emacs. Please update to the
40 current version whenever possible. XEmacs 21 and Emacs 20 as well
41 as Emacs 21 have been tested too.
43 I you want to know more about the differences please look at the
46 You will need the custom package to use this package. For full support
47 please check if your system knows the defface function, if not please
48 download the current version.
50 For best usability I suggest using the mouse, but it provide good
51 keyboard support as well.
55 The package is distributed as tar.gz file. You unpack it using:
57 gzip -dc dictionary-1.8.5.tar.gz | tar xf -
61 tar -xzf dictionary-1.8.5.tar.gz
63 (with the version number subject to change) depending on whether you
64 are using GNU tar which support the z flag for compression. After
65 unpacking the archive a directory dictionary-1.8.5 has been created
66 containing the necessary files.
72 If you are using a current Debian distribution (one that support
73 the emacsen package system) and have the build-essential, dpkg-dev,
74 and debmake packages installed (for running dpkg-buildpackage) you
75 can use the supplied debian support.
79 This will create a package named dictionary-1.8.5-1_all.deb or
80 similiar in the parent directory of dictionary-1.8.5. You can now
81 install this package as root, it will automatically byte-compile
82 itself for all installed emacs versions and provide a startup-file
83 which autoloads this package. In the configuration example given below
84 you can omit the autoload lines.
86 If you no longer want to use this package, you can remove it using:
92 The XEmacs version 21 support so called xemacs packages. These
93 packages are also supported, you can create them using:
95 make EMACS=xemacs package
97 The created package will be named dictionary-1.5-pkg.tar.gz and stored
98 within the current directory. If you don't want to install this
99 package manually, you can use the following command, provided you have
100 sufficient privileges (if unsure, login as super user):
102 make EMACS=xemacs package-install
104 If you have more than one XEmacs versions installed make sure the
105 EMACS argument to make points to the current binary.
111 For faster loading and executing of the package I strongly suggest
112 that you byte-compile the files. Emacs user please call make within
113 the create subdirectory, XEmacs user has to specify there favorite
114 tool using make EMACS=xemacs. If your custom package is not up-to-date
115 expect some warnings about free variables.
119 To install the files into your GNU Emacs/XEmacs installation please
120 copy the *.elc files into a directory being in your load-path
121 variable. On most installations /usr/lib/emacs/site-lisp or
122 /usr/local/lib/emacs/site-lisp are suitable locations.
126 You have to insert some instructions into your .emacs file to load the
127 dictionary package whenever needed. If you installed this dictionary
128 package as Debian package or XEmacs package you don't need the
129 autoloads, they are already supplied. Other users I suggest using the
132 (autoload 'dictionary-search "dictionary"
133 "Ask for a word and search it in all dictionaries" t)
134 (autoload 'dictionary-match-words "dictionary"
135 "Ask for a word and search all matching words in the dictionaries" t)
136 (autoload 'dictionary-lookup-definition "dictionary"
137 "Unconditionally lookup the word at point." t)
138 (autoload 'dictionary "dictionary"
139 "Create a new dictionary buffer" t)
140 (autoload 'dictionary-mouse-popup-matching-words "dictionary"
141 "Display entries matching the word at the cursor" t)
142 (autoload 'dictionary-popup-matching-words "dictionary"
143 "Display entries matching the word at the point" t)
144 (autoload 'dictionary-tooltip-mode "dictionary"
145 "Display tooltips for the current word" t)
146 (unless (boundp 'running-xemacs)
147 (autoload 'global-dictionary-tooltip-mode "dictionary"
148 "Enable/disable dictionary-tooltip-mode for all buffers" t))
150 In addition, some key bindings for faster access can be useful. I use
151 the following ones in my installation:
154 (global-set-key "\C-cs" 'dictionary-search)
155 (global-set-key "\C-cm" 'dictionary-match-words)
157 I will describe the user-callable functions and the key bindings
158 within dictionary mode later in this document.
164 Before I start describing how you use this package, please let me
165 explain some words as they are used in this text:
168 This is a word you want to lookup in the dictionaries verbatim.
171 This is used for looking up matching words. A pattern can be as
172 simple as a single word but also as complex as a POSIX regular
173 expression. The meaning of a pattern depends on the strategy
174 used for matching words.
177 The server can handle several distinct dictionaries. You can
178 select specific dictionaries or ask the server to search in all
179 dictionaries or until matches or definitions are found. To
180 search in all dictionaries the special name * is used, the
181 special name ! requests to search until definitions are found.
182 For more details please take a look at the standards
186 A dictionary entry that can be the result of a word search.
189 The operation of looking up a word in the dictionaries.
192 The operation of comparing a pattern to all words in the
196 While matching in a dictionary serveral methods for comparing
197 words can be used. These methods are named strategies and
198 include exact match, regular expression match, and soundex
199 match. The available strategies depends on the server, but a
200 special name . can be used to denote a server-default strategy.
204 There are five different (documented) ways of invoking the package. By
205 calling dictionary you can start a new dictionary buffer waiting for
206 your commands. If you want to create multiple buffers for searching
207 the dictionary, you can run this function multiple times.
208 dictionary-search will ask for a word a search defaulting to the word
209 at point and present all definitions found.
211 If you want to lookup the word near the point without further
212 confirmation use the dictionary-lookup-definition function. The last
213 one is dictionary-match-words which will ask for a pattern and display
216 You can also display a popup menu showing the definition for a certain
217 word. You just place the mouse cursor above the word you want to
218 lookup and press the assigned mouse button. The sample definition in
219 section Customizing binds this command to the right mouse button
220 in GNU Emacs and to ctrl + right mouse button in XEmacs. For mouse
221 invocation use dictionary-mouse-popup-matching-words, for assigning to
222 a key combination use the dictionary-popup-matching-words function.
223 The latter function search for the word located at point.
225 I have tested this feature in Emacs 21 and XEmacs 21. Emacs 20 do not
226 support this kind of popup menus (you will get an error message if you
227 try anyway), XEmacs 20 or prior has not been tested yet.
229 A new feature of version 1.5 is the tool-tip support. This will
230 only work in GNU Emacs 21. Starting from version 1.8.5 this feature
231 is also available in XEmacs. Please note, the tool-tip mode may
232 slow down your Emacs, especially if you prefer using the mouse.
234 First you have to define the dictionary for looking up words to
235 display in the tool-tip window. You could use * to search in all
236 dictionaries, however tool-tip window should be rather small. I use
237 an english to german dictionary for myself, which is called eng-deu
238 (you can find out the name if you look into contents of the square
239 brackets within the dictionary buffer; for example, the line From
240 WordNet (r) 1.6[wn]: tells you the name of this dictionary is wn).
242 (setq dictionary-tooltip-dictionary "eng-deu")
245 In the GNU Emacs implemention you can decide to activate the
246 tool-tip support either globally (global-dictionary-tooltip-mode)
247 or local to a buffer (dictionary-tooltip-mode).
249 ;; global dictionary-mode
250 (global-dictionary-tooltip-mode)
251 ;; activate for all text-based modes
252 (add-hook 'text-mode-hook 'dictionary-tooltip-mode)
255 In XEmacs only the local version (dictionary-tooltip-mode) is
258 ;; activate for all text-based modes
259 (add-hook 'text-mode-hook 'dictionary-tooltip-mode)
261 To turn the tool-tip support off, call these functions with a
262 numeric argument of 0.
264 The mode line includes a Dict marker if this minor mode is active.
266 If you get an error message that the server could not be contacted,
267 please check the values of the variables dictionary-server and
268 dictionary-port. The port should usually be 2628, the default server
269 as distributed is dict.org.
271 You can have multiple independent dictionary buffer. If the above
272 functions are called from within dictionary mode they reuse the
273 existing buffer. Otherwise they create a new buffer.
277 Once a dictionary buffer is created you can close it by simply typing
278 q (dictionary-close) or pressing the [Quit] button on the top.
279 Another, more cruel, way is to use the kill-buffer function which is
282 The dictionary mode save the window configuration on startup and try
283 to reestablish it when the buffer is being closed.
287 After a successful search the buffer is divided into two sections. The
288 first one is the button area at the top, the other one is the text
289 buffer displaying the result. By pressing the buttons you can select
290 some functions that are otherwise inaccessible with the mouse.
292 In the text are each definition is introduced by the name of the
293 database that contains it. In the default configuration this text is
294 in italic face. The definition itself can contains hyper links that
295 are marked using blue foreground and both sensitive to clicking with
296 the mouse and pressing return while being within the link.
298 Each link selection or otherwise selected new search or match will
299 create a new buffer showing the new result. You can use the [Back]
300 button on the top or the l key (dictionary-previous) to return the
301 previous buffer contents.
303 Pressing Meta while clicking on a link to start the search will extent
304 the search to all dictionaries (dictionary-default-dictionary to be
307 If you prefer using the keyboard it can be very frustrating to use the
308 cursor key to position the point before pressing return to visit the
309 link is possible. Therefore, I defined the Tab and the n keys to jump
310 to the next link (dictionary-next-link) and the Shift-Tab and p keys
311 to jump to the previous one (dictionary-prev-link). Please note that
312 the Shift-Tab key may be the same as the Tab key when running Emacs
313 within a tty (in contrast to a windowing system like X11). There is no
314 way for a application to differ Shift-Tab from Tab in this case,
315 please use the p key to visit the previous link if you run into this
320 The search operation can be invoked by using the [Search Definition]
321 button on the top or by pressing s (dictionary-search). It will ask
322 for a word to search and will default to the word near point. This
323 allows you to edit the word before starting the search. The found
324 definitions will be displayed inside the buffer. If no entries could
325 not be found an error message will be displayed.
327 If you want to quickly lookup the word at the point without further
328 confirmation use the d key (dictionary-lookup-definition). Except for
329 not allowing to edit the search word before asking the server it
330 behaves the same way as the normal search operation.
334 The match operation is started upon pressing the [Matching Words]
335 button or pressing the m key (dictionary-match-words). It will use the
336 current database and the current strategy and list matching words for
337 the one you entered at the prompt. The output is grouped by dictionary
338 and each found word can be looked up by clicking the word or pressing
339 return. Please note that in some cases not only the requested
340 definition but some similiar definitions are shown. This behaviour is
341 caused by the keyword lookup in the server. E.g., when you ask for the
342 definition of from in Webster you will presented with the definitions
343 of from and Thrust, the latter includes the phrase To thrust away or
344 from which causes the display.
348 By default all dictionaries (special name is "*") are searched for a
349 word definition or for matching words. You can select a specific word
350 for both modi by pressing the [Select Default Dictionary] button or
351 the D key (dictionary-select-dictionary). You will get a message about
352 successful selection.
354 If you hold Meta while selecting a dictionary you will get more
355 information displayed instead.
357 If you want to restore the original behaviour select All dictionaries.
358 The first matching dictionary is a special dictionary (named "!")
359 where the search will stop at the first dictionary with found
360 definitions or matching words.
362 Selection search strategy
364 While searching matching words to the pattern you entered the server
365 can use different comparison algorithm (aka search strategy). Every
366 server provides a default strategy which is internally known as ".".
368 After pressing the [Select Match Strategy] button or pressing the M
369 key (dictionary-select-strategy) all available strategies on this
370 server are presented. As in the "select dictionary" mode you can
371 select it by pressing the mouse button 2 or typing return.
375 If you visited a link and want to go back to the previous definition,
376 simply choose the [Back] button or press the l key
377 (dictionary-previous). The buffer contents and cursor position will be
378 restored. If you intented to go beyond the first definition an error
383 If you are totally confused what all the keys do in your dictionary
384 buffer some help will displayed by pressing the h key. Within XEmacs
385 you can exit the help screen by pressing q, in GNU Emacs you have to
386 switch to the help window using C-x o (other-window) first. This help
387 buffer will display the default key bindings only as I had problems
388 with displaying multiple bindings for a single function (e.g., both
389 button2 and return select a link). Any suggestions are welcome.
393 Starting from version 1.6 (not officially released) the dictionary
394 client supports connections via HTTP proxies. It uses the CONNECT
395 method which is usually used to relay SSL connections through a proxy.
396 On most proxies the dictionary port (2628) must be configured to be
397 allowed to connect through the proxy server. You will get an error
399 HTTP/1.0 500 WWWOFFLE Server Error
401 if this is not the case.
403 To enable proxy support, set the variable dictionary-use-http-proxy to
404 true. This can be done through the customize interface, there is a
405 sub-group named Dictionary Proxy of the Dictionary group. Other
406 settings you can modify are the name of the proxy server
407 (dictionary-proxy-server, Default proxy) and the port of the proxy
408 server (dictionary-proxy-port, Default 3128).
410 Support for different encodings in dictionaries
412 Although the standard definition specifies UTF-8 as character encoding
413 to be used for the protocol there exists dictionaries encoding in
414 other encodings like koi8-r for the russian language. To support these
415 dictionaries there exists starting from version 1.7 a variable named
416 dictionary-coding-systems-for-dictionaries. This is a list of cons
417 cell containing the dictionary name (as string) and the coding system
418 to use (as symbol). For modifying the variable the customize interface
419 should be used, it helps you selecting a valid charset and keeping the
420 lisp structure intact.
422 If a dictionary is not specified in this list its encoding defaults to
426 '( ("mueller" . koi8-r))
428 specifies that the koi8-r encoding should be used for the
429 english-russian dictionary internally called mueller. The internal
430 dictionary name can be found in brackets within the dictionaries
431 output buffer after the long dictionary name (for example, the output
432 From WordNet (r) 1.6[wn] specifies the internal name of the Wordnet
437 If you have an sufficient recent custom version installed (e.g., the
438 one provided in XEmacs 20.4) you can use the customize-group with the
439 dictionary group to customize this package. For using the customize
440 buffer please refer to its online help.
442 Of course you can set all the variables and hooks you want in the
443 startup file. Here is a little example that I use for selecting the
444 server on my local machine and for binding some function to the
445 user-reserved keys starting from C-c a to C-c z. It also shows how to
446 invoke popup menus (using the right button in GNU Emacs or ctrl+right
447 button in XEmacs) and installs the global tooltip-mode.
448 (global-set-key "\C-cs" 'dictionary-search)
449 (global-set-key "\C-cm" 'dictionary-match-words)
450 (setq dictionary-server "localhost")
452 ;; Popup menu for GNU Emacs 21, and XEmacs 21
453 (if (boundp 'running-xemacs)
454 (global-set-key [(control button3)] 'dictionary-mouse-popup-matching-words)
455 (global-set-key [mouse-3] 'dictionary-mouse-popup-matching-words))
457 ;; Tool-tip support for GNU Emacs 21
458 (setq dictionary-tooltip-dictionary "eng-deu")
459 (global-dictionary-tooltip-mode 1)
463 I want to thank Sam Steingold, Baoqiu Cui, Bruce Ravel, Pavel JanÃk,
464 Sergei Pokrovsky, Jeff Mincy, Serge Boiko, Enrico Scholz, Reuben
465 Thomas, Rui Zhu, Eugene Morozov, and Robert Pluim for their valuable
466 suggestions (including patches) for improving this package.
470 This file is free software; you can redistribute it and/or modify it
471 under the terms of the GNU General Public License as published by the
472 Free Software Foundation; either version 2, or (at your option) any
475 This file is distributed in the hope that it will be useful, but
476 WITHOUT ANY WARRANTY; without even the implied warranty of
477 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
478 General Public License for more details.
480 You should have received a copy of the GNU General Public License
481 version 2 along with this package; see the file GPL.
483 E-Mail: dictionary@myrkr.in-berlin.de