GNU Dico README
Copyright (C) 2008, 2009 Sergey Poznyakoff

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

This file contains brief information about configuring, testing
and running GNU Dico.  It is *not* intended as a replacement
for the documentation, it is provided as a brief reference only.
The (almost) 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 lower-case `d') will show you a
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
==========

Dico is an implementation of DICT server (RFC 2229).  It is fully
modular: the daemon itself (dicod) provides only the server
functionality, but it knows nothing about database formats.  Actual
searches are performed by functions supplied in loadable modules.  A
single module can serve one or more databases. 

The package includes several modules for searching in different
dictionary databases, among them a module for dict.org databases and a
module for databases in Emacs "outline" format.

A console client program, `dico', is also included.

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.

* Current state
===============

The dicod daemon is completely implemented. It provides all the
functionality required by RFC 2229, including SASL authentication.

The package comes with the following database modules:

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

- guile
 An abstract layer for interfacing with database modules written in
 Guile.

- python
 An abstract layer for interfacing with database modules written in
 Python.
 
- outline
 Support for databases in Emacs outline format. This module is
 designed mostly as an example and for testing purposes.

* 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
configuration file.  This makes the configuration extremely flexible.
We recommend to use GNU m4 as a preprocessor.  However, any other
implementation of `m4' may be used.  The `configure' script tries to
determine full file name of the preprocessor binary and the necessary
command line options.  In case it makes a wrong guess, you can instruct
it to use a particular preprocessor by using `DEFAULT_PREPROCESSOR'
configuration variable.  For example, the following `configure'
invocation instructs it to use `/usr/local/bin/gm4':

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

Note the use of `-s' preprocessor option.  It instructs `m4' to
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.

   Finally, if you do not wish to use preprocessor at all, you can
disable it using `--without-preprocessor' option to `configure'.

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

Unless given an explicit dictionary server, the client program `dico'
attempts to connect the server `dict://dico.gnu.org.ua'.  You may
change this default by defining the DEFAULT_DICT_SERVER variable.  For
example, the following command line selects dict.org as the default
server:

     $ ./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
requires Guile version 1.8.4 or newer.  The `configure' script will
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.

** Other Configure Settings
----------------------------

The `dicod' daemon uses syslog for diagnostics.  The default syslog
facility can be set using `LOG_FACILITY' configuration variable.  Its
allowed arguments are `user', `daemon', `auth', `authpriv', `mail',
`cron', and `local0' through `local7'.  Case is not significant.  In
addition, these words can be prefixed with `log_'.

By default, the `daemon' facility is used.

* Bug reporting.		

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


* Copyright information:

Copyright (C) 2008, 2009 Sergey Poznyakoff

   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: