diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 353 |
1 files changed, 353 insertions, 0 deletions
@@ -0,0 +1,353 @@ +Emacs package for talking to a dictionary server + +Introduction + +Recently I installed the dictd server, which can be used to access several +dictionaries using a simple protocol as defined in RFC 2229 (Text Version). + +As my primary working environment is XEmacs 20.4, I decided to write an +Emacs-Lisp package for accessing this dictionary server. The older +webster.el didn't worked with the newer protocol. After starting the +implementation I was pointed to an already existing implementation, but this +was basically a wrapper to the dict client program and didn't have all the +features I wanted. + +If you didn't received this file from its original location you can visit it +at http://www.in-berlin.de/User/myrkr/dictionary.html + +Features + +The dictionary mode provides the following features: + + * looking up word definitions in all dictionaries + * search for matching word + * words/phrases marked with { } in the dictionary definitions are + recognized as hyper links and browseable + * easy selection of dictionary and search strategy + * backward moving through the visited definitions + +Here is a sample screenshot showing the dictionary mode in action within a +XEmacs buffer: + +[Image] + +This buffer shows the result of searching the definition for Emacs. Two +entries have been found. The bold text on the top are buttons for selecting +action using the mouse or keyboard, the blue words are hyper links that +points to the definitions of these words. + +Installation + +Download and Requirements + +I have tested the package with a native GNU Emacs 19.34.1 and XEmacs 20.4. I +implemented some hacks to work with the very very old custom.el file in the +above GNU Emacs. Please update to the current version whenever possible. + + * Current version (1.2.1) of this package + * Version 1.1 of this package + * Version 1.0 of this package + +I you want to know more about the differences please look at the ChangeLog. + +You will need the custom package to use this package. For full support +please check if your system knows the defface function, if not please +download the current version. + +For best usuability I suggest using the mouse, but it provide good keyboard +support as well. + +Unpacking the archive + +The package is distributed as tar.gz file. You unpack it using: + +gunzip dictionary-1.2.1.tar.gz | tar xf - + +or + +tar -xzf dictionary-1.2.1.tar.gz + +(with the version number subject to change) depending on whether you are +using GNU tar which support the z flag for compression. After unpacking the +archive a directory dictionary-1.2.1 has been created containing the +necessary files. + +Byte compiling + +For faster loading and executing of the package I strongly suggest that you +bytecompile the files. Emacs user please call make within the create +subdirectory, XEmacs user has to specifiy there favorite tool using make +EMACS=xemacs. If your custom package is not up-to-date expect some warnings +about free variables. + +Installing the files + +To install the files into your GNU Emacs/XEmacs installation please copy the +*.elc files into a directory being in your load-path variable. On most +installations /usr/lib/emacs/site-lisp or /usr/local/lib/emacs/site-lisp are +suitable locations. + +Loading the package + +You have to insert some instructions into your .emacs file to load the +dictionary package whenever needed. I suggest using the following lines: + +(autoload 'dictionary-search "dictionary" + "Ask for a word and search it in all dictionaries" t) +(autoload 'dictionary-match-words "dictionary" + "Ask for a word and search all matching words in the dictionaries" t) +(autoload 'dictionary "dictionary" + "Create a new dictionary buffer" t) + +In addition, some keybindings for faster access can be useful. I use the +following ones in my installation: + +(global-set-key [(control c) ?s] 'dictionary-search) +(global-set-key [(control c) ?m] 'dictionary-match-words) + +I will describe the user-callable functions and the keybindings within +dictionary mode later in this document. + +Using the package + +Glossary + +Before I start describing how you use this package, please let me explain +some words as they are used in this text: + +word + This is a word you want to lookup in the dictionaries verbatim. +pattern + This is used for looking up matching words. A pattern can be as simple + as a single word but also as complex as a POSIX regular expression. The + meaning of a pattern depends on the strategy used for matching words. +dictionary + The server can handle serveral distinct dictionaries. You can select + specific dictionaries or ask the server to search in all dictionaries + or until matches or definitions are found. To search in all + dictionaries the special name * is used, the special name ! requests to + search until definitions are found. For more details please take a look + at the standards definition. +definition + A dictionary entry that can be the result of a word search. +search + The operation of looking up a word in the dictionaries. +match + The operation of comparing a pattern to all words in the dictionary. +strategy + While matching in a dictionary serveral methods for comparing words can + be used. These methods are named strategies and include exact match, + regualare expression match, and soundex match. The available strategies + depends on the server, but a special name . can be used to denote a + server-default strategy. + +Invoking + +There are four different (documented) ways of invoking the package. By +calling dictionary you can start a new dictionary buffer waiting for your +commands. If you want to create multiple buffers for searching the +dictionary, you can run this function muliple times. 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. + +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. + +You can have multiple independent dictionary buffer. If the above functions +are called from within dictionary mode they reuse the existing buffer. +Otherwise they create a new buffer. + +If you encounter emacs blocking forever while searching an entry and you are +using MULE you should check the value of the connection-broken-end-of-line +variable, which can be set to t in this case. + +Quitting + +Once a dictionary buffer is created you can close it by simply typing q +(dictionary-close). 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. + +Using the buffer + +After a successful search the buffer is devided 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 hyperlinks 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 +precisly). + +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). + +Searching + +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. + +Matching + +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. + +Selecting dictionary + +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. + +Selection search strategy + +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. + +Going backward + +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. + +Getting Help + +If you are totally confused what all the keys do in your dictionary buffer +some help will displayed by pressing the h key. Press q to make the help go +away. 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. + +Customizing + +If you have an sufficient recent custom version installed (e.g., the one +provided in XEmacs 20.4) you can use the customize-group with the dictionary +group to customize this package. For using the customize buffer please refer +to its online help. + +Of course you can set all the variables and hooks you want in the startup +file. Here is a little example that I use for selecting the server on my +local machine and for binding some function to the user-reserved keys +starting from C-c a to C-c z. + +(global-set-key [(control c) ?s] 'dictionary-search) +(global-set-key [(control c) ?m] 'dictionary-match-words) +(setq dictionary-server "localhost") + +Thanks + +I want to thank Sam Steingold, Baoqiu Cui, and Bruce Ravel for their +valuable suggestions (including patches) for improving this package. + +License + +This file is free software; you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free +Software Foundation; either version 2, or (at your option) any later +version. + +This file is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +details. + +You should have received a copy of the GNU General Public License version 2 +along with this package; see the file GPL. + +ChangeLogs + +Version 1.2 - 1.2.1 + + * Corrected dictionary command to draw the button bar. + * Improved documentation on dictionary to explicitly mention the use of + multiple buffers. + +Version 1.1.1 - 1.2 + + * Some users reported problems with GNU Emacs 20.3 and MULE. So I + introduced a new variable connection-broken-end-of-line which controls + whether a line is ended by \n or by \r\n. You can use the + customize-group command on dictionary to change the setting of the + variable. + +Version 1.1 - 1.1.1 + + * dictionary-search now allows editing the word to search for + * dictionary-search-word-near-point has been removed, you can use + dictionary-lookup-definition instead. It behaves like dictionary-search + but don't allow the search word to be edited (to speed up looking up + words). + +Version 1.0 - 1.1 + + * all dictionary buffers now share a single connection + * added kill-all-local-variables + * use cons instead of list where possible + * dictionary-search now: + o use word as point as default (implementing + dictionary-search-word-near-point too) + o asks for dictionary with prefix argument + * added help-echo tags which are used in XEmacs + * mark has been replaced by generic marker + * added messages for communications to the dictionary server that may + take a while + * fixed bug with going to the previous link + * replaced word-at-point by current-word + + ------------------------------------------------------------------------ +Torsten Hilbrich +Last modified: Sun May 7 11:06:16 CEST 2000 |