File: README

package info (click to toggle)
dictem 1.0.4-4.1
  • links: PTS
  • area: main
  • in suites: bookworm, bullseye, sid
  • size: 172 kB
  • sloc: lisp: 1,661; sh: 38; makefile: 36
file content (558 lines) | stat: -rw-r--r-- 16,787 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
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! ;-)