path: root/README

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