DictEm is a dict 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 mechanism are based on this possiblity.  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://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

* If you use shell, run

  ./configure

  for configuring dictem.
  You can also run

  ./configure --help

  to see configuring options.

* Then run

  make

  to byte-compile Emacs Lisp sources

* Finally run

  make install

  for installing dictem into the system.
  Make sure that you have necessary permissions to install dictem to
  system directories.

* 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 recomended.

REPORTING BUGS
==============

    Please send all bug reports and suggestions directly to
    Aleksey Cheusov <vle@gmx.net>

MAILING LISTS
=============

    There are no available mailing lists dedicated to DictEm.

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
--------------------

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 "/usr/local/share/emacs/emacs-site")

; Loading dictem functions
(require 'dictem)

; Setting the server host and port
(setq dictem-server "localhost")
(setq dictem-port   "2628")

; Code necessary to obtain database and strategy list
; from DICT server
(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)

-------

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)

-------

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.

-------

You can even create virtual dictionaries which consist of
databases from different DICT server.

(setq dictem-user-databases-alist
   '(("_en-ru" . ("dict://mova.org/mueller7"
                  "dict://dict.org:2628/web1913"))
     ("_ru-ru" . ("beslov" "dict://mova.org:2628/religion"))
     ))

-------

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)

-------

Of course, you can assign you can
assign your own key bendings in dictem buffer

(define-key dictem-mode-map [tab] 'dictem-next-link)
(define-key dictem-mode-map [(backtab)] 'dictem-previous-link)

-------

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)))))

-------

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)

-------

; By using dictem-run function more advanced ELISP programmers
; may create their own search scenaria. Look at this code.

(dictem-run
  'dictem-base-search
  "gcide"
  "apple"
  "lev")

(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")))))

-------

If you have read to this point and all the examples above seem easy
for you, you are probably a LISP Guru.
So, I have nothing more to tell you ;-)
Feel free to inspect the code, and I hope you found DictEm useful.