DictEm is a Dictionary protocol client for GNU Emacs. It uses a console dict client (http://sf.net/projects/dict) and implements all functions of the client part of DICT protocol (RFC-2229, www.dict.org), i.e. looking up words and definitions, obtaining information about available strategies, provided databases, information about DICT server etc. Unlike dictionary.el (http://www.myrkr.in-berlin.de/dictionary/index.html) DictEm widely uses autocompletion that is used for selecting dictionary and search strategy. Moreover, DictEm provides several hooks which may be used for buffer postprocessing. For example, inbuilt hyperlinking and highlighting mechanisms are based on this possibility. Another example is that information obtained from DICT server that is in HTML, ROFF or INFO format can be easily viewed by Emacs+DictEm if the user supplies appropriate conversion functions. Of course DictEm can be differently configured for different Emacs modes (major, minor or buffer oriented), that allows modularized access to all data serviced by DICT servers. This makes it ideal tool for translating articles between a series of foreign languages, browsing manuals and other tasks depending on Emacs mode user currently works with. Additionally DictEm supports accessing so called virtual dictionaries (a set of dictionaries provided by DICT server that user prefers to treat as a single one). Yet another feature DictEm provides is a set of useful functions with a help of which user can extend DictEm functionality such as to define new search strategies or even provide new functionality such as to use another sources of data other than DICT servers. See below for a set of example configuration and extensions. Also DictEm uses customization mechanism provided by Emacs that helps Emacs users to easily configure DictEm. COPYING ============ See the file COPYING DOWNLOAD ======== Latest sources can be downloaded from http://sourceforge.net/projects/dictem or http://freshmeat.net/projects/dictem INSTALLATION ============ * In order to uncompress dictem tarball run the following. tar xfv dictem-x.y.z.tar.gz If you read this file, you probably have already done this. * Change your current directory to dictem. cd dictem-x.y.z * Copy *.el file to the directory you want. cp *.el /path/to/emacs/el/files * Make sure that DICT client named dict (available at http://sf.net/projects/dict) is installed on your system. Console dict client is used by DictEm for accessing the DICT server. dict-1.9.14 or later is strongly recommended. If you'll set dictem-option-mime variable to t (read below), dict-1.10.3 or later MUST be used. REPORTING BUGS ============== Please send all bug reports and suggestions directly to Aleksey Cheusov <vle@gmx.net>. Reporting bugs at sf.net is also good. Also note that there exists dict-beta@dict.org mailing list (low traffic) where you can ask questions about DICT protocol and software. CONFIGURING ============= Customization group ------------------- Take note, that DictEm defines customization group "dictem". So, it may be easier for you to customize DictEm by running M-x customize-group <RET> dictem <RET> Manual Configuration -------------------- Ex.1 The easiest configuration of dictem may look like this ; Add to load-path variable a new directory with files of dictem (add-to-list 'load-path "/path/you/installed/dictem/to") ; Loading dictem functions (require 'dictem) ; Setting the dictionary server hostname. ; This part is optional, if dictem-server is nil (the default value) ; "dict" command line utility will use its ows config file ; ~/.dictrc or PREFIX/etc/dict.conf. ; Keeping dictem-server variable unset is recomended because ; this allows to try _list of_ servers until connection is made, ; see dict(1) for details. ;(setq dictem-server "localhost") ;(setq dictem-server "dict.org") ; Setting the dictionary server port. ; Setting dictem-port is usually not necessary because ; most DICT servers use the default port 2628. ;(setq dictem-port "2628") ; Code necessary to obtain database and strategy list from DICT ; server. As of version 0.90, dictem runs this function from ; dictem-select-database and dictem-select-strategy if an ; initialization was not completed or failed previously, that is ; running dictem-initialize is optional (dictem-initialize) ; Assigning hot keys for accessing DICT server ; SEARCH = MATCH + DEFINE ; Ask for word, database and search strategy ; and show definitions found (global-set-key "\C-cs" 'dictem-run-search) ; MATCH ; Ask for word, database and search strategy ; and show matches found (global-set-key "\C-cm" 'dictem-run-match) ; DEFINE ; Ask for word and database name ; and show definitions found (global-set-key "\C-cd" 'dictem-run-define) ; SHOW SERVER ; Show information about DICT server (global-set-key "\C-c\M-r" 'dictem-run-show-server) ; SHOW INFO ; Show information about the database (global-set-key "\C-c\M-i" 'dictem-run-show-info) ; SHOW DB ; Show a list of databases provided by DICT server (global-set-key "\C-c\M-b" 'dictem-run-show-databases) ------- Ex.2 There are a few functions that can make dictem look a bit nicer and be more functional. They should be added to special hooks like the following. ; For creating hyperlinks on database names ; and found matches. ; Click on them with mouse-2 (add-hook 'dictem-postprocess-match-hook 'dictem-postprocess-match) ; For highlighting the separator between the definitions found. ; This also creates hyperlink on database names. (add-hook 'dictem-postprocess-definition-hook 'dictem-postprocess-definition-separator) ; For creating hyperlinks in dictem buffer ; that contains definitions. (add-hook 'dictem-postprocess-definition-hook 'dictem-postprocess-definition-hyperlinks) ; For creating hyperlinks in dictem buffer ; that contains information about a database. (add-hook 'dictem-postprocess-show-info-hook 'dictem-postprocess-definition-hyperlinks) ------- Ex.3 If you want to combine some databases in you own "virtual" dictionary, create them like this (setq dictem-user-databases-alist '(("_en-ru" . ("mueller7" "korolew_en-ru")) ("_en-en" . ("foldoc" "gcide" "wn")) ("_ru-ru" . ("beslov" "ushakov" "ozhegov" "brok_and_efr")) ("_unidoc" . ("susv3" "man" "info" "howto" "rfc")) )) As a result four new special database collections will be created and new names will appear when dictem-run function will ask you about database name. ------- Ex.4 You can even create virtual dictionaries which consist of databases from different DICT server. The dict url form dict:///religion means 'dict' command line tool will be called without -h option, i.e. a list of dictionary servers from .dictrc (or dict.conf) will be used. (setq dictem-user-databases-alist '(("_en-ru" . ("dict://mova.org/mueller7" "dict://dict.org:2628/web1913")) ("_ru-ru" . ("beslov" "dict:///religion")) )) another example: (setq dictem-user-databases-alist `(("en-en" . ("dict://dict.org:2628/english")) ("en-ru" . ("dict:///en-ru" "dict://dict.org:2628/eng-rus" )) )) ------- Ex.5 If your DICT server provides too many databases and most of which are of no interest for you, you can disable them and use only those specified in dictem-user-databases-alist variable. (setq dictem-use-user-databases-only t) ------- Ex.6 Of course, you can assign your own key bindings in dictem buffer (define-key dictem-mode-map [tab] 'dictem-next-link) (define-key dictem-mode-map [(backtab)] 'dictem-previous-link) ------- Ex.7 You are not limited to the default DICT server only. The following code will allow you to access any server you want. You'll be asked for host and port. ; DEFINE (global-set-key "\C-c\M-d" '(lambda () (interactive) (save-dictem (let* ((dictem-server (read-string "server: " dictem-server nil "dict.org")) (dictem-port (read-string "port: " (dictem-get-port) nil "2628"))) (dictem-initialize) (call-interactively 'dictem-run-define))))) ; MATCH (global-set-key "\C-c\M-m" '(lambda () (interactive) (save-dictem (let* ((dictem-server (read-string "server: " dictem-server nil "dict.org")) (dictem-port (read-string "port: " (dictem-get-port) nil "2628"))) (dictem-initialize) (call-interactively 'dictem-run-match))))) ; SEARCH = MATCH+DEFINE (global-set-key "\C-c\M-s" '(lambda () (interactive) (save-dictem (let* ((dictem-server (read-string "server: " dictem-server nil "dict.org")) (dictem-port (read-string "port: " (dictem-get-port) nil "2628"))) (dictem-initialize) (call-interactively 'dictem-run-search))))) ; SHOW INFO (global-set-key "\C-c\M-i" '(lambda () (interactive) (save-dictem (let* ((dictem-server (read-string "server: " dictem-server nil "dict.org")) (dictem-port (read-string "port: " (dictem-get-port) nil "2628"))) (dictem-initialize) (call-interactively 'dictem-run-show-info))))) ; SHOW SERVER (global-set-key "\C-c\M-r" '(lambda () (interactive) (save-dictem (let* ((dictem-server (read-string "server: " dictem-server nil "dict.org")) (dictem-port (read-string "port: " (dictem-get-port) nil "2628"))) (dictem-initialize) (call-interactively 'dictem-run-show-server))))) ------- Ex.8 Some databases may have specially formatted definitions, for example, HTML, MIME, DICF or ROFF formats. It is easy to postprocess them. ; All functions from dictem-postprocess-each-definition-hook ; will be run for each definition which in turn will be narrowed. ; Current database name is kept in dictem-current-dbname variable. ; The following code demonstrates how to highlight SUSV3 and ROFF ; definitions. (add-hook 'dictem-postprocess-definition-hook 'dictem-postprocess-each-definition) ; Function for highlighting definition from the database "susv3". (defun dictem-highlight-susv3-definition () (cond ((string= "susv3" dictem-current-dbname) (goto-char (point-min)) (while (search-forward-regexp "^ *[QWERTYUIOPASDFGHJKLZXCVBNM ]+$" nil t) (put-text-property (match-beginning 0) (match-end 0) 'face 'bold) )))) ; Function to show roff-formatted text from the database "man". (require 'woman) (defun dictem-highlight-man-definition () (cond ((string= "man" dictem-current-dbname) (goto-char (point-min)) (while (search-forward-regexp "^ " nil t) (replace-match "")) (goto-char (point-min)) (forward-line 2) (woman-decode-region (point) (point-max)) ))) (add-hook 'dictem-postprocess-each-definition-hook 'dictem-highlight-susv3-definition) (add-hook 'dictem-postprocess-each-definition-hook 'dictem-highlight-man-definition) ------- Ex.9 ; The dictem's top level function is 'dictem-run'. ; By using it more advanced ELISP programmers ; can create their own search scenaria. Look at this code. (dictem-run 'dictem-base-search "gcide" "apple" "lev") (dictem-run 'dictem-base-match "dict://mova.org/mueller7" "apple" "exact") (dictem-run 'dictem-base-define '("dict://mova.org/mueller7" "dict://dict.org/gcide") "apple" "exact") (dictem-run 'dictem-base-show-info "dict://dict.org/gcide") (let ((dictem-server "localhost")) (dictem-run '(lambda (a b c) (dictem-base-show-strategies nil nil nil) (dictem-base-show-databases nil nil nil) (dictem-base-show-server nil nil nil) ))) (dictem-run '(lambda (a b c) (dictem-base-define '("man" "susv3") (dictem-read-query (thing-at-point 'word)) nil )) nil nil) (let ((query (dictem-read-query (thing-at-point 'word)))) (dictem-run `((lambda (a b c) (dictem-base-match '("gcide" "wn") ,query "exact")) (lambda (a b c) (dictem-base-search '("mueller7" "korolew_en-ru") ,query "word"))))) ------- Ex.10 By default dictem remembers the database name and strategy that was used last time. The dictem-select-database and dictem-select-strategy functions will use these values as a default in the minibuffer. If you dislike this behaviour, set variables dictem-default-database and/or dictem-default-strategy. (add-hook 'c-mode-common-hook '(lambda () (interactive) (make-local-variable 'dictem-default-database) (setq dictem-default-database "man") )) The example above sets default database to "man" in C buffers. ------- Ex.11 As of dictem-0.0.4 dictem-empty-initial-input customizable variable tells dictem-read-query whether to leave initial input empty or not. It is `nil' by default. For emulating behaviour of older releases, set it to `t'. (setq dictem-empty-initial-input t) ------- Ex. 12 By default dictem-postprocess-definition-hyperlinks function assumes that hyperlinks have the following form: {foo} or {foo|bar}. Sometimes "{" and "}" characters are general characters in definitions. The following code changes "{" and "}" for "{link-beg " and " link-end" respectively inside definitions obtained from the databases "^infopage-..." ; new function is used for creating hyperlinks ; which works differently depending on database name (defun my-dictem-postprocess-definition-hyperlinks () "Creating hyperlinks according to database name" (interactive) (cond ( ((string-match "^infopage-" dictem-current-dbname) (let ((dictem-hyperlink-beginning "{link-beg ") (dictem-hyperlink-end " link-end}") ) (dictem-postprocess-definition-hyperlinks))) (t (dictem-postprocess-definition-hyperlinks))))) ; definitions from each database are processed separately (add-hook 'dictem-postprocess-definition-hook 'dictem-postprocess-each-definition) (add-hook 'dictem-postprocess-each-definition-hook 'my-dictem-postprocess-definition-hyperlinks) ------- Ex. 13 You may want to remove "XXX definition[s] found" header from the DEFINE buffers. It may be done with a help of dictem-postprocess-definition-remove-header function. (add-hook 'dictem-postprocess-definition-hook 'dictem-postprocess-definition-remove-header) ------- Ex. 14 As of version 0.7 dictem can handle dictionaries defined by user. This allows to use dictem not only for accessing DICT servers, but also for accesing users' databases. ; DEFINE function for the database "mysuperdb" (defun dictem-mysuperdb-DEFINE (query) (cond ((string= query "apple") '("Apples grow on the trees" "Apple may be green, yellow or red")) ((string= query "potato") '("Potato is a vegetable" "Potato is a traditional Belarusian food")) (t (dictem-make-error 20 (format "No definitions for %s" query))) )) ; MATCH function for the database "mysuperdb" (defun dictem-mysuperdb-MATCH (query strategy) ; the name of strategy is ignored (let ((apple (string-match query "apple")) (potato (string-match query "potato"))) (cond ((and (string= strategy "exact") (string= query "apple")) '("apple")) ((and (string= strategy "exact") (string= query "potato")) '("potato")) ((and apple potato) '("apple" "potato")) (apple '("apple")) (potato '("potato")) (t (dictem-make-error 20 (format "No matches for %s/%s" query strategy))) ))) ; Initializing a list of user-defined databases (setq dictem-user-databases-alist `(("_en-en" . ("foldoc" "gcide" "wn")) ("_ru-ru" . ("beslov" "ushakov" "ozhegov" "brok_and_efr")) ,(dictem-make-userdb ; the name of the database "mysuperdb" ; short description "My super database" ; MATCH function (symbol-function 'dictem-mysuperdb-MATCH) ; DEFINE function (symbol-function 'dictem-mysuperdb-DEFINE)) )) ------- Ex. 15 Last years many dictionary servers provide too many bilingual dictionaries, most of which may be not very interesting for you. DictEm allows to exclude such dictionaries from an autocompletion menu by setting a list of regular expressions in dictem-exclude-databases variable. If, for example, you don't speak french and german and use dict://dict.org server, your config may look like this (setq dictem-server "dict.org") (setq dictem-exclude-databases '("ger-" "-ger" "fra-" "-fra")) (dictem-initialize) Note that, (dictem-initialize) is placed after initializing dictem-exclude-databases variable. ------- If you have read to this point and all the examples above seem easy, you are probably a ELISP Guru. So, I have nothing more to tell you ;-) Feel free to inspect the code, and I hope you'll find DictEm useful. Dict'em All! ;-)