1
2 Emacs package for talking to a dictionary server
3
4 Introduction
5
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).
9
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
16 dictionary client.
17
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
20
21 Features
22
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
31 popup menus
32 * in GNU Emacs 21 you can lookup words by simply pointing the mouse
33 cursor to them (tool-tips)
34
35 Here are three sample screenshot showing the dictionary mode in action
36 within an Emacs 21 buffer:
37
38 This buffer shows the result of searching the definition for
39 distinguished. A lot of entries have been found, including translation
40 into german and russian language. The blue words are hyper-links that
41 points to the definitions of these words. The hyper-link with the
42 green background will be activated when pressing the middle mouse
43 button.
44
45 This buffer shows the result of looking for matching words to
46 possible. You can now select one of the found entries or ignore the
47 search by pressing any mouse button outside the menu.
48
49 This screenshot shows the tool-tips supported in GNU Emacs 21.
50 Whenever the mouse cursor stands still for a certain time (about one
51 second) the word at cursor is looked up in the configured dictionary.
52 This example shows the german translation for originally, in this
53 context not the right one, urspr�nglich would be better.
54
55 Download and Requirements
56
57 I have tested the package with a native GNU Emacs 19.34.1 and XEmacs
58 20.4. I implemented some hacks to work with the very very old
59 custom.el file in the above GNU Emacs. Please update to the current
60 version whenever possible. XEmacs 21 and Emacs 20 as well as Emacs 21
61 have been tested too.
62 * Current version (1.7.2) of this package
63 * Version 1.5.1 of this package
64 * Version 1.4.1 of this package
65 * Version 1.3.3 of this package
66 * Version 1.2.1 of this package
67 * Version 1.1 of this package
68 * Initial version (1.0) of this package
69
70 I you want to know more about the differences please look at the
71 ChangeLog.
72
73 You will need the custom package to use this package. For full support
74 please check if your system knows the defface function, if not please
75 download the current version.
76
77 For best usability I suggest using the mouse, but it provide good
78 keyboard support as well.
79
80 Unpacking the archive
81
82 The package is distributed as tar.gz file. You unpack it using:
83gzip -dc dictionary-1.7.2.tar.gz | tar xf -
84
85 or
86tar -xzf dictionary-1.7.2.tar.gz
87
88 (with the version number subject to change) depending on whether you
89 are using GNU tar which support the z flag for compression. After
90 unpacking the archive a directory dictionary-1.7.2 has been created
91 containing the necessary files.
92
93 Installation
94
95Debian
96
97 If you are using a current Debian distribution (one that support the
98 emacsen package system) and have the dpkg-dev installed (for running
99 dpkg-buildpackage) you can use the supplied debian support.
100make debian
101
102 This will create a package named dictionary-1.7.2-1_i386.deb or
103 similiar in the parent directory of dictionary-1.7.2. You can now
104 install this package as root, it will automatically byte-compile
105 itself for all installed emacs versions and provide a startup-file
106 which autoloads this package. In the configuration example given below
107 you can omit the autoload lines.
108
109 If you no longer want to use this package, you can remove it using:
110dpkg -r dictionary
111
112XEmacs 21
113
114 The XEmacs version 21 support so called xemacs packages. These
115 packages are also supported, you can create them using:
116make EMACS=xemacs package
117
118 The created package will be named dictionary-1.5-pkg.tar.gz and stored
119 within the current directory. If you don't want to install this
120 package manually, you can use the following command, provided you have
121 sufficient privileges (if unsure, login as super user):
122make EMACS=xemacs package-install
123
124 If you have more than one XEmacs versions installed make sure the
125 EMACS argument to make points to the current binary.
126
127Manually
128
129 Byte compiling
130
131 For faster loading and executing of the package I strongly suggest
132 that you byte-compile the files. Emacs user please call make within
133 the create subdirectory, XEmacs user has to specify there favorite
134 tool using make EMACS=xemacs. If your custom package is not up-to-date
135 expect some warnings about free variables.
136
137 Installing the files
138
139 To install the files into your GNU Emacs/XEmacs installation please
140 copy the *.elc files into a directory being in your load-path
141 variable. On most installations /usr/lib/emacs/site-lisp or
142 /usr/local/lib/emacs/site-lisp are suitable locations.
143
144 Loading the package
145
146 You have to insert some instructions into your .emacs file to load the
147 dictionary package whenever needed. If you installed this dictionary
148 package as Debian package or XEmacs package you don't need the
149 autoloads, they are already supplied. Other users I suggest using the
150 following lines:
151(autoload 'dictionary-search "dictionary"
152 "Ask for a word and search it in all dictionaries" t)
153(autoload 'dictionary-match-words "dictionary"
154 "Ask for a word and search all matching words in the dictionaries" t)
155(autoload 'dictionary-lookup-definition "dictionary"
156 "Unconditionally lookup the word at point." t)
157(autoload 'dictionary "dictionary"
158 "Create a new dictionary buffer" t)
159(autoload 'dictionary-mouse-popup-matching-words "dictionary"
160 "Display entries matching the word at the cursor" t)
161(autoload 'dictionary-popup-matching-words "dictionary"
162 "Display entries matching the word at the point" t)
163(autoload 'dictionary-tooltip-mode "dictionary"
164 "Display tooltips for the current word" t)
165(autoload 'global-dictionary-tooltip-mode "dictionary"
166 "Enable/disable dictionary-tooltip-mode for all buffers" t)
167
168 In addition, some key bindings for faster access can be useful. I use
169 the following ones in my installation:
170;; key bindings
171(global-set-key "\C-cs" 'dictionary-search)
172(global-set-key "\C-cm" 'dictionary-match-words)
173
174 I will describe the user-callable functions and the key bindings
175 within dictionary mode later in this document.
176
177 Using the package
178
179Glossary
180
181 Before I start describing how you use this package, please let me
182 explain some words as they are used in this text:
183
184 word
185 This is a word you want to lookup in the dictionaries verbatim.
186
187 pattern
188 This is used for looking up matching words. A pattern can be as
189 simple as a single word but also as complex as a POSIX regular
190 expression. The meaning of a pattern depends on the strategy
191 used for matching words.
192
193 dictionary
194 The server can handle several distinct dictionaries. You can
195 select specific dictionaries or ask the server to search in all
196 dictionaries or until matches or definitions are found. To
197 search in all dictionaries the special name * is used, the
198 special name ! requests to search until definitions are found.
199 For more details please take a look at the standards
200 definition.
201
202 definition
203 A dictionary entry that can be the result of a word search.
204
205 search
206 The operation of looking up a word in the dictionaries.
207
208 match
209 The operation of comparing a pattern to all words in the
210 dictionary.
211
212 strategy
213 While matching in a dictionary serveral methods for comparing
214 words can be used. These methods are named strategies and
215 include exact match, regular expression match, and soundex
216 match. The available strategies depends on the server, but a
217 special name . can be used to denote a server-default strategy.
218
219Invoking
220
221 There are five different (documented) ways of invoking the package. By
222 calling dictionary you can start a new dictionary buffer waiting for
223 your commands. If you want to create multiple buffers for searching
224 the dictionary, you can run this function multiple times.
225 dictionary-search will ask for a word a search defaulting to the word
226 at point and present all definitions found.
227
228 If you want to lookup the word near the point without further
229 confirmation use the dictionary-lookup-definition function. The last
230 one is dictionary-match-words which will ask for a pattern and display
231 all matching words.
232
233 You can also display a popup menu showing the definition for a certain
234 word. You just place the mouse cursor above the word you want to
235 lookup and press the assigned mouse button. The sample definition in
236 section Customizing binds this command to the right mouse button
237 in GNU Emacs and to ctrl + right mouse button in XEmacs. For mouse
238 invocation use dictionary-mouse-popup-matching-words, for assigning to
239 a key combination use the dictionary-popup-matching-words function.
240 The latter function search for the word located at point.
241
242 I have tested this feature in Emacs 21 and XEmacs 21. Emacs 20 do not
243 support this kind of popup menus (you will get an error message if you
244 try anyway), XEmacs 20 or prior has not been tested yet.
245
246 A new feature of version 1.5 is the tool-tip support. This will only
247 work in GNU Emacs 21, XEmacs uses a different mechanism (called
248 balloon help) which can not easily be adapted. Please note, the
249 tool-tip mode may slow down your Emacs, especially if you prefer using
250 the mouse.
251
252 First you have to define the dictionary for looking up words to
253 display in the tool-tip window. You could use * to search in all
254 dictionaries, however tool-tip window should be rather small. I use an
255 english to german dictionary for myself, which is called eng-deu (you
256 can find out the name if you look into contents of the square brackets
257 within the dictionary buffer; for example, the line From WordNet (r)
258 1.6[wn]: tells you the name of this dictionary is wn).
259(setq dictionary-tooltip-dictionary "eng-deu")
260
261 Next you have to decide if you want tool-tip support in the current
262 buffer only or in all buffers. For the first use the
263 dictionary-tooltip-mode command, for the latter
264 global-dictionary-tooltip-mode.
265;; choose on of the following lines
266(global-dictionary-tooltip-mode 1)
267(dictionary-tooltip-mode 1)
268
269 To turn the tool-tip support off, call these functions with a numeric
270 argument of 0.
271
272 If you get an error message that the server could not be contacted,
273 please check the values of the variables dictionary-server and
274 dictionary-port. The port should usually be 2628, the default server
275 as distributed is dict.org.
276
277 You can have multiple independent dictionary buffer. If the above
278 functions are called from within dictionary mode they reuse the
279 existing buffer. Otherwise they create a new buffer.
280
281Quitting
282
283 Once a dictionary buffer is created you can close it by simply typing
284 q (dictionary-close) or pressing the [Quit] button on the top.
285 Another, more cruel, way is to use the kill-buffer function which is
286 handled correctly.
287
288 The dictionary mode save the window configuration on startup and try
289 to reestablish it when the buffer is being closed.
290
291Using the buffer
292
293 After a successful search the buffer is divided into two sections. The
294 first one is the button area at the top, the other one is the text
295 buffer displaying the result. By pressing the buttons you can select
296 some functions that are otherwise inaccessible with the mouse.
297
298 In the text are each definition is introduced by the name of the
299 database that contains it. In the default configuration this text is
300 in italic face. The definition itself can contains hyper links that
301 are marked using blue foreground and both sensitive to clicking with
302 the mouse and pressing return while being within the link.
303
304 Each link selection or otherwise selected new search or match will
305 create a new buffer showing the new result. You can use the [Back]
306 button on the top or the l key (dictionary-previous) to return the
307 previous buffer contents.
308
309 Pressing Meta while clicking on a link to start the search will extent
310 the search to all dictionaries (dictionary-default-dictionary to be
311 more precisely).
312
313 If you prefer using the keyboard it can be very frustrating to use the
314 cursor key to position the point before pressing return to visit the
315 link is possible. Therefore, I defined the Tab and the n keys to jump
316 to the next link (dictionary-next-link) and the Shift-Tab and p keys
317 to jump to the previous one (dictionary-prev-link). Please note that
318 the Shift-Tab key may be the same as the Tab key when running Emacs
319 within a tty (in contrast to a windowing system like X11). There is no
320 way for a application to differ Shift-Tab from Tab in this case,
321 please use the p key to visit the previous link if you run into this
322 problem.
323
324Searching
325
326 The search operation can be invoked by using the [Search Definition]
327 button on the top or by pressing s (dictionary-search). It will ask
328 for a word to search and will default to the word near point. This
329 allows you to edit the word before starting the search. The found
330 definitions will be displayed inside the buffer. If no entries could
331 not be found an error message will be displayed.
332
333 If you want to quickly lookup the word at the point without further
334 confirmation use the d key (dictionary-lookup-definition). Except for
335 not allowing to edit the search word before asking the server it
336 behaves the same way as the normal search operation.
337
338Matching
339
340 The match operation is started upon pressing the [Matching Words]
341 button or pressing the m key (dictionary-match-words). It will use the
342 current database and the current strategy and list matching words for
343 the one you entered at the prompt. The output is grouped by dictionary
344 and each found word can be looked up by clicking the word or pressing
345 return. Please note that in some cases not only the requested
346 definition but some similiar definitions are shown. This behaviour is
347 caused by the keyword lookup in the server. E.g., when you ask for the
348 definition of from in Webster you will presented with the definitions
349 of from and Thrust, the latter includes the phrase To thrust away or
350 from which causes the display.
351
352Selecting dictionary
353
354 By default all dictionaries (special name is "*") are searched for a
355 word definition or for matching words. You can select a specific word
356 for both modi by pressing the [Select Default Dictionary] button or
357 the D key (dictionary-select-dictionary). You will get a message about
358 successful selection.
359
360 If you hold Meta while selecting a dictionary you will get more
361 information displayed instead.
362
363 If you want to restore the original behaviour select All dictionaries.
364 The first matching dictionary is a special dictionary (named "!")
365 where the search will stop at the first dictionary with found
366 definitions or matching words.
367
368Selection search strategy
369
370 While searching matching words to the pattern you entered the server
371 can use different comparison algorithm (aka search strategy). Every
372 server provides a default strategy which is internally known as ".".
373
374 After pressing the [Select Match Strategy] button or pressing the M
375 key (dictionary-select-strategy) all available strategies on this
376 server are presented. As in the "select dictionary" mode you can
377 select it by pressing the mouse button 2 or typing return.
378
379Going backward
380
381 If you visited a link and want to go back to the previous definition,
382 simply choose the [Back] button or press the l key
383 (dictionary-previous). The buffer contents and cursor position will be
384 restored. If you intented to go beyond the first definition an error
385 message will appear.
386
387Getting Help
388
389 If you are totally confused what all the keys do in your dictionary
390 buffer some help will displayed by pressing the h key. Within XEmacs
391 you can exit the help screen by pressing q, in GNU Emacs you have to
392 switch to the help window using C-x o (other-window) first. This help
393 buffer will display the default key bindings only as I had problems
394 with displaying multiple bindings for a single function (e.g., both
395 button2 and return select a link). Any suggestions are welcome.
396
397Proxy support
398
399 Starting from version 1.6 (not officially released) the dictionary
400 client supports connections via HTTP proxies. It uses the CONNECT
401 method which is usually used to relay SSL connections through a proxy.
402 On most proxies the dictionary port (2628) must be configured to be
403 allowed to connect through the proxy server. You will get an error
404 message like:
405HTTP/1.0 500 WWWOFFLE Server Error
406
407 if this is not the case.
408
409 To enable proxy support, set the variable dictionary-use-http-proxy to
410 true. This can be done through the customize interface, there is a
411 sub-group named Dictionary Proxy of the Dictionary group. Other
412 settings you can modify are the name of the proxy server
413 (dictionary-proxy-server, Default proxy) and the port of the proxy
414 server (dictionary-proxy-port, Default 3128).
415
416Support for different encodings in dictionaries
417
418 Although the standard definition specifies UTF-8 as character encoding
419 to be used for the protocol there exists dictionaries encoding in
420 other encodings like koi8-r for the russian language. To support these
421 dictionaries there exists starting from version 1.7 a variable named
422 dictionary-coding-systems-for-dictionaries. This is a list of cons
423 cell containing the dictionary name (as string) and the coding system
424 to use (as symbol). For modifying the variable the customize interface
425 should be used, it helps you selecting a valid charset and keeping the
426 lisp structure intact.
427
428 If a dictionary is not specified in this list its encoding defaults to
429 UTF-8.
430
431 The default setting
432 '( ("mueller" . koi8-r))
433
434 specifies that the koi8-r encoding should be used for the
435 english-russian dictionary internally called mueller. The internal
436 dictionary name can be found in brackets within the dictionaries
437 output buffer after the long dictionary name (for example, the output
438 From WordNet (r) 1.6[wn] specifies the internal name of the Wordnet
439 dictionary being wn.
440
441 Customizing
442
443 If you have an sufficient recent custom version installed (e.g., the
444 one provided in XEmacs 20.4) you can use the customize-group with the
445 dictionary group to customize this package. For using the customize
446 buffer please refer to its online help.
447
448 Of course you can set all the variables and hooks you want in the
449 startup file. Here is a little example that I use for selecting the
450 server on my local machine and for binding some function to the
451 user-reserved keys starting from C-c a to C-c z. It also shows how to
452 invoke popup menus (using the right button in GNU Emacs or ctrl+right
453 button in XEmacs) and installs the global tooltip-mode.
454(global-set-key "\C-cs" 'dictionary-search)
455(global-set-key "\C-cm" 'dictionary-match-words)
456(setq dictionary-server "localhost")
457
458;; Popup menu for GNU Emacs 21, and XEmacs 21
459(if (boundp 'running-xemacs)
460 (global-set-key [(control button3)] 'dictionary-mouse-popup-matching-words)
461 (global-set-key [mouse-3] 'dictionary-mouse-popup-matching-words))
462
463;; Tool-tip support for GNU Emacs 21
464(setq dictionary-tooltip-dictionary "eng-deu")
465(global-dictionary-tooltip-mode 1)
466
467 Thanks
468
469 I want to thank Sam Steingold, Baoqiu Cui, Bruce Ravel, Pavel Jan�k,
470 Sergei Pokrovsky, Jeff Mincy, Serge Boiko, Enrico Scholz, Reuben
471 Thomas, Rui Zhu, Eugene Morozov, and Robert Pluim for their valuable
472 suggestions (including patches) for improving this package.
473
474 License
475
476 This file is free software; you can redistribute it and/or modify it
477 under the terms of the GNU General Public License as published by the
478 Free Software Foundation; either version 2, or (at your option) any
479 later version.
480
481 This file is distributed in the hope that it will be useful, but
482 WITHOUT ANY WARRANTY; without even the implied warranty of
483 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
484 General Public License for more details.
485
486 You should have received a copy of the GNU General Public License
487 version 2 along with this package; see the file GPL.
488
489 ChangeLogs
490
491Version 1.7.1 - 1.7.2
492
493 * link.el (link-initialize-keymap): fixed keybinding bug (reported
494 by David A. Panariti)
495
496Version 1.7 - 1.7.1
497
498 * fixed mule-detection in dictionary-coding-system (patch submitted
499 by Robert Pluim)
500
501Version 1.5.1 - 1.7
502
503 * added HTTP proxy support (using the CONNECT method)
504 * added support for dictionaries not encoded in utf-8 (suggested by
505 Eugene Morozov)
506
507Version 1.5 - 1.5.1
508
509 * fixed bug with non-working dictionary-previous (found by Rui Zhu)
510 * fixed key bindings in link.el
511
512Version 1.4.1 - 1.5
513
514 * tool-tip support for GNU Emacs 21
515
516Version 1.4 - 1.4.1
517
518 * changed recognition of utf-8 support (suggested by Enrico Scholz)
519
520Version 1.3.3 - 1.4
521
522 * added popup menu for easier lookup of words
523
524Version 1.3.2 - 1.3.3
525
526 * added support for XEmacs 21 packages to ease installation for
527 those users (suggested and reviewed by Enrico Scholz)
528
529Version 1.3.1 - 1.3.2
530
531 * replaced set-text-properties by remove-text-properties and
532 add-text-properties because this function is not recommended
533 within XEmacs (reported by Serge Boiko)
534
535Version 1.3 - 1.3.1
536
537 * small fix in dictionary function to check for availability of the
538 utf-8 encoding to prevent problems in certain xemacs versions
539 (reported by Jeff Mincy)
540 * added debian support (use dpkg-buildpackage to build a package)
541
542Version 1.2.1 - 1.3
543
544 * Implemented an automatic detection for line ends CR/LF and LF. The
545 variable connection-broken-end-of-line is no longer necessary and
546 its value ignored.
547 * Added utf-8 support, the native character set of the dictionary
548 protocol. Using ISO-8859-1 (aka latin-1) was just a necessary
549 work-around.
550
551Version 1.2 - 1.2.1
552
553 * Corrected dictionary command to draw the button bar.
554 * Improved documentation on dictionary to explicitly mention the use
555 of multiple buffers.
556
557Version 1.1.1 - 1.2
558
559 * Some users reported problems with GNU Emacs 20.3 and MULE. So I
560 introduced a new variable connection-broken-end-of-line which
561 controls whether a line is ended by \n or by \r\n. You can use the
562 customize-group command on dictionary to change the setting of the
563 variable.
564
565Version 1.1 - 1.1.1
566
567 * dictionary-search now allows editing the word to search for
568 * dictionary-search-word-near-point has been removed, you can use
569 dictionary-lookup-definition instead. It behaves like
570 dictionary-search but don't allow the search word to be edited (to
571 speed up looking up words).
572
573Version 1.0 - 1.1
574
575 * all dictionary buffers now share a single connection
576 * added kill-all-local-variables
577 * use cons instead of list where possible
578 * dictionary-search now:
579 + use word as point as default (implementing
580 dictionary-search-word-near-point too)
581 + asks for dictionary with prefix argument
582 * added help-echo tags which are used in XEmacs
583 * mark has been replaced by generic marker
584 * added messages for communications to the dictionary server that
585 may take a while
586 * fixed bug with going to the previous link
587 * replaced word-at-point by current-word
588 _________________________________________________________________
589
590 E-Mail: dictionary@myrkr.in-berlin.de
591 Last modified: Fri Dec 21 18:51:23 CET 2001
592