README 7.16 KB
Newer Older
1
GNU Dico README
2
See end of file for copying conditions.
3 4 5 6 7 8

* Introduction
==============

This file contains brief information about configuring, testing
and running GNU Dico.  It is *not* intended as a replacement
9
for the documentation, but is provided as a brief reference only.
10 11 12 13 14
The complete documentation for Dico is available in doc/
subdirectory. To read it without installing the package run
`info -f doc/dico.info'. After the package is installed the
documentation can be accessed running `info Dico'.  Invoking
`info dico' and `info dicod' (with a lower-case `d') will show you a 
15 16 17 18 19 20 21 22 23
concise description of the command line syntax (similar to a man-page
style) of `dico' and `dicod' programs, correspondingly.

An online copy of the documentation in various formats is available
at http://dico.man.gnu.org.ua.

* Overview
==========

24 25 26
Dico is a flexible implementation of DICT server (RFC 2229).  The
server is modular: the daemon itself (dicod) provides only the server
functionality, and knows nothing about database formats.  Actual
27
searches are performed by functions supplied in loadable modules.  A
28
single module can handle any number of database instances. 
29 30

The package includes several modules for searching in different
31
dictionary databases, such as dict.org, WordNet and others.
32

33 34 35 36 37 38
The server can be configured to handle both anonymous and authorized
access.  It supports a wide variety of authentication algorithms.
Simpler configurations can keep the user database in plaintext files,
while more complex ones can use LDAP.

A console client program, `dico', is included.
39 40 41 42 43 44 45 46 47 48

A module for lookups in Jim Breen's Kanjidic and Edict databases will
be added in future.

* What's in a name?
===================

Dico is informal French for "Dictionary".  It is pronounced "Deekoh",
with the stress on the last syllable.

49 50
* Modules
=========
51

52
The package comes with the following modules:
53 54

- dictorg
55
  This module handles databases in dict.org format.
56

57 58 59 60 61 62 63 64 65 66 67 68
- outline
  Support for databases in Emacs outline format. This module is
  designed mostly as an example and for testing purposes.

- gcide
  GNUCIDE dictionary support.

- wordnet
  WordNet support.  WordNet is a lexical database for the English
  language, created and maintained at the Cognitive Science Laboratory
  of Princeton University.
  
69
- guile
70 71
  An abstract layer for interfacing with database modules written in
  Guile.
72 73

- python
74 75
  An abstract layer for interfacing with database modules written in
  Python.
76
 
77 78 79
- substr
  Defines the "substr" lookup strategy, which matches a supplied
  substring anywhere in the headword.
80

81 82 83 84
- stratall
  Defines a special lookup strategy, named "all", which returns all
  headwords from the database.

85 86 87 88 89 90 91
- word
  Defines the "word" lookup strategy, which matches a supplied
  word anywhere in the headword.

- pcre
  Defines a strategy for using Perl-compatible regular expressions.
  
92 93
- ldap
  Brings support for LDAP user databases.
94 95 96

- pam
  Implements PAM authentication.
97
  
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
* Building
==========

As usual:

 $ ./configure
 $ make
 $ make install
 
See INSTALL for the generic configure instructions.  The rest of this
section describes configuration options and variables specific for
Dico.

** Default Preprocessor
------------------------

The runtime configuration system uses `m4' to preprocess the
115 116 117 118
configuration file, which makes the configuration extremely flexible.
We recommend to use GNU m4 as a preprocessor, although any other
implementation of `m4' can be used as well.  The `configure' script tries to
determine the full file name of the preprocessor binary and the necessary
119
command line options.  In case it makes a wrong guess, you can instruct
120
it to use a particular preprocessor by defining the `DEFAULT_PREPROCESSOR'
121 122 123 124 125
configuration variable.  For example, the following `configure'
invocation instructs it to use `/usr/local/bin/gm4':

     $ ./configure DEFAULT_PREPROCESSOR="/usr/local/bin/gm4 -s"

126
Note the use of the `-s' preprocessor option.  It tells `m4' to
127 128 129 130 131
produce line directives which help `dicod' produce correct diagnostics
about eventual configuration errors.  Unless your `m4' implementation
does not have this feature, we recommend to always use it in
`DEFAULT_PREPROCESSOR' value.

132 133
   Finally, if you do not wish to use preprocessor at all, use
the `--without-preprocessor' option.
134 135 136 137 138

** Default Server
-----------------

Unless given an explicit dictionary server, the client program `dico'
139 140 141
attempts to connect the server `dict://dico.gnu.org.ua'.  You can
change this default by setting the DEFAULT_DICT_SERVER environment
variable to the desired server hostname.  For example:
142 143 144 145 146 147 148 149 150

     $ ./configure DEFAULT_DICT_SERVER=dict.org


** Guile Support
-----------------

The "GNU's Ubiquitous Intelligent Language for Extensions" (Guile)
can be used to write database modules for `dico'.  This
151
requires Guile version 2.2.0 or newer.  The `configure' script will
152 153 154 155 156
probe for the presence of Guile on your system and automatically enable
its use if its version number is high enough.

If you do not wish to use Guile, use `--without-guile' to disable it.

157 158 159
** WordNet database
-------------------

160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180
If you plan to use WordNet database, there are several points to be
observed.  First of all, WordNet provides static libraries, usually
with position-dependent code, which makes it difficult (or impossible,
on 64-bit architectures) to use from the shared dico modules.  So,
first of all you will need to rebuild WordNet so that it contains
position-independent code.  To do so, reconfigure it as follows:

  ./configure CFLAGS=-fPIC [other_options]

where [other_options] stands for any other options you might wish to
pass to configure.

If you are going to run this command in a source directory that has
been previously configured, it is advised to run "make distclean"
beforehand.

After configuring, run make and make install, as usual.

Once this step done, configure dico with the `--with-wordnet' option,
to inform the it about the location where WordNet libraries and
headers can be found.  For example, the command 
181 182 183

  ./configure --with-wordnet=/usr/local/WordNet-3.0

184
will instruct the configure script to look for WordNet library files in
185 186 187
/usr/local/WordNet-3.0/lib and for include files in
/usr/local/WordNet-3.0/include.

188 189 190 191
** Other Configure Settings
----------------------------

The `dicod' daemon uses syslog for diagnostics.  The default syslog
192 193 194
facility can be set using `LOG_FACILITY' configuration variable.  
Allowed arguments are `user', `daemon', `auth', `authpriv', `mail',
`cron', and `local0' through `local7' (case insensitive).
195 196 197 198 199 200 201 202 203 204

By default, the `daemon' facility is used.

* Bug reporting.		

Send bug reports to <bug-dico@gnu.org>.


* Copyright information:

205
Copyright (C) 2008-2019 Sergey Poznyakoff
206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and this permission notice are preserved,
   thus giving the recipient permission to redistribute in turn.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them.


Local Variables:
mode: outline
paragraph-separate: "[ 	]*$"
version-control: never
End: