File: dico.texi

package info (click to toggle)
dico 2.12-4
links: PTS, VCS
area: main
in suites: forky, sid
size: 21,300 kB
sloc: ansic: 94,671; sh: 52,520; lex: 4,023; tcl: 1,439; yacc: 1,439; makefile: 1,387; python: 1,310; perl: 1,200; lisp: 489; awk: 157; pascal: 127; javascript: 71; cpp: 50; fortran: 28; asm: 21; sed: 16; xml: 8
file content (7061 lines) | stat: -rw-r--r-- 220,260 bytes
parent folder | download | duplicates (2)
\input texinfo @c -*-texinfo-*-
@smallbook
@c %**start of header
@setfilename dico.info
@settitle GNU Dico Manual
@c %**end of header
@setchapternewpage odd

@defcodeindex pr
@defcodeindex op
@defcodeindex kw
@defcodeindex fl

@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@syncodeindex op cp
@syncodeindex pr cp
@syncodeindex kw cp
@syncodeindex fl cp

@include version.texi
@include rendition.texi
@include macros.texi

@ifinfo
@dircategory Dictionary
@direntry
* Dico: (dico).              A modular dictionary server package.
* dicod: (dico) Dicod.       Dictionary server program.
* dico: (dico) dico client.  Dictionary client program.
@end direntry
@end ifinfo

@copying
Published by the Free Software Foundation,
31 Milk Street,
Boston, MA 02196 USA 

Copyright @copyright{} 2008--2024 Sergey Poznyakoff

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover, and no Back-Cover texts.
A copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end copying

@titlepage
@title GNU Dico Manual
@subtitle version @value{VERSION}, @value{UPDATED}
@author Sergey Poznyakoff.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@headings off
@ifnothtml
@page
@w{ }
@sp 9
@end ifnothtml
@quotation
@i{D@'edi@'e @`a la m@'emoire de Jacques Brel.}
@end quotation
@ifnothtml
@w{ }
@page
@w{ }
@page
@end ifnothtml
@headings on

@ifnothtml
@page
@summarycontents
@page
@end ifnothtml
@contents

@ifnottex
@node Top
@top Dico Manual

This edition of the @cite{GNU Dico Manual}, last updated @value{UPDATED},
documents Dico Version @value{VERSION}.

@end ifnottex

@menu
* Preface::
* Overview::
* Intro::                Introduction to Dico.
* Building::             Building the Package.
* Dicod::                The dicod daemon.
* Modules::              Dicod modules shipped with Dico.
* Interface::            How to write your own Dico module.
* dico client::          The client program.
* gcider::               A window-based browser for GCIDE.
* Reporting Bugs::       How to Report a Bug.

Appendices

* Available Strategies::
* Dictionary Server Protocol::
* Time and Date Formats::
* Libdico::
* Copying This Manual::  The GNU Free Documentation License.
* Concept Index::        Index of Concepts.
@ifset WEBDOC
@ifhtml
* This Manual in Other Formats::
@end ifhtml
@end ifset

@detailmenu
 --- The Detailed Node Listing ---

Building the Package

* Default Preprocessor::
* Default Server::
* Guile Support::
* Python Support::
* Other Settings::

The @command{dicod} daemon.

* Daemon Mode::
* Inetd Mode::
* Configuration::
* Exit Codes::
* Dicod Invocation::

Configuration

* Syntax::               Configuration file syntax.
* Server Settings::
* Authentication::
* SASL::                 SASL Authentication.
* ACL::                  Access Control Lists
* Security Settings::
* Logging and Debugging::
* Access Log::
* General Settings::
* Capabilities::
* Handlers::
* Databases::
* Strategies and Default Searches::
* Tuning::
* Command Aliases::
* Preprocessor::         Using preprocessor to improve the configuration.

Configuration File Syntax

* Comments::
* Pragmatic Comments::
* Statements::

Authentication

* text userdb::       Flat Text Databases.
* ldap userdb::       LDAP Databases.

Databases

* Input Conversions::
* Database Visibility::
* Virtual Databases::

Dicod Invocation

* Operation Mode::
* Help Options::
* Modifier Options::
* Preprocessor Control::
* Debugging Options::

Modules

* outline::
* dictorg::
* gcide::
* wordnet::
* guile::
* python::
* stratall::
* substr::
* word::
* nprefix::
* metaphone2::
* pcre::
* ldap::
* pam::
* greek_kbd::

@command{Gcide}

* idxgcide::

@command{Guile}

* Virtual Functions::
* Guile Initialization::
* Guile API::
* Dico Scheme Primitives::
* Example Module::

@command{Python}

* Dictionary Class::
* Dico Python Primitives::
* Python Example::    An Example of Python Module

Dico Python Primitives

* DicoSelectionKey::
* DicoStrategy::

Dico Module Interface

* dico_database_module::
* Strategies::
* Output::
* Unit Testing::

Strategies

* Key::
* Selector::

Dico --- a client program.

* Single Query Mode::
* Interactive Mode::
* Initialization File::
* Autologin::
* Dico invocation::

Single Query Mode

* dico options::
* urls::

Interactive Mode

* Server Commands::
* Database and Strategy::
* Informational Commands::
* History Commands::
* Pager::
* Program Settings::
* Session Transcript::
* Other Commands::
* Command Summary::

Dictionary Server Protocol

* Initial Reply::
* Standard Commands::
* Extended Commands::

Standard Commands

* DEFINE::
* MATCH::
* SHOW::
* OPTION::
* AUTH::
* CLIENT::
* STATUS::
* HELP::
* QUIT::

The Libdico Library

* strat::
* argcv::
* lists::
* assoc::
* diag::
* filter::
* parseopt::
* stream::
* url::
* utf8::
* util::
* xlat::

UTF-8

* Character sizes::
* Iterating over UTF-8 strings::
* Conversions::
* Comparing UTF-8 strings::
* Character lookups::
* Functions for converting UTF-8 characters::
* Additional functions::

@end detailmenu
@end menu

@node Preface
@unnumbered Preface
  A @dfn{dictionary server} is a program that provides dictionary
services to other computers using the client-server model.  The
dictionary services include listing the available databases, searching
for a specific term in one or more databases, displaying the definitions
found, etc.  

  GNU Dico is an implementation of dictionary server, which supports a
wide variety of database formats and is easily extensible using
several scripting languages.  Apart from the server itself, the package
contains a console dictionary client program (@pxref{dico client}),
a web interface for the server (@code{dicoweb}), and a window-based
browser for GCIDE dictionary (@pxref{gcider}).  A sister project
@uref{https://www.gnu.org.ua/software/dico/dicodock, dicodock}
provides containerized environment for running the server and web
interface for it.

@node Overview
@chapter Overview
@cindex database
@cindex headword
@cindex article
  A dictionary server operates on a set of @dfn{databases}.  Each database
contains a set of @dfn{headwords} with corresponding @dfn{articles},
therefore it can be regarded as a dictionary, in which articles supply
definitions (or translations) for headwords.

  The server offers facilities for searching headwords in the
databases and for fetching articles from them.

  This chapter provides an overview of the dictionary protocol and
defines basic terms and notions used throughout this manual.

  When describing the protocol, the following typographic conventions
are used: the data sent by the client are prefixed with @samp{C:} and
the data sent in response by the server are prefixed with @samp{S:}.

@cindex name, database
@cindex database name
@cindex information, database
@cindex database description
@cindex description, database
@cindex database description
  Each database has a unique name -- a string of characters that serves
to identify this particular database in a set of available databases.
Two more pieces of textual data are associated with a database.  The
@dfn{database information} string (or @dfn{info}, for short), supplies
a short description of the database.  It is a sentence, tersely
describing the database, e.g.@: @samp{English-German Dictionary}.  The
@dfn{database description} provides a full description of the
dictionary, with author credits and copyright information.  The length
of this description is not limited.

  Both pieces of information can be requested by the remote user.  The
command @code{SHOW DB} lists all available databases along with their
descriptions:

@example
C: SHOW DB
S: 110 3 databases present
S: jargon "Jargon File (4.3.1, 29 Jun 2001)"
S: deu-eng "German-English Freedict dictionary"
S: en-pl-naut "English-Polish dictionary of nautical terms"
S: .
S: 250 ok
@end example

Each line of output lists a name of the dictionary, and the
corresponding description.

The @code{SHOW INFO} command displays full information about a
database, whose name is given as its argument:

@example
C: SHOW INFO en-pl-naut
S: 112 information for en-pl-naut
S: English-Polish dictionary of nautical terms
S: 
S: Permission is granted to copy, distribute and/or modify 
S: this document under the terms of the GNU Free Docu-
S: mentation License, Version 1.2 or any later version 
S: published by the Free Software Foundation; with no 
S: Invariant Sections, no Front-Cover and Back-Cover Texts
S: .
S: 250 ok
@end example

  A definition for any given headword can be requested using the
@code{DEFINE} command.  It takes two arguments, the name of the
database and the headword to look for in that database, e.g.:

@example
DEFINE en-pl-naut sprit
@end example

If the headword is found in the database, its definition is
displayed, otherwise a diagnostic message is returned, telling
that the headword was not found.

@cindex strategy
A special mechanism is provided for looking up the headword in a
database (or databases).  The @code{MATCH} command returns 
headwords that match a given string (a @dfn{search key}) using a
particular @dfn{strategy}.  In other words, a strategy identifies the
algorithm for comparing two strings: a headword and the search key.  
A strategy is identified by its name.  For example, the strategy 
@samp{exact} means literal comparison and returns only those headwords 
that match the key exactly.  The strategy @samp{prefix} matches word 
prefixes.  These two strategies are always present.  Depending on 
the configuration, the server may offer other strategies as well.  
@xref{Available Strategies}, for a complete list of strategies 
implemented in GNU Dico @value{VERSION}.

@anchor{default strategy}
@cindex default strategy
@cindex strategy, default
One of the strategies is selected as a @dfn{default strategy}.
Usually such strategy tolerates possible typing errors and allows the
user to find matching headwords even if he does not know exactly how
the word in question is spelled.  The default strategy is denoted as
@samp{.} (a dot).

The @code{MATCH} command takes three arguments: the name of the
database to search, the strategy and the search key.  For example:

@example
S: MATCH wn prefix sail
C: 152 4 matches found: list follows
C: wn "sail"
C: wn "sail through"
C: wn "sailboat"
C: wn "sailcloth"
C: .
C: 250 Ok
@end example

Two database names are special.  The @samp{*} means search in all
databases and return all matches.  The @samp{!} means search in all
databases until the match is found in one of them and return only
matches from that particular database. 

These are basic facilities provided by the DICT protocol.  For a
complete and detailed description of the protocol, see @ref{Dictionary
Server Protocol}.

@node Intro
@chapter Introduction to GNU Dico
@cindex Dico overview
@cindex two-layer model
@cindex protocol layer
@cindex database layer
@cindex RFC 2229
@cindex DICT protocol
GNU Dico is an implementation of @acronym{DICT} dictionary server
(described in @acronym{RFC} 2229) and a set of accompanying utilities.
The GNU Dico server uses two-layer model.  The @dfn{protocol
layer} is responsible for the correct @acronym{DICT} protocol dialog and
is provided by the @command{dicod} server binary.  The @dfn{database
layer} is responsible for searching and retrieving data from dictionary 
databases.  This layer is provided by external @dfn{loadable modules}.  
Thus, Dico does not impose any specific dictionary database format.  
A single server can handle databases in various formats, provided that
appropriate modules are available.  Several database modules are
shipped with GNU Dico.  The following is a short introductions for
some of them.  @xref{Modules}, for a complete list of available
modules with detailed descriptions.

@table @asis
@item dictorg
@cindex dictorg database format
  This module provides full support for the format designed by
the @cite{@acronym{DICT} development group} (@uref{http://dict.org}).
This is a @i{de facto} standard for @acronym{DICT} databases.  A
number of dictionary databases in this format are provided by the
@cite{FreeDict} project (@uref{http://freedict.org}).

@item wordnet
@cindex wordnet
  Support for @samp{WordNet} databases.  WordNet is a lexical
database for the English language developed in the Princeton
University and distributed under a BSD style license.

@item gcide
@cindex gcide
@cindex GNU Collaborative International Dictionary of English
@cindex Patrick J.@: Cassidy
  Support for @samp{GNU Collaborative International Dictionary of
English}.  This dictionary derived from Webster's Revised Unabridged
Dictionary, supplemented with some of the definitions from WordNet.
It was edited by Patrick J.@: Cassidy, proof-read and supplemented by
volunteers from around the world.  It is available from
@uref{http://gcide.gnu.org.ua}.

@item guile
  This module provides an interface to Guile, the @dfn{GNU's
Ubiquitous Intelligent Language for Extensions}
(@uref{http://www.gnu.org/software/guile}) and allows you to write
Dico modules in Scheme programming language.

@item python
  This module provides an interface to Python 
(@uref{http://www.python.org}) and can be used to write Dico modules
in it.

@item outline
  This module handles simple databases in GNU Emacs @dfn{outline}
format.  It is designed mostly for test purposes.
@end table

  This manual describes how to configure and use the Dico dictionary
system.  It also describes the @acronym{API} for writing
Dico modules in @acronym{C}, @acronym{Scheme} or Python.

@node Building
@chapter Building the Package
  Building Dico is quite straightforward.  You run
@command{./configure}, then @command{make}, followed by @command{make
install}, and you are done.

  Actions the @command{configure} script performs are controlled
by a set of command line options and variables.  Some of these
options are generic, i.e. common for all packages using the GNU
@command{autoconf} system.  For a detailed description of these option
see the @file{INSTALL} file shipped with the sources.  Yet another
options are specific for Dico.  We will describe them in this chapter.

@menu
* Default Preprocessor::
* Default Server::
* Guile Support::
* Python Support::
* Other Settings::
@end menu

@node Default Preprocessor
@section Default Preprocessor
@cindex Default preprocessor
@cindex preprocessor, default
@vrindex DEFAULT_PREPROCESSOR     
  The runtime configuration system uses @command{m4} to preprocess
the configuration file (@pxref{Preprocessor}), which makes the
configuration extremely flexible.  We recommend to use GNU m4 as a
preprocessor@footnote{@uref{http://www.gnu.org/software/m4}}.
However, any other implementation of @command{m4} can be used as well.
The @command{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 @env{DEFAULT_PREPROCESSOR} configuration
variable.  For example, the following @command{configure} invocation
instructs it to use @command{/usr/local/bin/gm4}:

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

Note the use of the @option{-s} preprocessor option.  It instructs
@command{m4} to produce line directives which help @command{dicod}
produce correct diagnostics about eventual configuration errors.
Unless your @command{m4} implementation does not have this feature, we
recommend to always use it in @env{DEFAULT_PREPROCESSOR} value.

@opindex --without-preprocessor, configuration option
Finally, if you do not wish to use preprocessor at all, you can
disable it using @option{--without-preprocessor} option to
@command{configure}.

@node Default Server
@section Default Server
@cindex dict server, default
@vrindex DEFAULT_DICT_SERVER

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

     $ ./configure DEFAULT_DICT_SERVER=dict.org

The value of the @env{DEFAULT_DICT_SERVER} variable can be either a
hostname or IP address of the server.  It can also be followed by a
colon and a port specification, either as a decimal number or as
a service name from @file{/etc/services}.

@node Guile Support
@section Guile Support
@cindex guile, configuration
  The @dfn{GNU's Ubiquitous Intelligent Language for Extensions}, or
@dfn{Guile}@footnote{@uref{http://www.gnu.org/software/guile}.}  can
be used to write database modules for GNU Dico.  This requires
Guile version 2.2.0 or newer.  The @command{configure} script will
probe for the presence of Guile on your system and automatically
enable its use if its version number is high enough.

@opindex --without-guile, configuration option
  If you do not wish to use Guile, use @option{--without-guile} to
disable it.

@node Python Support
@section Python Support
@cindex python, configuration
  The support for Python (@uref{http://www.python.org}) is enabled
automatically if @command{configure} detects that Python version 2.5 or
later is installed on your machine.

@opindex --without-python, configuration option
  If you do not wish to use Python, use @option{--without-python} to
disable it.

@node Other Settings
@section Other Configure Settings

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

  By default, the @samp{daemon} facility is used. 
  
@node Dicod
@chapter The @command{dicod} daemon.
@cindex @command{dicod}, description
  The main component of GNU Dico is the @command{dicod} daemon.  It is
responsible for serving client requests and for coordinating the work
of dictionary modules.

@cindex @command{dicod}, operation modes
There are two @dfn{operation modes}: @samp{daemon} and @samp{inetd}.

@menu
* Daemon Mode::
* Inetd Mode::
* Configuration::
* Exit Codes::
* Dicod Invocation::
@end menu

@node Daemon Mode
@section Daemon Operation Mode
@cindex operation modes of @command{dicod}
@cindex daemon operation mode
  The @samp{daemon} mode is enabled by @code{mode daemon} statement in
the configuration file (@pxref{mode statement}).  It is also the
default mode.  In daemon mode @command{dicod} listens for incoming 
requests on one or several network interfaces.  Unless the
@command{--foreground} option is specified, it detaches itself from the 
controlling terminal and switches to background (becomes a
@dfn{daemon}).  When an incoming connection arrives, it forks a
subprocess for handling it.

@cindex signals handled by @command{dicod}
@cindex SIGTERM
@cindex SIGQUIT
@cindex SIGINT
@cindex SIGHUP
  In this mode the following signals cause @command{dicod} to
terminate: @samp{SIGTERM}, @samp{SIGQUIT}, and @samp{SIGINT}.  The
@samp{SIGHUP} signal causes the program to restart.  This works only
if both the program name and its configuration file name (if given
using @option{--config} option) are absolute file names.

@cindex SIGHUP handling
@cindex restart procedure
@cindex restarting @command{dicod}
  Upon receiving @samp{SIGHUP}, @command{dicod} first verifies if the
configuration file does not contain fatal errors.  To do that, the
program executes a copy of itself with the @option{--lint} option
(@pxref{--lint}) and analyzes its return code.  Only if this check
passes, @command{dicod} restarts itself.  This ensures that the daemon
will not terminate due to unnoticed errors in its configuration file.

@cindex termination procedure
@cindex terminating @command{dicod}
  Upon receiving @samp{SIGTERM}, @samp{SIGQUIT}, or @samp{SIGINT}, the
program stops accepting incoming requests and sends the @samp{SIGTERM}
signal to all active subprocesses.  Then it waits a predefined amount
of time for all processes to terminate (@pxref{shutdown-timeout}).
Any subprocesses that do not terminate after this time are sent the
@samp{SIGKILL} signal.  Then, the database modules are unloaded and
@command{dicod} terminates.

  Several command line options are provided that modify the behavior
of @command{dicod} in this mode.  These options are mainly designed
for debugging and error-hunting purposes.

@xopindex{foreground, introduced}
@xopindex{stderr, introduced}
  The @option{--foreground} option instructs the server to remain
attached to the controlling terminal and stay in the foreground.  It 
is often used with @option{--stderr} option, which instructs 
@command{dicod} to output all diagnostic to the standard error output, 
instead of syslog which is used by default.

@node Inetd Mode
@section Inetd Operation Mode
@cindex inetd operation mode
@xopindex{inetd, introduced}
@flindex inetd.conf
  In @samp{inetd} operation mode @command{inetd} receives requests
from standard input and sends its replies to the standard output.
This mode is enabled by @code{mode inetd} statement (@pxref{mode
statement}) in configuration file, or by the @option{--inetd} command
line option (@pxref{--inetd}).  This mode is usually used when
invoking @command{dicod} from @file{inetd.conf} file, as in example
below:

@example
dict  stream  tcp  nowait  nobody /usr/bin/dicod --inetd
@end example
  
@node Configuration
@section Configuration
@cindex configuration file
@flindex dicod.conf
@xopindex{config, introduced}
  Upon startup, @command{dicod} reads its settings and database
definitions from a @dfn{configuration file} @file{dicod.conf}.  By
default it is located in @var{$sysconfidr} (i.e., in most cases
@file{/usr/local/etc}, or @file{/etc}), but an alternative location
may be specified using the @option{--config} command line option
(@pxref{--config}).

  If any errors are encountered in the configuration file, the program
reports them on the standard error and exits with a non-zero status.

@xopindex{lint, introduced}
  To test the configuration file without starting the server, use
the @option{--lint} (@option{-t}) command line option.  It causes
@command{dicod} to check its configuration file and exit with status 0
if no errors were detected, and with status 1 otherwise.

@opindex -E, introduced
@xopindex{no-preprocessor, introduced}
  Before parsing, the configuration file is preprocessed using
@command{m4} (@pxref{Preprocessor}).  To examine the preprocessed
configuration without actually parsing it, use the @option{-E} command
line option.  To avoid preprocessing it, use the
@option{--no-preprocessor} option.

@xopindex{config-help, introduced}
  The rest of this section describes configuration file syntax in
detail.  You can receive a concise summary of all configuration
directives any time by running @command{dicod --config-help}.

@menu
* Syntax::               Configuration file syntax.
* Server Settings::
* Authentication::
* SASL::                 SASL Authentication.
* ACL::                  Access Control Lists
* Security Settings::
* Logging and Debugging::
* Access Log::
* General Settings::
* Capabilities::
* Handlers::
* Databases::
* Strategies and Default Searches::
* Tuning::
* Command Aliases::
* Preprocessor::         Using preprocessor to improve the configuration.
@end menu

@node Syntax
@subsection Configuration File Syntax
  A @command{dicod} configuration consists of statements and comments.

  There are three classes of lexical tokens: keywords, values, and
separators.  Blanks, tabs, newlines and comments, collectively called
@dfn{white space} are ignored except as they serve to separate
tokens.  Some white space is required to separate otherwise adjacent 
keywords and values.

@menu
* Comments::
* Pragmatic Comments::
* Statements::
@end menu

@node Comments
@subsubsection Comments
@cindex Comments in a configuration file
@cindex single-line comments
  @dfn{Comments} may appear anywhere where white space may appear in the
configuration file.  There are two kinds of comments:
single-line and multi-line comments.  @dfn{Single-line} comments start
with @samp{#} or @samp{//} and continue to the end of the line:

@example
# This is a comment
// This too is a comment
@end example

@cindex multi-line comments
  @dfn{Multi-line} or @dfn{C-style} comments start with the two
characters @samp{/*} (slash, star) and continue until the first
occurrence of @samp{*/} (star, slash).

  Multi-line comments cannot be nested.

@node Pragmatic Comments
@subsubsection Pragmatic Comments
@cindex comments, pragmatic
@cindex pragmatic comments
  Pragmatic comments are similar to usual comments, except that they
cause some changes in the way the configuration is parsed.  Pragmatic
comments begin with a @samp{#} sign and end with the next physical
newline character.  As of GNU Dico version @value{VERSION}, the following
pragmatic comments are understood:

@table @code
@kwindex #include
@item #include <@var{file}>
@itemx #include @var{file}
Include the contents of the @var{file}.  If @var{file} is an
absolute file name, both forms are equivalent.  Otherwise, the form
with angle brackets searches for the file in the @dfn{include 
search path}, while the second one looks for it in the current working
directory first, and, if not found there, in the include search
path.

The default include search path is:

@enumerate 1
@item @file{@var{prefix}/share/dico/@value{VERSION}/include}
@item @file{@var{prefix}/share/dico/include}
@end enumerate

@noindent
where @var{prefix} is the installation prefix.

  New directories can be appended in front of it using @option{-I}
(@option{--include-dir}) command line option (@pxref{--include-dir}).  

@kwindex #include_once
@item #include_once <@var{file}>
@itemx #include_once @var{file}
  Same as @code{#include}, except that, if the @var{file} has already
been included, it will not be included again.

@kwindex #line
@item #line @var{num}
@itemx #line @var{num} "@var{file}"
  This line causes @command{dicod} to believe, for purposes of error
diagnostics, that the line number of the next source line is given by
@var{num} and the current input file is named by @var{file}.
If the latter is absent, the remembered file name does not change.

@item # @var{num} "@var{file}"
  This is a special form of @code{#line} statement, understood for
compatibility with the @sc{c} preprocessor.
@end table

  In fact, these statements provide a rudimentary preprocessing
features.  For more sophisticated ways to modify configuration before
parsing, see @ref{Preprocessor}.

@node Statements
@subsubsection Statements
@cindex statements, configuration file
@cindex configuration file statements
@cindex statement, simple
@cindex simple statements
  A @dfn{simple statement} consists of a keyword and a value
separated by any amount of whitespace.  It is terminated with a 
semicolon (@samp{;}), unless the value is a @dfn{here-document}
(see below), in which case semicolon is optional.

  Examples of simple statements:

@example
timing yes;
access-log-file /var/log/access_log;
@end example

  A @dfn{keyword} begins with a letter and may contain letters,
decimal digits, underscores (@samp{_}) and dashes (@samp{-}).
Examples of keywords are: @samp{group}, @samp{identity-check}.

  A @dfn{value} can be one of the following:

@table @asis
@item number
  A number is a sequence of decimal digits.

@item boolean
@cindex boolean value
  A boolean value is one of the following: @samp{yes}, @samp{true},
@samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no},
@samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}.
  
@item unquoted string
@cindex string, unquoted
  An unquoted string may contain letters, digits, and any of the
following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/},
@samp{@@}, @samp{*}, @samp{:}.

@item quoted string
@cindex quoted string
@cindex string, quoted
@cindex escape sequence
  A quoted string is any sequence of characters enclosed in
double-quotes (@samp{"}).  A backslash appearing within a quoted
string introduces an @dfn{escape sequence}, which is replaced
with a single character according to the following rules:

@float Table, backslash-interpretation
@caption{Backslash escapes}
@multitable @columnfractions 0.30 .5
@item Sequence @tab Replaced with
@item \a @tab Audible bell character (@acronym{ASCII} 7)
@item \b @tab Backspace character (@acronym{ASCII} 8)
@item \f @tab Form-feed character (@acronym{ASCII} 12)
@item \n @tab Newline character (@acronym{ASCII} 10)
@item \r @tab Carriage return character (@acronym{ASCII} 13)
@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
@item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
@item \\ @tab A single backslash (@samp{\})
@item \" @tab A double-quote.
@end multitable
@end float

  In addition, the sequence @samp{\@var{newline}} is removed from
the string.  This allows you to split long strings over several
physical lines, e.g.:

@example
@group
"a long string may be\
 split over several lines"
@end group
@end example

  If the character following a backslash is not one of those specified
above, the backslash is ignored and a warning is issued.

  Two or more adjacent quoted strings are concatenated, which gives
another way to split long strings over several lines to improve
readability.  For instance, the following fragment produces the same
result as the example above:

@example
@group
"a long string may be"
" split over several lines"
@end group
@end example

@anchor{here-document}
@item Here-document
@cindex here-document
  A @dfn{here-document} is a special construct that allows the user to
introduce strings of text containing embedded newlines.  

  The @code{<<@var{word}} construct instructs the parser to read all
the following lines up to the line containing only @var{word}, with
possible trailing blanks.  Any lines thus read are concatenated
together into a single string.  For example:

@example
@group
<<EOT
A multiline
string
EOT
@end group
@end example

  The body of a here-document is interpreted the same way as a
double-quoted string, unless @var{word} is preceded by a backslash
(e.g.@: @samp{<<\EOT}) or enclosed in double-quotes, in which case
the text is read as is, without interpretation of escape sequences.

  If @var{word} is prefixed with @code{-} (a dash), then all leading
tab characters are stripped from input lines and the line containing
@var{word}.  Furthermore, if @code{-} is followed by a single space,
all leading whitespace is stripped from them.  This allows for indenting
here-documents in a natural fashion.  For example:

@example
@group
<<- TEXT
    All leading whitespace will be
    ignored when reading these lines.
TEXT
@end group
@end example

  It is important that the terminating delimiter be the only token on
its line.  The only exception to this rule is allowed if a
here-document appears as the last element of a statement.  In this
case a semicolon can be placed on the same line with its terminating 
delimiter, as in: 

@example
help-text <<-EOT
        A sample help text.
EOT;
@end example

@item list
@cindex list
  A @dfn{list} is a comma-separated sequence of values.  Lists are
delimited by parentheses.  The following example shows a statement
whose value is a list of strings:

@example
capability (mime,auth);
@end example

  In any case where a list is appropriate, a single value is allowed
without being a member of a list: it is equivalent to a list whose only
member is that value. This means that, e.g.@: @samp{capability mime;} is
equivalent to @samp{capability (mime);}.

@end table

@cindex statement, block
@cindex block statement
  A @dfn{block statement} introduces a logical group of another
statements.  It consists of a keyword, followed by an optional value,
and a sequence of statements enclosed in curly braces, as shown in
the example below:

@example
@group
load-module outline @{
        command "outline";
@}
@end group
@end example

  The closing curly brace may be followed by a semicolon, although
this is not required.

@node Server Settings
@subsection Server Settings
  Server settings control how @command{dicod} is executed on the
server machine.

@anchor{user statement}
@deffn {Configuration} user @var{string}
Run with the privileges of this user.  @command{Dicod} does not
require root privileges, so it is recommended to always use this
statement when running @command{dicod} in daemon mode (@pxref{Daemon
Mode}).  The argument is either a user name, or UID prefixed with a
plus sign.

Example:
@example
user nobody;
@end example
@end deffn

@anchor{group statement}
@deffn {Configuration} group @var{list}
If @code{user} is given, @command{dicod} will drop all supplementary
groups and switch to the principal group of that user.  Sometimes,
however, it may be necessary to retain one or more supplementary
groups.  For example, this might be necessary to access dictionary
databases.  The @code{group} statement retains the supplementary
groups listed in @var{list}.  Each group can be specified either
by its name or by its GID number, prefixed with @samp{+}, e.g.:

@example
user nobody;
group (man, dict, +88);
@end example

This statement is ignored if @code{user} statement is not present or
if @command{dicod} is running in inetd mode.  @xref{Inetd Mode}. 
@end deffn

@anchor{mode statement}
@deffn {Configuration} mode @var{enum}
Sets server operation mode.  The argument is one of:

@table @asis
@item daemon
Run in daemon mode.  @xref{Daemon Mode}, for a detailed description.

@item inetd
Run in inetd mode.  @xref{Inetd Mode}, for a detailed description.
@end table

This statement is overridden by the @option{--inetd} command line
option.  @xref{--inetd}.
@end deffn

@deffn {Configuration} listen @var{list};
Specify the @acronym{IP} addresses and ports to listen on in daemon mode.
By default, @command{dicod} will listen on port 2628 on all existing
interfaces.  Use the @code{listen} statement to abridge the list of
interfaces to listen on, or to change the port number. 

Elements of @var{list} can have the following forms:

@table @asis
@item @var{host}:@var{port}
  Specifies an @acronym{IP} (version 4 or 6) socket to listen on.  The
@var{host} part is either an @acronym{IPv4} in ``dotted-quad''
notation, or an @acronym{IPv6} address in square brackets, or a host
name.  In the latter case, @command{dicod} will listen on all IP
addresses corresponding to its @samp{A} or @samp{AAAA}
@acronym{DNS} records.

The @var{port} part is either a numeric port number or a
symbolic service name which is found in @file{/etc/services} file.

  Either of the two parts may be omitted.  If @var{host} is omitted,
@command{dicod} will listen on all interfaces.  If @var{port} is
omitted, it defaults to 2628.  In this case the colon may be omitted,
too.

  Examples:
  
@example
listen dict.example.org:2628;
listen 198.51.100.10;
listen [2001:DB8::11];
listen :2628;
@end example

@item inet://@var{host}:@var{port}
@itemx inet4://@var{host}:@var{port}
  Listen on @acronym{IPv4} socket.  The @var{host} is either an
@acronym{IP} address or a host name.  In the latter case,
@command{dicod} will start listening on all @acronym{IP} addresses
from the @samp{A} records for this host.

  Either @var{host} or @var{port} (but not both) can be omitted.
Missing @var{host} defaults to @acronym{IPv4} addresses on all available
network interfaces, and missing @var{port} defaults to 2628.

  Example:

@example
listen inet4://198.51.100.10;
@end example

@item inet6://@var{host}:@var{port}
  Listen on @acronym{IPv6} socket.  The @var{host} is either an
@acronym{IPv6} address in square brackets, or a host name.  In the
latter case, @command{dicod} will start listening on all @acronym{IP}
addresses from the @samp{AAAA} records for this host.

  Either @var{host} or @var{port} (but not both) can be omitted.
Missing @var{host} defaults to @acronym{IPv6} addresses on all available
network interfaces, and missing @var{port} defaults to 2628.

  Example:

@example
listen inet6://[2001:DB8::11];
@end example

@item @var{filename}
@itemx unix://@var{filename}
  Specifies the name of a @acronym{UNIX} socket to listen on.
@var{Filename} must be an absolute file name of the socket.
@end table

@end deffn

@deffn {Configuration} pidfile @var{string}
Store @acronym{PID} of the master process in this file.
Default is @file{@var{localstatedir}/run/dicod.pid}. 
Notice that the access bits of this default directory
may be insufficient for @command{dicod} to write there after dropping
root privileges (@pxref{user statement}).  One solution to this is
to create a subdirectory with the same owner as given by @code{user}
statement and to point the @acronym{PID} file there:

@example
pidfile /var/run/dict/dicod.pid;
@end example

Another solution is to make @acronym{PID} directory group-writable and
to add the owner group to the @code{group} statement (@pxref{group
statement}).
@end deffn

@deffn {Configuration} max-children @var{number}
Sets maximum number of sub-processes that can run simultaneously.
This is equivalent to the number of clients that can simultaneously
use the server.  The default is 64 sub-processes.
@end deffn

@anchor{inactivity-timeout}
@deffn {Configuration} inactivity-timeout @var{number}
Set inactivity timeout to the @var{number} of seconds.  The server
disconnects automatically if the remote client has not sent any
command within this number of seconds.  Setting timeout to 0 disables
inactivity timeout (the default).

This statement along with @code{max-children} allows you to control
the server load.
@end deffn

@anchor{shutdown-timeout}
@deffn {Configuration} shutdown-timeout @var{number}
When the master server is shutting down, wait this number of seconds for all
children to terminate.  Default is 5 seconds.
@end deffn

@anchor{identity-check}
@deffn {Configuration} identity-check @var{boolean}
Enable identification check using @acronym{AUTH} protocol
(@acronym{RFC} 1413).  The received user name or @acronym{UID} can
be shown in access log using the @code{%l} conversion (@pxref{Access Log}).
@end deffn

@deffn {Configuration} ident-keyfile @var{string}
Use encryption keys from the named file to decrypt @acronym{AUTH}
replies encrypted using @acronym{DES}.
@end deffn

@deffn {Configuration} ident-timeout @var{number}
Set timeout for @acronym{AUTH} input/output operation to @var{number}
of seconds.  Default timeout is 3 seconds.
@end deffn

@node Authentication
@subsection Authentication
@cindex authentication
  The server may be configured to request authentication in order to
make some databases or some additional information available to the
user.  Another possible use of authentication is to minimize resource
utilization on the server machine.

  GNU Dico supports two types of authentication: the traditional
APOP-style authentication (@pxref{AUTH}) and a more advanced SASL
authentication.  The latter is described separately, see @ref{SASL}. 

  Authentication setup is simple: first, you define a user
authentication database, then you enable it by declaring @code{auth}
server capability (@pxref{Capabilities}):

@example
capability auth;
@end example

@cindex authentication database
@cindex database, authentication
  @dfn{User authentication database} keeps, for each user name,
the corresponding plain text password, and, optionally, the names of
groups this user belongs to.  Notice, that due to the specifics of
@acronym{DICT} authentication scheme (@pxref{AUTH}), user passwords
are stored in plain text, therefore special care must be taken to
protect the contents of your authentication database from compromise.

The database is defined using the @code{user-db} block statement:

@deffn {Configuration} user-db url
Declare user authentication database.
@end deffn

@cindex @acronym{URL}, authentication database
@cindex authentication database @acronym{URL}
Dico's authentication is designed so that various authentication
database formats can easily be added.  A database is identified
by its @acronym{URL}, or @dfn{Universal Resource Locator}.  It
consists of the following parts (square brackets denoting optional
ones):

@example
@var{type}://[[@var{user}[:@var{password}]@@]@var{host}]/@var{path}[@var{params}]
@end example

@table @var
@item type
A @dfn{database type}, or format.  See below for a list of
available database formats.

@item user
User name necessary to access the database. 

@item password
User password necessary to access the database. 

@item host
Domain name or @acronym{IP} address of a machine running the database.

@item path
A @dfn{path} to the database.  The exact meaning of this element
depends on the database protocol.  It is described in detail when
discussing the particular database protocols.

@item params
A list of protocol-dependent parameters.  Each parameter is of the
form @code{@var{keyword}=@var{name}}, multiple parameters are separated
with semicolons.
@end table

  If the underlying mechanism requires some additional configuration
data that cannot be supplied in an @acronym{URL}, these are passed to
it using the following statement:

@cindex option, authentication
@deffn {user-db conf} options string
  The argument is treated as an opaque string and passed to the
authentication @samp{open} procedure verbatim.  Its exact meaning
depends on the type of the database.
@end deffn

  The @acronym{URL} defines how the database is accessed.  Another
important point is where to get the user data from.  This is specified by
the following two sub-statements:

@cindex resource, authentication
@cindex authentication resource
@deffn {user-db conf} password-resource arg
A database resource which returns the user's password.
@end deffn

@deffn {user-db conf} group-resource arg
A database resource which returns the list of groups this user is member of.
@end deffn

The exact semantics of the @dfn{database resource} depends on the
type of database being used.  For flat text databases, it means
the name of a text file that contains these data, for @acronym{SQL}
databases, the resource is an @acronym{SQL} query, etc.  Below we will
discuss @acronym{URL}s and resources used by each database type.

@cindex authentication database configuration
@cindex authentication database definition
To summarize, the authentication database is defined as:

@example
@group
# @r{Define user database for authentication.}
user-db @var{url} @{
  # @r{Additional configuration options.}
  options @var{string};
  
  # @r{Name of a password resource.}
  password-resource @var{resource};

  # @r{Name of the resource returning user group information.}
  group-resource @var{resource};
@}
@end group
@end example

@menu
* text userdb::       Flat Text Databases.
* ldap userdb::       LDAP Databases.
@end menu

@node text userdb
@subsubsection Text Authentication Database
@cindex text authentication database
@cindex authentication database, text
  A text authentication database consists of one or two flat text
files --- a @dfn{password file}, which contains user passwords, and
a @dfn{group file}, which contains user groups.  The latter is
optional.  Both files have the same format:

@itemize @bullet
@item Empty lines are ignored.
@item Any text from @samp{#} to the end of the line is ignored.
@item Non-empty lines consist of two fields, separated by any amount
of white space.  The first field is the user name.  It serves as a search
key in the database.  The second field is the requested resource.
@end itemize

  Record keys in a password file must be unique, i.e. no two records
may contain the same first field.  The group file may contain multiple
records with the same key.  For example:

@example
$ grep smith pass
smith guessme
$ grep smith group
smith user
smith timing
smith tester
@end example

  This means that user @samp{smith} has password @samp{guessme} and is
a member of three groups: @samp{user}, @samp{timing} and
@samp{tester}.

  A @acronym{URL} of a text database begins with @samp{text} and
contains only the @var{path} element, which gives the name of the
directory where the database files reside.  The name of a password
file is given by the @code{password-resource} statement.  The name of a
group file is given by the @code{group-resource} statement.

  For example, if user passwords are kept in the file @file{passwd}, user
groups are kept in the file @file{user}, and both files reside in
@file{/var/db/dico} directory, then the appropriate database
configuration will be:

@example
@group
user-db text:///var/db/dico @{
  password-resource passwd;
  group-resource group;
@}
@end group
@end example

@node ldap userdb
@subsubsection LDAP Databases.
To configure @acronym{LDAP} user database, you need first to load
the @samp{ldap} module (@pxref{ldap, LDAP module}):

@example
load-module ldap;
@end example

The @acronym{URL} of the database is:
@samp{ldap://@var{host}[:@var{port}]}, where @var{host} is the host
name or IP address of the @acronym{LDAP} server, and optional @var{port}
specifies the port number it is listening on (by default, port 389 is
assumed).

The @code{password-resource} statement specifies the name of an
attribute containing the password, and the @code{group-resource}
supplies the name of the attribute with the group name.

Additional configuration data are supplied in the @code{options}
statement, whose argument is a whitespace-separated list of
assignments:

@table @option
@item base=@var{base}
Sets base DN.

@item binddn=@var{dn}
Sets the DN to bind as.

@item passwd=@var{string}
Sets the password.

@item tls=@var{bool}
When set to @samp{yes}, enables the use of TLS encryption.

@item debug=@var{number}
Sets OpenLDAP debug level.

@item user-filter=@var{filter}
A LDAP filter to select the objects describing this user.  Any
occurrence of @samp{$user} in @var{filter} is replaced with the actual
user name, as obtained during the authentication.  This @dfn{variable expansion}
occurs much the same way as in shell.  In particular, the variable
is expanded only unless it is immediately followed by an alphanumeric
character.  For example, it occurs in:

@example
(uid=$user)
@end example

@noindent
and

@example
(uid=$user.1)
@end example

But it does not occur in

@example
(uid=$users)
@end example

If it is necessary to expand the variable in such a context, enclose
its name in curly braces:

@example
(uid=$@{user@}s)
@end example

@item group-filter=@var{filter}
A @acronym{LDAP} filter that selects the user groups.  The
@var{filter} is expanded as in @code{user-filter}.
@end table

  The following example shows a @acronym{LDAP} user database
configured for base DN @samp{example.com} which uses
@samp{posixAccount} and @samp{posixGroup} objects from
@samp{nis.schema}:

@example
@group
user-db "ldap://localhost" @{
  password-resource userPassword;
  group-resource cn;
  options "user-filter=(uid=$user) "
          "group-filter=(&(objectClass=posixGroup)"
                       "(memberuid=$user)) "
          "base=dc=example,dc=com";
@}
@end group
@end example

  A note on password usage is in order here.  Most authentication methods
require the passwords to be stored in the database in @emph{plain
text} form.  The use of encrypted passwords (e.g.@: MD5 or SHA1) is
possible only with @samp{LOGIN} and @samp{PLAIN} GSASL authentication
methods.

@node SASL
@subsection SASL Authentication
@cindex SASL
@cindex gsasl
The SASL authentication is available if the server was compiled with
GNU SASL.

@deffn {Configuration} sasl @{ @var{statements} @}
This block statement configures SASL authentication.  The following
is a short summary of its syntax and the available substatements:

@example
sasl @{
  # @r{Disable SASL mechanisms listed in @var{mech}}.
  disable-mechanism @var{mech};
  # @r{Enable SASL mechanisms listed in @var{mech}}.
  enable-mechanism @var{mech};
  # @r{Set service name for GSSAPI and Kerberos.}
  service @var{name};
  # @r{Set realm name for GSSAPI and Kerberos.}
  realm @var{name};
  # @r{Define groups for anonymous users.}
  anon-group @var{group-list};
@}
@end example
@end deffn

The list of available authentication mechanisms is configured using
two statements:

@deffn {sasl} disable-mechanism mech
Disables SASL mechanisms listed in @var{mech}, which is a list of names.
@end deffn

@deffn {sasl} enable-mechanism mech
Enables SASL mechanisms listed in @var{mech}, which is a list of names.
@end deffn

The server builds a list of available mechanisms using the following
algorithm.  First, a list of implemented mechanisms is retrieved from
the SASL library.  If the @code{enable-mechanism} statement is
defined, the resulting list is filtered so that only mechanisms listed
in @code{enable-mechanism} remain.  Further, if the
@code{disable-mechanism} statement is defined, the names listed there
are removed from the list.

@deffn {sasl} service name
Sets the service name for GSSAPI and Kerberos mechanisms.
@end deffn

@deffn {sasl} realm name
Sets the realm name.
@end deffn

@deffn {sasl} anon-group list
Sets the list of user groups considered anonymous.
@end deffn

The database of user credentials depends on the authentication
mechanism used.  For GSSAPI or Kerberos it is managed by appropriate
servers.  Other mechanisms use the standard @command{dicod} user database
configuration (@pxref{Authentication}).

@node ACL
@subsection Access Control Lists
@cindex @acronym{ACL}
@cindex access control lists
@dfn{Access control lists}, or @acronym{ACL}s for short, are lists of
permissions that can be applied to certain @command{dicod} objects.
They can be used to control who can connect to the dictionary server
and what resources are offered to whom.

@kwindex acl
An @acronym{ACL} is defined using the @code{acl} block statement:

@example
acl @var{name} @{
  @var{definitions}
@}
@end example

The parameter @var{name} specifies a unique name for that
@acronym{ACL}.  This name will be used by another configuration
statements to refer to that @acronym{ACL} (@xref{Security Settings},
and @pxref{Database Visibility}).

A part between the curly braces (denoted by @var{definitions} above),
is a list of @dfn{access statements}.  There are two types of
such statements:  

@deffn {ACL} allow @var{user-group} @var{sub-acl} @var{host-list}
Allow access to resource.
@end deffn

@deffn {ACL} deny @var{user-group} @var{sub-acl} @var{host-list}
Deny access to resource.
@end deffn

All parts of an access statement are optional, but at least one
of them must be present.

The @var{user-group} part specifies which users match this entry.
Allowed values are the following:

@table @code
@kwindex all
@item all
All users.

@kwindex authenticated
@item authenticated
Only authenticated users.

@kwindex group
@item group @var{group-list}
Authenticated users which are members of at least one of the groups listed in
@var{group-list}.
@end table

The @var{sub-acl} part, if present, branches to another @acronym{ACL}.
The syntax of this group is: 

@example
acl @var{name}
@end example

@noindent
where @var{name} is the name of a previously defined @acronym{ACL}.

Finally, the @var{host-list} group matches client IP addresses.
It consists of a @code{from} keyword followed by a list of
@dfn{address specifiers}.  Allowed address specifiers are:

@table @asis
@item @code{any}
Matches any client address.

@item @var{addr}
Matches if the client @acronym{IP} equals @var{addr}.
The latter may be given either as an @acronym{IP}
address or as a host name, in which case it will be resolved and the
first of its @acronym{IP} addresses will be used.


@item @var{addr}/@var{netlen}
Matches if first @var{netlen} bits from the client @acronym{IP}
address equal to @var{addr}.  The network mask length, @var{netlen}
must be an integer number in the range from 0 to 32 for IPv4, and
in the range 0 -- 128 for IPv6.  The address part,
@var{addr}, is as described above. 

@item @var{addr}/@var{netmask}
The specifier matches if the result of logical @acronym{AND} between
the client @acronym{IP} address and @var{netmask} equals to
@var{addr}.  The network mask must be specified in a IP address
(either IPv4 or IPv6) notation.

@item @var{filename}
Matches if connection was received from a @acronym{UNIX} socket
@var{filename}, which must be given as an absolute file name.
@end table

To summarize, the syntax of an access statement is:

@example
allow|deny [all|authenticated|group @var{group-list}]
           [acl @var{name}] [from @var{addr-list}]
@end example

@noindent
where square brackets denote optional parts and vertical bar means
@samp{one of}.

When an @acronym{ACL} is applied to a particular object, its entries
are tried in turn until one of them matches, or the end of the list is
reached.  If a matched entry is found, its command verb, @code{allow}
or @code{deny}, defines the result of @acronym{ACL} match.  If the end
of list is reached, the result is @samp{allow}, unless explicitly
specified otherwise.

For example, the following statement defines an @acronym{ACL} named
@samp{common}, that allows access for any user connected via local
@acronym{UNIX} socket @file{/tmp/dicod.sock} or coming from a local
network @samp{192.168.10.0/24}.  Any authenticated users are allowed,
provided that they are allowed by another @acronym{ACL} @samp{my-nets}
(which should have been defined before this definition).  Users 
coming from the network @samp{10.10.0.0/24} are allowed if they
authenticate themselves and are members of groups @samp{dicod} or
@samp{users}.  Anybody else is denied access:

@example
@group
acl common @{
    allow all from ("/tmp/dicod.sock", "192.168.10.0/24");
    allow authenticated acl "my-nets";
    allow group ("dicod", "users") from "10.10.0.0/24";
    deny all;
@}
@end group
@end example

@xref{Security Settings}, for information on how to control daemon
security settings.

@xref{Database Visibility}, for a detailed description on how to use
@acronym{ACL}s to control access to databases.  

@node Security Settings
@subsection Security Settings
  This subsection describes configuration settings that control access
to various resources served by @command{dicod}.

@deffn {Configuration} connection-acl @var{acl-name}
  Use @acronym{ACL} @var{acl-name} to control incoming connections.
The @acronym{ACL} itself must be defined before this statement.  Using
@var{user-group} (see previous subsection) in this @acronym{ACL} makes
no sense, because the authentication itself is performed only after the 
connection have been established.

@example
@group
acl incoming-conn @{
   allow from 213.130.0.0/19;
   deny any;
@}

connection-acl incoming-conn;
@end group
@end example
@end deffn

@deffn {Configuration} show-sys-info @var{acl-name}
  This statement controls whether to show system information in reply
to @code{SHOW SERVER} command (@pxref{SHOW, SHOW SERVER}).  The
information will be shown only if @acronym{ACL} @var{acl-name} allows it.

@cindex system information
The system information shown includes the following data: name
of the package and its version, name of the system where it was
built and the kernel version thereof, host name, total operational
time of the daemon, number of subprocesses executed so far and average
usage frequency.  For example:

@example
dicod (dico @value{VERSION}) on Linux 2.6.32,
dict.example.net up 99+04:42:58, 19647 forks (686.9/hour)
@end example
@end deffn

@node Logging and Debugging
@subsection Logging and Debugging
@cindex logging, configuration
  The directives described in this subsection provide basic logging
capabilities.  

@deffn {Configuration} log-tag @var{string}
Prefix syslog messages with this string.  By default, the program name
is used.
@end deffn

@deffn {Configuration} log-facility @var{string}
Sets the syslog facility to use.  Allowed values are: @samp{user},
@samp{daemon}, @samp{auth}, @samp{authpriv}, @samp{mail}, @samp{cron},
@samp{local0} through @samp{local7} (case-insensitive), or a facility
number.
@end deffn

@deffn {Configuration} log-print-severity @var{boolean}
Prefix diagnostics messages with a string identifying their severity.
@end deffn

@deffn {Configuration} transcript @var{boolean}
Controls the transcript of user sessions.  If @var{boolean} is @samp{true},
the transcript will be output to the logging channel.  In the transcript,
the lines received from client are prefixed with @samp{C:}, while those 
sent in reply are marked with @samp{S:}.  Here is an excerpt from the 
transcript output:

@example
S: 220 example.net dicod (dico @value{VERSION}) <mime.xversion>
  <1645.1212874507@@example.net>
C: client "Kdict"
S: 250 ok
C: show db
S: 110 16 databases present
S: afr-deu "Afrikaans-German Freedict dictionary"
S: afr-eng "Afrikaans-English FreeDict Dictionary"
[...]
S: .
S: 250 ok
@end example

(The first line is split in two to fit in the printed page width.)
This option produces lots of output and can significantly slow down
the server.  Use it only if you are debugging @command{dicod} or
some remote client.  Never use it in a production environment.
@end deffn

@node Access Log
@subsection Access Log
@cindex access log
@cindex logging requests
@cindex Apache
  GNU Dico provides a feature similar to Apache's @code{CustomLog}, which
keeps a log of @code{MATCH} and @code{DEFINE} requests.  To enable
this feature, specify the name of the log file using the following
directive:
  
@deffn {Configuration} access-log-file @var{string}
Sets access log file name.

@example
access-log-file /var/log/dico/access.log;
@end example
@end deffn

  The format of log file entries is defined via the
@code{access-log-format} directive:

@deffn {Configuration} access-log-format @var{string}
Sets format string for access log file.
@end deffn

@cindex % formats
  Its argument can contain literal characters, which are copied into
the log file verbatim, and @dfn{format specifiers}, i.e. special
sequences which begin with @samp{%} and are replaced in the log file
as shown in the table below.

@table @code
@item %%
The percent sign.

@item %a
Remote @acronym{IP}-address.

@item %A
Local @acronym{IP}-address.

@item %B
Size of response in bytes.

@item %b
Size of response in bytes in @acronym{CLF} format, i.e. a @samp{-} rather
than a @samp{0} when no bytes are sent.

@item %C
Remote client (from the @code{CLIENT} command, @pxref{CLIENT}).

@item %D
The time taken to serve the request, in microseconds.

@item %d
Request command verb in abbreviated form, suitable for use in
@acronym{URL}s, i.e.@: @samp{d} for @code{DEFINE}, and @samp{m} for
@code{MATCH}.  @xref{urls}.

@item %h
Remote host.

@item %H
Request command verb (@code{DEFINE} or @code{MATCH}).

@item %l
Remote logname (from identd, if supplied).  This will return a
dash unless @code{identity-check} is set to true.
@xref{identity-check}.

@item %m
The search strategy.

@item %p
The canonical port of the server serving the request.

@item %P
The @acronym{PID} of the child that served the request.

@item %q
The database from the request.

@item %r
Full request.

@item %@{@var{n}@}R
The @var{n}th token from the request (@var{n} is 0-based).

@item %s
Reply status.  For multiple replies, the form @samp{%s} returns the
status of the first reply, while @samp{%>s} returns that of the last
reply.

@item %t
Time the request was received in the standard Apache format, e.g.:

@example
[04/Jun/2008:11:05:22 +0300]
@end example

@item %@{@var{format}@}t
The time, in the form given by @var{format}, which should be a valid
@code{strftime} format.  @xref{Time and Date Formats}, for a detailed
description.

The standard @samp{%t} format is equivalent to

@example
[%d/%b/%Y:%H:%M:%S %z]
@end example

@item %T
The time taken to serve the request, in seconds.

@item %u
Remote user from @code{AUTH} command.

@item %v
The host name of the server serving the request.  @xref{hostname
directive}.

@item %V
Actual host name of the server (in case it was overridden in
configuration).

@item %W
The word from the request.
@end table

  For the reference, here is the list of format specifiers that
have different meaning than in Apache: @samp{%C}, @samp{%H}, @samp{%m},
@samp{%q}.  The following format specifiers are unique to @command{dicod}:
@samp{%d}, @samp{%@{@var{n}@}R}, @samp{%V}, @samp{%W}.

  The absence of @code{access-log-format} directive is equivalent to
the following statement:

@example
access-log-format "%h %l %u %t \"%r\" %>s %b";
@end example

@cindex webalizer
  It was chosen so as to be compatible with Apache access logs and 
be easily parsable by existing log analyzing tools, such as
@command{webalizer}.

  Extending this format string with the client name produces a log
format similar to Apache @samp{combined log}:

@example
access-log-format "%h %l %u %t \"%r\" %>s %b \"\" \"%C\"";
@end example


@node General Settings
@subsection General Settings
  Settings described in this subsection configure the basic behavior of the
@acronym{DICT} daemon.
  
@deffn {Configuration} initial-banner-text @var{string}
Display the @var{string} in the textual part of the initial server
reply.

@anchor{initial reply}
When connection is established, the server sends an @dfn{initial reply} to
the client, that looks like in the example below:

@example
220 example.org <auth.mime> <520.1212912026@@example.org>
@end example

@xref{Initial Reply}, for a detailed description of its parts.

The part of this reply after the host name is modifiable and can 
contain arbitrary text.  You can use @code{initial-banner-text} 
to append any additional information there.  Note, that 
@var{string} may not contain newlines or angle brackets.  For example:

@example
initial-banner-text "Please authenticate yourself,";
@end example

This statement produces the following initial reply (split over two
lines for readability):

@example
220 example.org Please authenticate yourself,
  <auth.mime> <520.1212912026@@Texample.org>
@end example
@end deffn

@anchor{hostname directive}
@deffn {Configuration} hostname @var{string}
Sets the hostname.  By default, the server determines it automatically.  If,
however, it makes a wrong guess, you can fix it using this directive.

The server hostname is used, among others, in the initial reply after
@samp{220} code (see above) and may also be displayed in the access
log file using the @samp{%v} escape (@pxref{Access Log}).
@end deffn

@deffn {Configuration} server-info @var{string}
Sets the server description to be shown in reply to @code{SHOW SERVER}
(@pxref{SHOW, SHOW SERVER}) command.

The first line of the reply, after the usual @samp{114} response line,
shows the name of host where the server is running.  If the settings
of @code{show-sys-info} (@pxref{Security Settings, show-sys-info})
permit, some additional information about the system is printed.

The lines that follow are taken from the @code{server-info}
directive.  It is common to specify @var{string} using
``here-document'' syntax (@pxref{here-document}), e.g.:

@example
server-info <<EOT
Welcome to the FOO dictionary service.

Contact <dict@@foo.example.org> if you have questions or
suggestions.
EOT;
@end example

@end deffn

@deffn {Configuration} help-text @var{string}
Sets the text to be displayed in reply to the @acronym{HELP} command.

The default reply to @acronym{HELP} command displays a list of
commands understood by the server with a short description of each.

If the @var{string} begins with a plus sign, it will be appended to
the default reply:

@example
help-text <<-EOT
  +
  The commands beginning with an X are extensions.
EOT;
@end example

If the @var{string} begins with any other character, except @samp{+},
it will replace the default help output.  For example:

@example
help-text <<-EOT
  There is no help.
  See RFC 2229 for detailed information.
EOT;
@end example
@end deffn

@deffn {Configuration} default-strategy @var{string}
Sets the name of the default matching strategy
(@pxref{MATCH}).  By default, Levenshtein matching is used,
which is equivalent to

@example
default-strategy lev;
@end example
@end deffn

@node Capabilities
@subsection Server Capabilities
  @dfn{Capabilities} are certain server features that can be enabled
or disabled at the system administrator's will. 

@deffn {Configuration} capability @var{list}
Requests additional capabilities from the @var{list}.
@end deffn

  The argument to @code{capability} directive must contain names
of existing @command{dicod} capabilities.  These are listed in the
following table:

@defvr {capability} auth
The @code{AUTH} command is supported.  @xref{Authentication}.
@end defvr

@defvr {capability} mime
The @code{OPTION MIME} command is supported.  Notice that
@acronym{RFC} 2229 requires all servers to support that command, so
you should always specify this capability.
@end defvr

@defvr {capability} lang
The @dfn{lang} extensions are enabled.  @pxref{lang extensions}.
@end defvr

@defvr {capability} markup
The @code{OPTION MARKUP} command is supported.  This extended command
sets the preferred markup language for the output.  Supported markups
are reported as @code{markup-@var{name}} capabilities.
@xref{Extended Commands, OPTION MARKUP}.
@end defvr

@defvr {capability} xidle
The @code{XIDLE} command is supported.  This is an experimental
command that asks the server to report the configured value of
inactivitiy timeout for the client session.

@xref{Extended Commands, XIDLE}.
@end defvr

@defvr {capability} xlev
The @code{XLEV} command is supported.  This command allows the remote
party to set and query maximal Levenshtein distance for @code{lev}
matching strategy.  @xref{MATCH, strategy}.  @xref{Extended Commands, XLEV}.
@end defvr

@defvr {capability} xversion
The @code{XVERSION} command is supported.  It is a GNU extension that
displays the @command{dicod} implementation and version number. 
@xref{Extended Commands, XVERSION}.
@end defvr

  The capabilities set using this directive are
displayed in the initial server reply (@pxref{initial reply}), and
their descriptions are added to the @code{HELP} command output (unless
specified otherwise by the @code{help-text} statement).

@node Handlers
@subsection Database Modules and Handlers
@cindex database module, defined
  A @dfn{database module} is an external piece of software designed to
handle a particular format of dictionary databases.  This piece of
software is built as a shared library that @command{dicod} loads
at run time.

@cindex database handler, defined
  A @dfn{handler} is an instance of the database module loaded by
@command{dicod} and configured for a specific database or a set of
databases. 

  Database handlers are defined using the following block statement:
  
@deffn {Configuration} load-module @var{string} @{ @dots{} @}
Create an instance of a database module.  The argument specifies a unique name
which will be used by subsequent parts of the configuration to refer to this
handler.  The ellipsis in the description above represents
sub-statements.  As of Dico version @value{VERSION} only one
sub-statement is defined:

@deffn {load-module config} command @var{string}
Sets the command line for this handler.  It is similar to the shell's
command line in that it consists of a name of database module, optionally
followed by a whitespace-separated list of its arguments.  The name of
the module specifies the disk file to load (see below for a detailed
description of the loading sequence).  Both command name and arguments
are passed to the module @dfn{initialization function}
(@pxref{dico_init}).
@end deffn
@end deffn

For example:

@example
@group
load-module dict @{
  command "dictorg dbdir=/var/dicodb";
@}
@end group
@end example

@noindent
This statement defines a handler named @samp{dict}, which loads
the module @file{dictorg} and passes its initialization function a
single argument, @samp{dbdir=/var/dicodb}.  If the module name is not
an absolute file name, as in this example, the loadable module will be
searched in the module load path.

@cindex load-module, shortcut form
A common case is when the module does not require initialization
arguments and its command string is the same as its name, e.g.:

@example
@group
load-module outline @{
  command "outline";
@}
@end group
@end example

The configuration syntax provides a shortcut for such usage:

@example
load-module outline;
@end example

If @code{load-module} is used this way, it accepts a single string or
a list of strings as its argument.  In the latter case, it loads all
modules listed in the argument.  For example:

@example
load-module (stratall,substr,word);
@end example

@anchor{load path}
@cindex module load path
@cindex load path
  A @dfn{module load path} is an internal list of directories which
@command{dicod} scans in order to find a loadable file name specified
in the @code{command} statement.  By default the search order is as
follows:

@enumerate 1
@item
@kwindex prepend-load-path
@kwindex --load-dir
@kwindex -L
Optional @dfn{prefix} search directories specified by the
@code{prepend-load-path} directive (see below) and the
@option{--load-dir} (@option{-L}) command line option.

@item
GNU Dico module directory: @file{$prefix/lib/dico}.

@item
Additional search directories specified by the
@code{module-load-path} directive (see below).

@item
@vrindex LTDL_LIBRARY_PATH
The value of the environment variable @env{LTDL_LIBRARY_PATH}.

@item
@flindex /etc/ld.so.conf
@vrindex LD_LIBRARY_PATH
The system dependent library search path (e.g. on GNU/Linux it is defined
by the file @file{/etc/ld.so.conf} and the environment variable
@env{LD_LIBRARY_PATH}).
@end enumerate

The value of @env{LTDL_LIBRARY_PATH} and @env{LD_LIBRARY_PATH} must be a
colon-separated list of absolute directory names, for example
@samp{/usr/lib/mypkg:/lib/foo}.

In any of these directories, @command{dicod} first attempts to find and
load the given filename.  If this fails, it tries to append the
following suffixes to it:

@enumerate 1
@item
the libtool archive suffix @samp{.la}

@item
the suffix used for native dynamic libraries on the host platform,
e.g., @samp{.so}, @samp{.sl}, etc. 
@end enumerate

@deffn {Configuration} module-load-path @var{list}
This directive adds the directories listed in its argument to the
module load path.  Example:

@example
module-load-path (/usr/lib/dico,/usr/local/dico/lib);
@end example
@end deffn

@deffn {Configuration} prepend-load-path @var{list}
Same as @code{module-load-path}, but adds directories to the beginning
of the module load path.
@end deffn

@node Databases
@subsection Databases
@cindex databases, defining
  Dictionary databases are defined using the @code{database} block
statement.

@deffn {Configuration} database @{ @var{statements} @}
Defines a dictionary database.  At least two sub-statements must be
defined for each database: @code{name} and @code{handler}.
@end deffn

@deffn {Database} visible @var{bool}
Defines whether this database is visible or not.  By default, all
databases are visible.  You will need this statement if you want to
temporary hide the database without removing it from the
configuration.  Another common use case is to hide a database that is
used as a member of a virtual database, so that its contents is
available only by querying the parent database (@pxref{Virtual Databases}).
@end deffn

@deffn {Database} name @var{string}
Sets the name of this database (a single word).  This name will be used
to identify this database in @acronym{DICT} commands.
@end deffn

@deffn {Database} handler @var{string}
Specifies the handler name for this database and any arguments for
it.  This handler must be previously defined using the @code{load-module}
statement (@pxref{Handlers}).  
@end deffn

For example, the following fragment defines a database named
@samp{en-de}, which is handled by @samp{dictord} handler.  The handler
is passed one argument, @code{database=en-de}:

@example
database @{
        name "en-de";
        handler "dictorg database=en-de";
@}
@end example

More directives are available to fine-tune the database.

@deffn {Database} description @var{string}
Supplies a short description, to be shown in reply to @command{SHOW DB}
command.  The @var{string} may not contain new-lines.

Use this statement if the database itself does not supply a
description, or if its description is malformed.

In any case, if the @code{description} directive is specified, its value
takes precedence over the description string retrieved from the
database itself.

@xref{SHOW, SHOW DB}, for a description of @code{SHOW DB} command.
@end deffn

@deffn {Database} info @var{string}
Supplies a full description of the database.  This description is shown
in reply to @code{SHOW INFO} (@pxref{SHOW, SHOW INFO}) command.  The
@var{string} is usually a multi-line text, so it is common to use
here-document syntax (@pxref{here-document}), e.g.:

@example
@group
info <<- EOT
   This is a foo-bar dictionary.
   Copyright (C) 2008 foo-bar dict group.
   Distributed under the terms of GNU Free
   Documentation license.
EOT;
@end group
@end example

Use this statement if the database itself does not supply a full
description, or if its full description is malformed.

As with @code{description}, the value of @code{info} takes precedence
over info strings retrieved from the database.
@end deffn

The following two directives control the content type and transfer
encoding used when formatting replies from this database if
@code{OPTION MIME} (@pxref{OPTION, OPTION MIME}) is in effect:

@deffn {Database} mime-headers @var{multiline-string}
Defines the headers to be sent with the replies from this
database.  Argument is a here-document (@pxref{here-document}),
containing the headers to be sent with each dictionary entry, if the
client sent the @samp{OPTION MIME} command.  By default
@command{dicod} uses MIME headers defined in the database itself.  Use
this statement if these are not defined, or if you want to override them.
In this case you would want to include at least the @samp{Content-Type} and
@samp{Content-Transfer-Encoding} headers, as shown in the example below:

@example
directory @{
   name "foo";
   handler "dictorg";
   mime-headers <<- EOT
     Content-Type: text/html; charset=utf-8
     Content-Transfer-Encoding: 8bit
   EOT;     
   ...
@}   
@end example

Valid values for the @samp{Content-Transfer-Encoding} header are:

@table @asis
@item 8bit
The content will be transferred as is.

@item quoted-printable
Non-printable characters will be encoded using the
@samp{quoted-printable} encoding.

@item base64
Non-printable characters will be encoded using the
@samp{base64} encoding.
@end table
@end deffn

@menu
* Input Conversions::
* Database Visibility::
* Virtual Databases::
@end menu

@node Input Conversions
@subsubsection Input Conversions
@cindex conversion
  The argument to @command{DEFINE} or @command{MATCH} command can
optionally be modified before being used in actual search.  This
allows, for example, to input search terms in transliteration instead
of in the actual script.  Such a modification is called @dfn{input
conversion}.  Each conversion is identified by its name.  Conversions
are implemented by @dfn{convertors}, which are defined in loadable
modules, so you will need to load the appropriate ones to be able to
actually use them.

@deffn {Database} conv @var{name}
@deffnx {Database} conv ( @var{name0}, @var{name1}, ... )
@cindex converter
@cindex input converter
This statement associates one or more converters with the database.
Each converter takes a word as input and produces another word on
output.  If the list of converters is specified, then the produced
word will be used as input to the next conversion and so on.  Output
from the last conversion will be used as the actual headword to look up.
@end deffn

@xref{greek_kbd}, for an example of using input convertors.

@node Database Visibility
@subsubsection Database Visibility
@cindex database visibility
@cindex visibility, database
  A property called @dfn{database visibility} is associated with each
dictionary database.  It determines whether the database appears in
the output of @code{SHOW DB} command, and takes part in dictionary
searches.

  By default, all databases are defined as publicly visible.  You can hide
a database permanently by using the @samp{visible no} statement in its
definition.  You can also limit its visibility on global as well as on
per-directory basis.  This can be achieved using @dfn{visibility
@acronym{ACL}s}.

  In general, the visibility of a database is controlled by two access
control lists: a global visibility @acronym{ACL} and a database visibility
@acronym{ACL}.  The latter takes precedence over the former.

  Both @acronym{ACL}s are defined using the @code{visibility-acl} statement:

@deffn {Configuration} visibility-acl @var{acl-name}
Sets name of the @acronym{ACL} that controls the database visibility.
When used in global scope, this statement sets the global visibility
@acronym{ACL}.  If used within a @code{database} block, it sets the
visibility @acronym{ACL} for that particular database.
@end deffn

  Consider the following example:

@example
acl glob-vis @{
  allow authenticated;
  deny all;
@}  

acl local-nets @{
  allow from (192.168.10.0/24, /tmp/dicod.sock);
@}

visibility-acl glob-vis;

database @{
  name "terms";
  visibility-acl local-nets;
@}
@end example

In this configuration, the @samp{terms} database is visible to
everybody coming from the @samp{192.168.10.0/24} network and from
the @acronym{UNIX} socket @file{/tmp/dicod.sock}, without
authorization.  It is not visible to users coming from elsewhere,
unless they authenticate themselves.

@node Virtual Databases
@subsubsection Virtual Databases
@cindex virtual databases
@cindex database, virtual
A @dfn{virtual database} is a collection of several regular databases.
When a search is performed on a virtual database, it returns matches
from the constituent databases.

Virtual databases can be used for grouping. For example a virtual
database may include all dictionaries translating from English to
Norwegian.  Another one may include thesauri for English.

Yet another common use for virtual databases is to select different
output markup depending on whether @samp{OPTION MIME} was requested by
the user.

Technically, a virtual database is defined by specifying

@example
  handler "virtual";
@end example

@noindent
in the @code{database} definition.  This is a built-in module, so you
must not use the @code{load-module} statement.

The names of the member databases (the databases to be included to
this one) are supplied using the @code{database} statements:

@deffn {Database} database @var{name} [mime | nomime]
Specifies the database to be included as a member of this virtual
database.  The @var{name} argument supplies the name of the database
(as set by the @code{name} statement in its definition).

Optional second argument may be used to restrict the use of this
database to the given state of the @samp{MIME} option.  Databases
marked with @samp{mime} will be used only if the @code{OPTION MIME}
command has been given for the current session.  Databases marked with
@samp{nomime} will be used only if this command has not been issued.
@end deffn

The following example defines a virtual database for translations from
English to several other languages:

@example
@group
database @{
  name "English Translating Database";
  info "Translations from English to other languages";
  handler "virtual";
  database "en-sw";
  database "en-no";
  database "en-pl";
@}  
@end group
@end example

It is supposed, that databases @samp{en-sw}, @samp{en-no}, and
@samp{en-pl} are defined elsewhere in the configuration.

Another example illustrates how to define a database that will select
the format of the articles depending on whether the client requests
MIME output.  Suppose that the configuration defines two dictionaries:
@samp{thes_plain}, with a thesaurus formatted in plaintext, and
@samp{thes_html}, with the same thesaurus, but formatted in HTML.  The
following database will return plaintext responses by default and HTML
responses after the @code{OPTION MIME} command:

@example
@group
database @{
  name "thesaurus";
  handler "virtual";
  database thes_plain nomime;
  database thes_html mime;
@}
@end group
@end example

Notice, that in this case it makes sense to define member databases
as invisible, to avoid duplicate matches. E.g.:

@example
@group
database @{
  name "thes_pain";
  visible no;
  ...
@}  
database @{
  name "thes_html";
  visible no;
  ...
@}  
@end group
@end example

To determine description (whether short or long) for a virtual
database, the following algorithm is used. If the @samp{description}
(or, for long description, @samp{info}) statement is present in the
@samp{database} block, its value is used. Otherwise, the server obtains 
descriptions of each member database that is visible in the current
@samp{OPTION MIME} state. If all databases return the same value, it
is used.  Otherwise, empty string is used.

Practically, that means that when defining a collection virtual
database (as in the first example above), you are better off supplying
both @samp{description} and @samp{info} statements.

On the other hand, when defining a mime-switching virtual database
with two members (as in the second example), you can safely omit both
statements: @command{dicod} will pick the value from the currently
active member database.

@node Strategies and Default Searches
@subsection Strategies and Default Searches
@cindex default searches
  A @dfn{default search} is a @code{MATCH} request with @samp{*} or
@samp{!} as the database argument (@pxref{MATCH}).  The former means
search in all available databases, the latter means search in all
databases until a match is found.

  Default searches may be quite expensive and may cause considerable
strain on the server.  For example, the command @code{MATCH * priefix
""} returns all entries from all available databases, which would
consume a lot of resources both on the server and on the client side.

  To minimize harmful effects from such potentially dangerous
requests, it is possible to limit the use of certain strategies in
default searches.

@deffn {Configuration} strategy @var{name} @{ @var{statements} @}
Restricts the use of the strategy @var{name} in default searches.
@end deffn

The @var{statements} define conditions the 4th argument of a
@code{MATCH} command must match in order to deny the request.  The
following statements are defined:

@deffn {Configuration} deny-all @var{bool}
Unconditionally deny the use of this strategy in default searches.
@end deffn

@deffn {Configuration} deny-word @var{list}
Deny this strategy if the search word matches one of the words from
@var{list}.
@end deffn

@deffn {Configuration} deny-length-lt @var{number}
Deny if length of the search word is less than @var{number}.
@end deffn

@deffn {Configuration} deny-length-le @var{number}
Deny if length of the search word is less than or equal to @var{number}.
@end deffn

@deffn {Configuration} deny-length-gt @var{number}
Deny if length of the search word is greater than @var{number}.
@end deffn

@deffn {Configuration} deny-length-ge @var{number}
Deny if length of the search word is greater than or equal to @var{number}.
@end deffn

@deffn {Configuration} deny-length-eq @var{number}
Deny if length of the search word is equal to @var{number}.
@end deffn

@deffn {Configuration} deny-length-ne @var{number}
Deny if length of the search word is not equal to @var{number}.
@end deffn

For example, the following statement denies the use of @samp{prefix}
strategy in default searches if its argument is an empty string:

@example
strategy prefix @{
  deny-length-eq 0;
@}
@end example

If the @code{dicod} daemon is configured this way, it will always return
a @samp{552} reply on commands @code{MATCH * prefix ""} or @code{MATCH
! prefix ""}.  However, the use of empty prefix on a concrete database, as
in @code{MATCH eng-deu prefix ""}, will still be allowed.
  
@node Tuning
@subsection Tuning

  While tuning your server, it is often necessary to get timing
information which shows how much time is spent serving certain
requests.  This can be achieved using the @code{timing} configuration
directive:

@deffn {Configuration} timing @var{boolean}
Provide timing information after successful completion of an
operation.  This information is displayed after the following
requests: @code{MATCH}, @code{DEFINE}, and @code{QUIT}.  It consists
of the following parts:

@example
[d/m/c = @var{nd}/@var{nm}/@var{nc} @var{RT}r @var{UT}u @var{ST}s]
@end example

@noindent
where:

@table @var
@item nd
Number of processed define requests.  It is @samp{0} after a
@code{MATCH} request.

@item nm
Number of processed match requests.  It is @samp{0} after a
@code{DEFINE} request. 

@item nc
Number of comparisons made.  This value may be inaccurate if the
underlying database module is not able to count comparisons.

@item RT
Real time spent serving the request.

@item UT
Time in user space spent serving the request.

@item ST
Time in kernel space spent serving the request.
@end table

An example of a server reply with timing information follows:

@example
250 Done [d/m/c = 0/63/107265 2.293r 1.120u 0.010s]
@end example
@end deffn

You can also add timing information to your access log files, see
@ref{Access Log, %T}.

@node Command Aliases
@subsection Command Aliases

  @dfn{Aliases} allow a string to be substituted for a word when it is used 
as the first word of a command.  The daemon maintains a list of
aliases that are created using the @code{alias} configuration file
statement:

@deffn {Configuration} alias @var{word} @var{command}
Creates a new alias. 
@end deffn

  Aliases are useful to facilitate manual interaction with the server,
as they allow the administrator to create abbreviations for some
frequently typed commands.  For example, the following alias creates
new command @code{d} which is equivalent to @code{DEFINE *}:

@example
alias d DEFINE "*";
@end example

  Aliases may be recursive, i.e. the first word of @var{command} may
refer to another alias.  For example:

@example
alias d DEFINE;
alias da d "*";
@end example

  This configuration will produce the following expansion:

@example
da word @result{} DEFINE * word
@end example

  To prevent endless loops, recursive expansion is stopped if the
first word of the replacement text is identical to an alias expanded
earlier. 

@node Preprocessor
@subsection Using Preprocessor to Improve the Configuration.
@cindex preprocessor
@cindex m4
  Before parsing its configuration file, @command{dicod} preprocesses
it.  The built-in preprocessor handles only file inclusion
and @code{#line} statements (@pxref{Pragmatic Comments}), while the
rest of traditional preprocessing facilities, such as macro expansion,
is supported via @command{m4}, which is used as an external preprocessor. 

  The detailed description of @command{m4} facilities lies far beyond
the scope of this document.  You will find a complete user manual in
@ifnothtml
@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
@end ifnothtml
@ifhtml
@uref{http://www.gnu.org/software/m4/manual}.
@end ifhtml
For the rest of this subsection we assume the reader is sufficiently
acquainted with @command{m4} macro processor.

@flindex pp-setup
  The external preprocessor is invoked with @option{-s} flag, instructing
it to include line synchronization information in its output.  This
information is then used by the parser to display meaningful
diagnostic.  An initial set of macro definitions is supplied by the 
@file{pp-setup} file, located in
@file{@var{$prefix}/share/dico/@var{version}/include} directory (where
@var{version} means the version of GNU Dico package).

The default @file{pp-setup} file changes quote characters to @samp{[}
and @samp{]}, and renames all @command{m4} built-in macros so they all
start with the prefix @samp{m4_}.  The latter has an effect similar 
to GNU @command{m4} @option{--prefix-builtin} option, but has an
advantage that it works with non-GNU @command{m4} implementations as well.  

As an example of how the use of preprocessor may improve
@command{dicod} configuration, consider the following fragment taken
from one of the installations of GNU Dico.  This installation offers quite
a few Freedict dictionaries.  The database definition for each of them
is almost the same, except for the dictionary name and eventual
description entry for several databases that miss it.  To avoid
repeating the same text over again, we define the following macro:

@example
@group
# defdb(@sc{name}[, @sc{descr}])
# @r{Produce a standard definition for a database @sc{name}}.
# @r{If @sc{descr} is given, use it as a description}.
m4_define([defdb], [
database @{
        name "$1";
        handler "dictorg database=$1";m4_dnl
m4_ifelse([$2],,,[
        description "$2";])
@}
])
@end group
@end example

It takes two arguments.  The first one, @sc{name}, defines the dictionary
name visible in the output of @code{SHOW DB} command.  Optional second
argument may be used to supply a description string for the databases
that miss it.

Given this macro, the database definitions look like:

@example
@group
defdb(eng-swa)
defdb(swa-eng)
defdb(afr-eng, Afrikaans-English Dictionary)
defdb(eng-afr, English-Afrikaans Dictionary)
@end group
@end example

@node Exit Codes
@section Dicod Exit Codes

  Apart from issuing a descriptive error message, @command{dicod}
attempts to indicate the reason of its termination by its error code.
As usual, a zero exit code indicates normal termination.  The table
below summarizes all possible error codes.   For each error code, it
indicates its decimal value and its symbolic name from
@file{include/sysexits.h} (if available).

@table @asis
@item 0
@itemx EX_OK
Program terminated correctly.

@item 2
Only child instances of @command{dicod} exit with this code.  It
indicates that the child did not receive any @samp{DICT} command
within the time out interval (@pxref{inactivity-timeout}).

@item 64
@itemx EX_USAGE
The program was invoked incorrectly, e.g. an invalid option was given,
or an erroneous argument was supplied to an option.

@item 67
@item EX_NOUSER
@command{Dicod} cannot switch to the privileges of the user it is
configured to run as (@pxref{user statement}).

@item 69
@itemx EX_UNAVAILABLE
The server exited due to some error not otherwise described in this table.

@item 70
@item EX_SOFTWARE
Some internal software error occurred.

@item 71
@itemx EX_OSERR
Some system error occurred, e.g. the program ran out of memory, or file
descriptors, or @samp{fork} failed, etc.

@item 78
@itemx EX_CONFIG
An error in the configuration file was detected.
@end table

@node Dicod Invocation
@section Dicod Invocation
@cindex invocation
@cindex command line options
@cindex options, @command{dicod}.
   This section summarizes @command{dicod} command line options.
Options are subdivided in five categories.

@menu
* Operation Mode::
* Help Options::
* Modifier Options::
* Preprocessor Control::
* Debugging Options::
@end menu

@node Operation Mode
@subsection Dicod Operation Mode   
The following options select the operation mode.  Only one of them can
be present in the command line:

@table @option
@item -E
Preprocess configuration file and exit.  @xref{Preprocessor}.

@opsummary{inetd}
@item -i
@itemx --inetd
Run in inetd mode.  @xref{Inetd Mode}.

@opsummary{runtest}
@item -r
@itemx --runtest
@itemx --test
Run unit tests for the module.  Arguments following that option are
parsed as follows:

@example
@var{modname} [@var{testargs}] [-- @var{initargs}]
@end example

@noindent
where @var{modname} stands for the name of the module to test,
@var{testargs} are arguments to the @code{dico_run_test} function of
the module, and @var{initargs} are module initialization arguments
(passed to the @code{dico_init} method).  Square brackets denote
optional parts.  Before passing to the corresponding method, both
argument lists are augmented by prepending module name as the first
element (with index 0).

This option implies @option{--stderr}.

@kwindex --load-dir
@kwindex -L
Use the @option{--load-dir} (@option{-L}) option (@pxref{--load-dir}),
if the module is not located in one of the default load directories
(@pxref{load path}).

@xref{Unit Testing}, for a detailed discussion of module unit testing.

@opsummary{lint}
@item -t
@itemx --lint
Check configuration file syntax and exit with code @samp{0} if it is
OK, or with @samp{78} if there are errors.  @xref{Configuration}.
@end table

@node Help Options
@subsection Informational Options

The informational options cause the program to print a selected piece
of information and exit.  Only one informational option can be used at
a time.

@table @option
@opsummary{config-help}
@item --config-help
Show a summary of the configuration file syntax and allowed
statements.  @xref{Configuration}.

@opsummary{help}
@item -h
@itemx --help
Display a short command line option summary and exit.

@opsummary{usage}
@item --usage
List all available command line options and exit.

@opsummary{version}
@item --version
Print program version and exit.
@end table

@node Modifier Options
@subsection Modifier Options
These options modify the program behavior:

@table @option
@opsummary{config}
@item --config=@var{file}
Read this configuration file instead of the default
@file{@var{$sysconfdir}/dicod.conf}.  @xref{Configuration}.

@opsummary{foreground}
@item -f
@itemx --foreground
Operate in foreground.  @xref{Daemon Mode}.

@opsummary{load-dir}
@item -L @var{dir}
@itemx --load-dir=@var{dir}
Adds @var{dir} to the beginning of module load path.  @xref{load
path}, for  detailed discussion.

@opsummary{single-process}
@item -s
@itemx --single-process
In daemon mode, process connections in the main process, without
starting subprocesses for each connection (@pxref{Daemon Mode}).  This
means that the daemon is able to serve only one client at a time.  The
@option{--single-process} option is provided for debugging purposes
only.  Never use it in production environment.

@opsummary{stderr}
@item --stderr
Output the diagnostics to stderr.  @xref{Daemon Mode, --stderr}.

@opsummary{syslog}
@item --syslog
After successful startup, output any diagnostic to syslog.  This is
the default.
@end table

@node Preprocessor Control
@subsection Preprocessor Control

The following options control the use of preprocessor.
@xref{Preprocessor}, for a detailed discussion.

@table @option
@opsummary{define}
@item --define=@var{symbol}[=@var{value}]
@itemx -D @var{symbol}[=@var{value}]
Define the preprocessor symbol @var{symbol}.  Optional @var{value}
supplies the new symbol value.  This option is passed to the
preprocessor verbatim.

@opsummary{include-dir}
@item -I @var{dir}
@itemx --include-dir=@var{dir}
Add the directory @var{dir} to the list of directories to be searched for
preprocessor include files.  @xref{Preprocessor}.

@opsummary{no-preprocessor}
@item --no-preprocessor
Do not use external preprocessor.  @xref{Preprocessor}.

@opsummary{preprocessor}
@item --preprocessor=@var{prog}
Use @var{prog} as a preprocessor for configuration file.  The default
preprocessor command line is @command{m4 -s}, unless overridden while
configuring the package (@pxref{Default Preprocessor}).
@end table

@node Debugging Options
@subsection Debugging Options
@table @option
@opsummary{debug}
@item -x
@itemx --debug=@var{level}
Set debug verbosity level.  The @var{level} argument is an integer 
ranging from @samp{0} (no debugging) to @samp{100} (maximum debugging
information).

@opsummary{no-transcript}
@item --no-transcript
Disable transcript mode.  This is the default.  Use this option if you
wish to temporarily disable transcript mode, enabled in the
configuration file (@pxref{Logging and Debugging, transcript}).

@opsummary{transcript}
@item -T
@itemx --transcript
Enable session transcript.  This instructs @command{dicod} to log
all commands it receives and all responses it sends during the
session.  Transcript is logged via the default logging channel
(@pxref{Logging and Debugging}).  If logging via syslog, the
@samp{debug} priority is used.

See also @ref{Session Transcript}, for a description of the similar
mode in @command{dico}, the client program.

@opsummary{source-info}
@item --source-info
Include source line information in the debugging output.

@opsummary{trace-grammar}
@item --trace-grammar
Trace parsing of the config file.

@opsummary{trace-lex}
@item --trace-lex
Trace the configuration file lexer.
@end table

@node Modules
@chapter Modules
@cindex Modules
  GNU Dico comes with a set of loadable modules for handling various
database formats and extending the server functionality.  Modules
are binary loadable files, installed in
@file{@var{$prefix}/lib/dico}.  They are configurable on per-module
(@pxref{Handlers, command}) and per-database (@pxref{Databases,
handler}) basis.

  In this chapter we will describe the modules included in the 
distribution of GNU Dico version @value{VERSION}.

@menu
* outline::
* dictorg::
* gcide::
* wordnet::
* guile::
* python::
* stratall::
* substr::
* word::
* nprefix::
* metaphone2::
* pcre::
* ldap::
* pam::
* greek_kbd::
@end menu

@node outline
@section @command{Outline}
@cindex outline module
  The @command{outline} module supports databases written in
@dfn{Emacs outline mode}.  It is not designed for storing large
amounts of data, its purpose rather is to handle small databases that
can be composed easily and quickly using the Emacs editor.

@cindex outline mode
  The outline mode is described in @ref{Outline Mode, Outline Mode,
Outline Mode, emacs, The Emacs Editor}.  In short, it is a usual plain
text file, containing @dfn{header lines} and @dfn{body lines}.  Header
lines start with one or more stars, the number of starts indicating
the nesting level of the heading in the document structure: one star for
chapters, two stars for sections, etc.  Body lines are anything that
is not header lines.

@cindex outline dictionary
  The outline dictionary must have at least a chapter named
@samp{Dictionary}, which contains the dictionary corpus.  Within it, each
section is treated as a dictionary article, its header line giving
the headword, and its body lines supplying the article itself.  Apart
from this, two more chapters have special meaning.  The
@samp{Description} chapter gives a short description to be displayed
on @code{SHOW DB} command, and the @samp{Info} chapter supplies a full
database description for @code{SHOW INFO} output.  Both chapters are
optional.

  All three reserved chapter names are case-insensitive.

  To summarize, the structure of an outline database is:

@example
* Description
@var{line}
   
* Info
@var{text}

* Dictionary

** @var{line}
@var{text}

[@r{any number of entries follows}]
@end example

@cindex Ambrose Bierce
@cindex Devil's Dictionary
@flindex devils.out
  As an example of outline format, the GNU Dico package includes
Ambrose Bierce's @cite{Devil's Dictionary} in this format, see
@file{examples/devdict.out}. 

  The initialization of the @command{outline} module does not require
any command line parameters.  To declare a database, supply its full
file name to the database @code{handler} directive, as shown in the
example below:

@example
@group
load-module outline;

database @{
   name "devdict";
   handler "outline /var/db/devdict.out";
@}
@end group
@end example

@node dictorg
@section @command{Dictorg}
@cindex dictorg module
  The @command{dictorg} module supports dictionaries in the format
designed by @cite{@acronym{DICT} development group}
(@uref{http://dict.org}).  Lots of free dictionaries in this format
are available from the @uref{http://freedict.org, @cite{FreeDict}
project}.

  A dictionary in this format consists of two files: a @dfn{dictionary
database file}, named @file{@var{name}.dict} or
@file{@var{name}.dict.dz} (a compressed form), and an @dfn{index file},
which lists article headwords with the corresponding offsets in the
database.  The index file is named @file{@var{name}.index}.  The
common part of these two file names, @var{name}, is called the @dfn{base
name} for that dictionary.

@cindex dictorg handler definition
  An instance of the @command{dictorg} module is created using the
following statement:

@example
load-module @var{inst-name} @{
    command "dictorg [@var{options}]";
@}
@end example

@noindent
where square brackets denote optional part.  Valid @var{options} are
the following:

@cindex dictorg initialization options
@table @option
@kwindex dbdir
@item dbdir=@var{dir}
Look for databases in directory @var{dir}.

@kwindex show-dictorg-entries
@item show-dictorg-entries
@dfn{Dictorg entries} are special database entries that keep some
service information, such as database description, etc.  Such entries
are marked with headwords that begin with @samp{00-database-}.  By
default they are exempt from database look-ups and cannot be retrieved
using @code{MATCH} or @code{DEFINE} command.

Using @option{show-dictorg-entries} removes this limitation.

@kwindex sort
@item sort
Sort the database index after loading.  This option is designed for
use with some databases that have malformed indexes.  At the time of
this writing the @samp{eng-swa} database from @cite{FreeDict} requires
this option.

Using @code{sort} may considerably slow down initial database loading.

@kwindex trim-ws
@item trim-ws
Remove trailing whitespace from dictionary headwords at start up.
This might be necessary for some databases.
@end table

The values set via these options become defaults for all databases
using this module instance, unless overridden in their declarations.

@cindex dictorg database declaration
A database that uses this module must be declared as follows:

@example
@group
database @{
    handler "@var{inst-name} database=@var{file} [@var{options}]";
    ...
@}
@end group
@end example

@noindent
where @var{inst-name} is the instance name used in the @code{load-module}
declaration above.

@kwindex database
  The @code{database} argument specifies the base name of the
database.  Unless @var{file} begins with a slash, the value of
@code{dbdir} initialization option is prepended to it.  If
@code{dbdir} is not given and @var{file} does not begin with a slash,
an error is signalled.

@kwindex noshow-dictorg-entries
@kwindex nosort
@kwindex notrim-ws
  The @var{options} above are the same options as described in
initialization procedure: @code{show-dictorg-entries}, @code{sort},
and @code{trim-ws}.  If used, they override initialization settings for
that particular database.  Forms prefixed with @samp{no} can be used
to disable the corresponding option for this database.  For example, 
@code{notrim-ws} cancels the effect of @code{trim-ws} used when
initializing the module instance.

@node gcide
@section @command{Gcide}
@cindex gcide module
@cindex GNU Collaborative International Dictionary of English
  The @command{gcide} module provides support for GNU Collaborative
International Dictionary of English.  This dictionary can be downloaded
from @uref{ftp://ftp.gnu.org/gnu/gcide}.  It consists of a set of
files named from @file{CIDE.A} through @file{CIDE.Z}, written using a
special markup.  See @uref{http://gcide.gnu.org.ua}, for a detailed
information about the dictionary.

  The @command{gcide} module is started via the following statement:

@example
load-module gcide;
@end example

@kwindex dbdir
  The database is initialized as follows:

@example
@group
database @{
    handler "gcide dbdir=@var{directory} [@var{options}]";
    ...
@}
@end group
@end example

The @samp{dbdir} parameter supplies the name of the directory where
database files are located.  Upon startup, the module scans the
dictionary files and creates an index file, named @file{GCIDE.IDX}, if
it does not already exist.  The file is created using an ancillary
program @command{idxgcide}, described below.  Unless specified
otherwise, this file is created in the same directory where the
database files are located, therefore the directory must be writable
for the user @command{dicod} is started as.

Other options are:

@deffn {gcide parameter} html
Enables HTML output.  To request results in HTML, the client must
issue @command{OPTION MIME} command.
@end deffn

@deffn {gcide parameter} idxdir directory
Specifies the directory where the @file{CIDE.IDX} index file resides
or should reside.
@end deffn

@deffn {gcide parameter} index-cache-size size
Sets the maximum number of index pages the module keeps in memory
simultaneously.  The default value is 16.  The pages are cached using
the @dfn{last recently used} algorithm.  Raising this value will make
dictionary accesses faster at the expense of using more memory.
@end deffn

@deffn {gcide parameter} index-program progname
Specifies the full name of the index program.  Usually this option is
not needed, because the module is configured to start the
@command{idxgcide} utility from its default location.  It is mostly
useful for the module developers.
@end deffn

@deffn {gcide parameter} watch
Watch for modifications in the dictionary corpus.  If any of the
dictionary files is modified, recreate the index file.  Use this
option if you expect to update dictionary files often.
@end deffn

@deffn {gcide parameter} suppress-pr
This parameter suppresses the output of @samp{pr} (pronunciation)
tags.  According to GCIDE docs, @cite{very few of the pronunciation
fields have been filled in}, so it might be reasonable to avoid
displaying them at all.
@end deffn

  Starting from version 0.51, GCIDE contains the file @file{INFO},
which provides basic information about the dictionary.  The
@command{gcide} module returns contents of this file at the
@samp{SHOW INFO} request.  The first line of this file (with the
trailing newline and final point removed) is returned as the short
database description.

  Here's a full example of a @samp{gcide} as used in
@indicateurl{dico.gnu.org.ua}:

@example
@group
load-module gcide;

database @{
    name "gcide";
    handler "gcide dbdir=/var/dictdb/gcide-0.51 suppress-pr";
    languages-from "en";
    languages-to "en";
@}
@end group
@end example

@menu
* idxgcide::
@end menu

@node idxgcide
@subsection @command{idxgcide}
  The @command{idxgcide} utility is used by the @command{gcide} module
to index the GCIDE dictionary.  You can start it manually to reindex
the database.  It can be needed, for example, if you install a
modified version of the dictionary.  The program is installed in
@dfn{libexecdir}.  The usage is:

@example
idxgcide [@var{options}] @var{dbdir} [@var{idxdir}]
@end example

The only mandatory argument @var{dbdir} specifies the name of the
directory where the GCIDE dictionary is installed.  The optional
@var{idxdir} argument specifies the directory for the index file, if
it differs from @var{dbdir}.  Available @var{options} are:

@table @option
@item --debug=[@var{letters}]
@itemx -d[@var{letters}]
Debug lexical analyzer.  Optional argument specifies letters of
alphabet, for which debug should be enabled.  E.g. @option{--debug=FP}
enables debugging only for files @file{CIDE.F} and @file{CIDE.P}.
Without arguments, this option enables debugging for all corpus files.

@item --dry-run
@itemx -n
Do nothing, but print everything.  This implies @option{--verbose}.

@item --verbose
@itemx -v
Increase output verbosity.  This option can be specified multiple
times, each occurrence increasing the verbosity level by one.  By
default the utility outputs only errors and warnings.  At level one,
it prints additionally the names of source files that are being
indexed at the moment.  At level two (the maximum level implemented at
the moment) it outputs each headword being indexed along with its
location.  This is useful only for debugging.

@item --page-size=@var{number}
@itemx -p @var{number}
Defines the size of index file page.  The @var{number} specifies the
size in bytes.  The following case-insensitive suffixes can be used:
@samp{k} (@samp{kb}), @samp{m} (@samp{mb}) or @samp{g} (@samp{gb}),
specifying kilobytes, megabytes and gigabytes (ouch!) correspondingly.

The default page size is 10240 bytes.

@item -# @var{fd}
@itemx --file-descriptor=@var{fd}
Operate on the index file which is open at file descriptor @var{fd}.
The @command{gcide} module uses this option to pass the descriptor of
the @file{GCIDE.IDX} file to the indexer.
@end table

@node wordnet
@section @command{Wordnet}
@cindex wordnet module
@dfn{WordNet} is a lexical database for the English language, created
and maintained at the Cognitive Science Laboratory of Princeton
University@footnote{See @uref{http://wordnet.princeton.edu/wordnet/},
for a detailed information, including links to download.}.  It groups
English words into sets of synonyms called @dfn{synsets}, provides short,
general definitions, and records the various semantic relations
between these synonym sets.

@cindex libWN
Dico provides a @command{wordnet} module for reading WordNet lexical
database files.  The module relies on @file{libWN}, the support
library distributed with the WordNet database. 

@cindex WordNet, configuring
There is a point worth noticing if you plan to use the WordNet
library.  Normally, the @file{libWN} is compiled as a static library
with position-dependent code, which makes it difficult (or impossible,
on 64-bit architectures) to use from the dynamically-loaded libraries,
such as @command{dicod} modules.  So, first of all you will need to
rebuild WordNet so that it contains position-independent code.  To do
so, change to the WordNet source directory and reconfigure it as
follows: 

@example
  ./configure CFLAGS=-fPIC [@var{other_options}]
@end example

where @var{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 advisable to run @samp{make distclean}
beforehand.

@cindex wordnet-dev
@cindex libwordnet
@opindex --with-libWN, @command{configure} option
Debian-based systems provide a package @samp{wordnet-dev}, which contains
a properly built shared library.  However, this library is named
@samp{libwordnet.so}, instead of the expected @samp{libWN.so}.  On
such systems you will have to use the @option{--with-libWN} option to
configure, in order to inform it about the change:

@example
  ./configure --with-libWN=wordnet
@end example

Argument to this option is the new basename for the libWN library,
without file suffix. Optionally, the @samp{lib} prefix is allowed,

@findex wn.h
@opindex --with-wordnet, @command{configure} option.
The @command{wordnet} module is compiled automatically if the
configure script was able to find the library and its header file
@file{wn.h}.  If it was not, use the @option{--with-wordnet} configure
option to specify the location where these files can be found.  For
example, if WordNet was installed using the default procedure, then
the following option will do the job:

@example
  ./configure --with-wordnet=/usr/local/WordNet-3.0
@end example

This command tells Dico to look for WordNet library files in
@file{/usr/@/local/@/WordNet-3.0/@/lib} and for include files in
@file{/usr/@/local/@/WordNet-3.0/@/include}.

A compiled module is loaded using the following statement:

@example
load-module wordnet @{
    command "wordnet [@var{parameters}]";
@}
@end example

Optional parameters are:

@deffn {wordnet module parameter} wnhome dir
Base directory for WordNet files.  This is the directory where WordNet
was installed.  For the @command{wordnet} module to work, it must
contain the @file{dict} subdirectory with WordNet dictionary files.

If you installed WordNet to @file{/usr/local/WordNet-3.0}, so that
running @command{ls} on that directory shows you:

@example
$ ls /usr/local/WordNet-3.0/
bin/  dict/  doc/  include/  lib/  man/
@end example

@noindent
then you would use

@example
load-module wordnet @{
    command "wordnet wnhome=/usr/local/WordNet-3.0";
@}
@end example
@end deffn

@deffn {wordnet module parameter} wnsearchdir dir
Directory in which the WordNet database has been installed.
@end deffn

Normally, these values are set at compile time and you won't need to
override them.  The use of these parameters may, however, be necessary
if the database was moved or installed in a non-standard location.

One or more WordNet database instances can be defined.  They all will
be sharing the same database.  The reason for having several database
instances is that they may have different output options.  For
example, you may configure one database to return word definitions and
another one to act as a thesaurus.

Dico version @value{VERSION} defines the following database parameters:

@deffn {wordnet database parameter} pos value
Select part of speech to be displayed by this database.  By default,
all parts of speech are displayed.  Valid values are:

@table @asis
@item all
Display all parts of speech.  This is the default.

@item noun
Display only nouns.

@item verb
Display only verbs.

@item adj
@itemx adjective
Display only adjectives.

@item adv
@itemx adverb
Display only adverbs.

@item satellite
@itemx adjsat
Display only @dfn{satellites}.
@end table
@end deffn

@deffn {wordnet database parameter} merge-defs
When specified, this parameter instructs the WordNet database to merge
all definitions with the same part of speech into a single definition,
which will be returned in the usual dictionary fashion, e.g.:

@example
@group
sail
n. 1. a large piece of fabric (usually canvas fabric) by
means of which wind is used to propel a sailing vessel 
Synonyms: @{canvas@}, @{canvass@}, @{sheet@}
2. an ocean trip taken for pleasure
Synonyms: @{cruise@}
3. any structure that resembles a sail
v. 1. traverse or travel on (a body of water); "We sailed
the Atlantic"; "He sailed the Pacific all alone" 
2. move with sweeping, effortless, gliding motions
@end group
@end example

By default, each definition is returned as a separate entry.
@end deffn

As an example, the following is the database definition the author
uses on his server:

@example
@group
database @{
    name "WordNet";
    handler "wordnet merge-defs";
    languages-from "en";
    languages-to "en";
    description "WordNet dictionary, version 3.0";
@}
@end group
@end example

@node guile
@section @command{Guile}
@cindex guile module
@cindex Guile
@cindex Scheme
  @dfn{Guile} is an acronym for @dfn{GNU's Ubiquitous Intelligent
Language for Extensions}.  It provides a Scheme interpreter conforming
to the R5RS language specification and a number of convenience
functions.  For information about the language, refer to
@ref{Top,,,r5rs,Revised(5) Report on the Algorithmic Language Scheme}.
For a detailed description of Guile and its features, see
@ref{Top,,Overview,guile,The Guile Reference Manual}.

  The @command{guile} module provides an interface to Guile that
allows for writing GNU Dico modules in Scheme.  The module is loaded
using the following configuration file statement:

@example
@group
load-module @var{mod-name} @{
   command "guile [@var{options}]"
           " init-script=@file{@var{script}}"
           " init-args=@var{args}"
           " init-fun=@var{function}";
@}
@end group
@end example

@kwindex init-script
@kwindex init-args
@kwindex init-fun
  The @code{init-script} parameter specifies the name of a Scheme
source file to be loaded in order to initialize the module.
The @code{init-args} parameter supplies additional arguments to the
module.  They will be accessible to the @file{@var{script}} via
@code{command-line} function.  This parameter is optional.

  The @code{init-fun} parameter specifies the name of a function that
will be invoked to perform initialization of the module and of
particular databases.  @xref{Guile Initialization}, for a description
of initialization sequence.  Optional arguments, @var{options}, are:

@table @code
@kwindex debug
@item debug
  Enable Guile debugging and stack traces.

@kwindex nodebug
@item nodebug
  Disable Guile debugging and stack traces (default).

@kwindex load-path
@item load-path=@var{path}
  Append directories from @var{path} to the list of directories which
should be searched for Scheme modules and libraries.  The @var{path}
must be a list of directory names, separated by colons.

  This option modifies the value of Guile's @code{%load-path}
variable.
@c FIXME: Texi2html is unable to handle \, in the section title.  This
@c conditional overrides this bug.
@ifnothtml
@xref{Build Config, %load-path,
Configuration Build and Installation, guile, The Guile Reference Manual}.
@end ifnothtml
@ifhtml
See the section @uref{http://www.gnu.org/software/guile/manual/html_node/Build-Config.html, Configuration and Installation} in the Guile Reference Manual.
@end ifhtml

@end table

@anchor{guile-cmdline}
@noindent
Guile databases are declared using the following syntax:

@example
@group
database @{
        name "@var{dbname}";
        handler "@var{mod-name} [@var{options}] @var{cmdline}";
@}
@end group
@end example

@noindent
where:

@table @var
@item dbname
gives the name for this database,

@item mod-name
the name given to Guile module in @code{load-module} statement (see
above),

@item options
@kwindex init-script
@kwindex init-args
@kwindex init-fun
options that override global settings given in the
@code{load-module} statement.  The following options are understood:
@code{init-script}, @code{init-args}, and @code{init-fun}.  Their
meaning is the same as for @code{load-module} statement (see above),
except that they affect only this particular database.

@item cmdline
the command line that will be passed to the Guile
@code{open-db} callback function (@pxref{open-db}).
@end table

@menu
* Virtual Functions::
* Guile Initialization::
* Guile API::
* Dico Scheme Primitives::
* Example Module::
@end menu

@node Virtual Functions
@subsection Virtual Functions
@cindex virtual functions, guile module
  A database handled by the @command{guile} module is assigned a 
@var{virtual function table}.  This table is an association list which
keeps Scheme @dfn{call-back functions} implemented to perform
particular tasks on that database.  In this list, the @code{car} of
each element contains the name of a function, and its @code{cdr} gives
the corresponding function.  The defined function names and their
semantics are:

@table @asis
@item open
Open the database.

@item close
Close the database.

@item descr
Return a short description of the database.

@item info
Return a full information about the database.

@item define
Define a word.

@item match
Look up a word in the database.

@item output
Output a search result.

@item result-count
Return number of entries in the result.
@end table

For example, the following is a valid virtual function table:

@smalllisp
@group
(list (cons "open" open-module)
      (cons "close" close-module)
      (cons "descr" descr)
      (cons "info" info)
      (cons "define" define-word)
      (cons "match" match-word)
      (cons "output" output)
      (cons "result-count" result-count))
@end group
@end smalllisp

Apart from a per-database virtual table, there is also a global
virtual function table, which supplies entries missing in
the former.  Both tables are created during the module initialization,
as described in the next subsection.

The purposes of particular virtuals functions are described in
@ref{Guile API}.

@node Guile Initialization
@subsection Guile Initialization
  The following configuration statement causes loading and
initialization of the @command{guile} module: 

@example
@group
load-module @var{mod-name} @{
   command "guile init-script=@var{script}"
           " init-fun=@var{function}";
@}
@end group
@end example
@kwindex init-script
@kwindex init-fun
  Upon module initialization stage, the module attempts to load the
file named @file{@var{script}}.  The file is loaded using
@code{primitive-load} call (@pxref{Loading, primitive-load, Loading,
guile, The Guile Reference Manual}), i.e. the load paths are not
searched, so @var{script} must be an absolute path name.  The
@code{init-fun} parameter supplies the name of the @dfn{initialization
function}.  This Scheme function constructs virtual 
function tables for the module itself and for each database that uses
this module.  It must be declared as follows:

@smalllisp
(define (@var{function} arg)
  ...)
@end smalllisp

This function is called several times.  First of all, it is called after
the @var{script} is loaded.  This time it is given @code{#f} as its
argument, and its return value is saved as a global function table.
Then, it is called for each @code{database} statement that has
@var{mod-name} (used in @code{load-module} above) in its
@code{handler} keyword, e.g.:

@example
@group
database @{
   name @var{db-name};
   handler "@var{mod-name} @dots{}";
@}
@end group
@end example

This time, it is given @var{db-name} as its argument and the value it
returns is stored as the virtual function table for this particular
database.

The following example function returns a complete virtual function table:

@smalllisp
@group
(define-public (my-dico-init arg)
  (list (cons "open" open-module)
        (cons "close" close-module)
        (cons "descr" descr)
        (cons "info" info)
        (cons "lang" lang)
        (cons "define" define-word)
        (cons "match" match-word)
        (cons "output" output)
        (cons "result-count" result-count)))
@end group
@end smalllisp

@node Guile API
@subsection Guile API
@cindex Guile API  

  This subsection describes callback functions that a Guile
database module must provide.  Each description begins with the
function prototype and its entry in the virtual function table.

  Callback functions can be subdivided into two groups: database
functions and search functions. 

  Database callback functions are responsible for opening and closing
databases and for returning information about them.

@anchor{open-db}
@deffn {Guile Callback} open-db name . args
Virtual table: @code{(cons "open" open-db)}@*

Open the database.  The argument @var{name} contains database name as
given in the @code{name} statement of the corresponding
@code{database} block (@pxref{Databases}).  Optional argument
@var{args} is a list of command line parameters obtained from
@var{cmdline} in @code{handler} statement (@pxref{guile-cmdline}).
For example, if the configuration file contained: 

@example
@group
database @{
    name "foo";
    handler "guile db=file 1 no";
@}
@end group
@end example

@noindent
then the @code{open-db} callback will be called as:

@smalllisp
(open-db "foo" '("db=file" "1" "no"))
@end smalllisp

The @code{open-db} callback returns a @dfn{database handle}, i.e. an
opaque object that will subsequently be used to identify this
database.  This value, hereinafter named @var{dbh}, will be passed to
another callback functions that need to access the database.

The return value @code{#f} or @code{'()} indicates an error.
@end deffn

@deffn {Guile Callback} close-db dbh
Virtual Table: @code{(cons "close" close-db)}@*

Close the database.  This function is called during the cleanup
procedure, before termination of @code{dicod}.  The argument
@code{dbh} is a database handle returned by @code{open-db}.

The return value from @code{close-db} is ignored.  To communicate
errors to the daemon, throw an exception.
@end deffn

@deffn {Guile Callback} descr dbh
Virtual Table: @code{(cons "descr" descr)}@*

Return a short textual description of the database, for use in
@code{SHOW DB} output.  If there is no description, returns @code{#f}
or @code{'()}. 

The argument @var{dbh} is a database handle returned by
@code{open-db}.

This callback is optional.  If it is not defined, or if it returns
@code{#f} (@code{'()}), the text from @code{description} statement
is used (@pxref{Databases, description}).  Otherwise, if no
@code{description} statement is present, an empty string will be returned.
@end deffn

@deffn {Guile Callback} info dbh
Virtual Table: @code{(cons "info" info)}@*

Return a verbose, eventually multi-line, textual description of the
database, for use in @code{SHOW INFO} output.  If there is no
description, returns @code{#f} or @code{'()}. 

The argument @var{dbh} is a database handle returned by @code{open-db}.

This callback is optional.  If it is not defined, or if it returns
@code{#f} (@code{'()}), the text from @code{info} statement
is used (@pxref{Databases, info}).  If there is no @code{info} statement,
the string @samp{No information available} is used.
@end deffn

@deffn {Guile Callback} lang dbh
Virtual Table: @code{(cons "lang" lang)}@*

Return a @code{cons} of languages supported by this database:
Its @code{car} is a list of source languages, and its @code{cdr} is a
list of destination languages.  For example, the following return
value indicates that the database contains translations from English
to French and Spanish:

@example
 (cons (list "en") (list "fr" "es"))
@end example
@end deffn

A database is searched in a two-phase process.  First, an appropriate
callback is called to do the search: @code{define-word} is called for
@code{DEFINE} searches and @code{match-word} is called for matches.
This callback returns an opaque entity, called @dfn{result handle},
which is then passed to the @code{output} callback, which is responsible
for outputting it.

@deffn {Guile Callback} define-word dbh word
Virtual Table: @code{(cons "define" define-word)}@*

Find definitions of word @var{word} in the database @var{dbh}.  Return
a result handle.  If nothing is found, return @code{#f} or @code{'()}.

The argument @var{dbh} is the database handle returned by @code{open-db}.
@end deffn

@anchor{match-word}
@deffn {Guile Callback} match-word dbh strat key
Virtual Table: @code{(cons "match" match-word)}@*

Find in the database @var{dbh} all headwords that match @var{key}, using
strategy @var{strat}.  Return a result handle.  If nothing is
found, return @code{#f} or @code{'()}. 

The @var{key} is a @dfn{Dico Key} object, which contains information
about the word being looked for.  To obtain the actual word, use
the @code{dico-key->word} function (@pxref{dico-key->word}).

The argument @var{dbh} is a database handle returned by
@code{open-db}.  The matching strategy @var{strat} is a special Scheme
object that can be accessed using a set of functions described below
(@pxref{Dico Scheme Primitives}). 
@end deffn

@deffn {Guile Callback} result-count resh
Virtual Table: @code{(cons "result-count" result-count)}@*

Return the number of elements in the result set @var{resh}.
@end deffn

@deffn {Guile Callback} output resh n
Virtual Table: @code{(cons "output" output)}@*

Output @var{n}th result from the result set @var{resh}.  The argument
@var{resh} is a result handle returned by @code{define-word} or
@code{match-word} callback.

The data must be output to the current output port, e.g. using
@code{display} or @code{format} primitives.  If @var{resh} represents
a match result, the output must not be quoted or terminated by
newlines.

It is guaranteed that the @code{output} callback will be called
as many times as there are elements in @var{resh} (as determined by the
@code{result-count} callback) and that for each subsequent call the
value of @var{n} equals its value from the previous call incremented
by one.

At the first call @var{n} equals 0.
@end deffn

@node Dico Scheme Primitives
@subsection Dico Scheme Primitives
@cindex strategy functions, Scheme
@cindex strategy functions, Guile
@cindex key (a Scheme object) functions
@cindex Scheme strategy and key functions
@cindex Guile strategy and key functions
  GNU Dico provides the following Scheme primitives for accessing various
fields of the @code{strat} and @code{key} arguments to @code{match} callback:

@defun dico-key? @var{obj}
Return @samp{#t} if @var{obj} is a Dico key object.
@end defun

@anchor{dico-key->word}
@defun dico-key->word @var{key}
Extract the lookup word from the key object @var{key}.
@end defun

@defun dico-make-key @var{strat} @var{word}
Create new key object from strategy @var{strat} and word @var{word}.
@end defun

@defun dico-strat-selector? @var{strat}
Return true if @var{strat} has a selector (@pxref{Selector}).
@end defun

@defun dico-strat-select? @var{strat} @var{word} @var{key}
Return true if @var{key} matches @var{word} as per strategy selector
@var{strat}.  The @var{key} is a @samp{Dico Key} object.
@end defun

@defun dico-strat-name @var{strat}
Return the name of strategy @var{strat}.
@end defun

@defun dico-strat-description @var{strat}
Return a textual description of the strategy @var{strat}.
@end defun

@defun dico-strat-default? @var{strat}
Return @code{true} if @var{strat} is a default
strategy.  @xref{MATCH, default strategy}.
@end defun

@defun dico-register-strat @var{strat} @var{descr} [@var{fun}]
Register a new strategy.  If @var{fun} is given it will be used as a
callback for that strategy.  Notice, that you can use strategies
implemented in Guile in your C code as well (@pxref{MATCH, strategy}).

  The selector function must be declared as follows:

@smalllisp
(define (@var{fun} key word)
  ...)
@end smalllisp

It must return @code{#t} if @var{key} matches @var{word}, and
@code{#f} otherwise.
@end defun

@node Example Module
@subsection Example Module
  In this subsection we will show how to build a simple @command{dicod} module
written in Scheme.  The source code of this module, called
@file{listdict.scm} and a short database for it, @file{numerals-pl.db}, are
shipped with the distribution in the directory @file{examples}.

  The database is stored in a disk file in form of a list.  The first
two elements of this list contain database description and full
information strings.  Rest of elements are conses, whose @code{car}
contains the headword, and @code{cdr} contains the corresponding
dictionary article.  Following is an example of such a database:

@example
("Short English-Norwegian numerals dictionary"
 "Short English-Norwegian dictionary of numerals (1 - 7)"
 ("one" . "en")
 ("two" . "to")
 ("three" . "tre")
 ("four" . "fire")
 ("five" . "fem")
 ("six" . "seks")
 ("seven" . "sju"))
@end example

  We wish to declare such databases in @file{dicod.conf} the following
way:
  
@example
database @{
        name "numerals";
        handler "guile example.db";
@}
@end example

@noindent
Thus, the @code{rest} argument to @samp{open-db} callback will be
@samp{("guile" "example.db")} (@pxref{open-db}).  Given this, we may
write the callback as follows:

@smalllisp
(define (open-db name . rest)
  (let ((db (with-input-from-file
                (cadr rest)
              (lambda () (read)))))
    (cond
     ((list? db) (cons name db))
     (else
      (format (current-error-port) "open-module: ~A: invalid format\n"
              (car args))
      #f))))
@end smalllisp

  The list returned by this callback will then be passed as a database
handle to another callback functions.  To facilitate access to
particular elements of this list, it is convenient to define the
following syntax:

@smalllisp
(define-syntax db:get
  (syntax-rules (info descr name corpus)
    ((db:get dbh name)   ;; @r{Return the name of the database.}
     (list-ref dbh 0))
    ((db:get dbh descr)  ;; @r{Return the desctiption.}
     (list-ref dbh 1))
    ((db:get dbh info)   ;; @r{Return the info string.} 
     (list-ref dbh 2))
    ((db:get dbh corpus) ;; @r{Return the word list.}
     (list-tail dbh 3))))
@end smalllisp

  Now, we can write @samp{descr} and @samp{info} callbacks:

@smalllisp
(define (descr dbh)
  (db:get dbh descr))

(define (info dbh)
  (db:get dbh info))
@end smalllisp

  The two callbacks @samp{define-word} and @samp{match-word} provide
the core module functionality.  Their results will be passed to
@samp{output} and @samp{result-count} callbacks as a ``result handler''
argument.  In the spirit of Scheme, we make the result a list.  Its
@code{car} is a boolean value: @code{#t}, if the result
comes from @samp{define-word} callback, and @code{#f} if it comes from
@samp{match-word}.  The @code{cdr} of this list contains a list of
matches.  For @samp{define-word}, it is a list of conses copied from
the database word list, whereas for @samp{match-word}, it is a list of
headwords. 

  The @samp{define-word} callback returns all list entries whose
@code{car}s contain the look up word.  It uses @code{mapcan}
function, which is supposed to be defined elsewhere:
  
@smalllisp
(define (define-word dbh word)
  (let ((res (mapcan (lambda (elt)
                       (and (string-ci=? word (car elt))
                            elt))
                     (db:get dbh corpus))))
    (and res (cons #t res))))
@end smalllisp

  The @samp{match-word} callback (@pxref{match-word}) takes three
arguments: a database handler @var{dbh}, a strategy descriptor
@var{strat}, and a word @var{word} to look for.  The result handle it
returns contains a list of headwords from the database that match
@var{word} in the sense of @var{strat}.  Thus, the behavior of
@samp{match-word} depends on the @var{strat}.  To implement
this, let's define a list of directly supported strategies (see below
for definitions of particular @samp{match-} functions):

@smalllisp
(define strategy-list
  (list (cons "exact"  match-exact)
        (cons "prefix"  match-prefix)
        (cons "suffix"  match-suffix)))
@end smalllisp

  The @samp{match-word} callback will then select an entry from
that list and call its @code{cdr}, e.g.:

@smalllisp
(define (match-word dbh strat key)
  (let ((sp (assoc (dico-strat-name strat) strategy-list)))
    (let ((res (cond
                (sp
                 ((cdr sp) dbh strat (dico-key->word key)))
@end smalllisp

  If the requested strategy is not in that list, the function will use
the selector function if it is available, and the default matching
function otherwise:

@smalllisp
                ((dico-strat-selector? strat)
                 (match-selector dbh strat key))
                (else
                 (match-default dbh strat (dico-key->word key))))))
@end smalllisp

Notice the use of @code{dico-key->word} function to extract the actual
lookup word from the key object.

  To summarize, the @samp{match-word} callback is:

@smalllisp  
(define (match-word dbh strat key)
  (let ((sp (assoc (dico-strat-name strat) strategy-list)))
    (let ((res (cond
                (sp
                 ((cdr sp) dbh strat (dico-key->word key)))
                ((dico-strat-selector? strat)
                 (match-selector dbh strat key))
                (else
                 (match-default dbh strat (dico-key->word key))))))
      (if res
          (cons #f res)
          #f))))
@end smalllisp

  Now, let's create the @samp{match-} functions it uses.  The
@samp{exact} strategy is easy to implement:

@smalllisp
(define (match-exact dbh strat word)
  (mapcan (lambda (elt)
            (and (string-ci=? word (car elt))
                 (car elt)))
          (db:get dbh corpus)))
@end smalllisp

  The @samp{prefix} and @samp{suffix} strategies are implemented using
SRFI-13 (@pxref{SRFI-13,,SRFI-13,guile,The Guile Reference Manual})
functions @code{string-prefix-ci?} and @code{string-suffix-ci?}, e.g.:

@smalllisp
(define (match-prefix dbh strat word)
  (mapcan (lambda (elt)
            (and (string-prefix-ci? word (car elt))
                 (car elt)))
          (db:get dbh corpus)))
@end smalllisp

  Notice that whereas the @samp{prefix} strategy is defined by the
server itself, the @samp{suffix} strategy is an extension, and should
therefore be registered:

@smalllisp
(dico-register-strat "suffix" "Match word suffixes")
@end smalllisp

  The @code{match-selector} function is pretty similar to its
siblings, except that it uses @code{dico-strat-select?}
(@pxref{Dico Scheme Primitives, dico-strat-select?}) to select the
matching elements.  This also leads to this function expecting
a @dfn{key} as its third argument, in contrast to the previous
matchers, which expect the actual lookup word there:

@smalllisp
(define (match-selector dbh strat key)
  (mapcan (lambda (elt)
            (and (dico-strat-select? strat (car elt) key)
                 (car elt)))
          (db:get dbh corpus)))
@end smalllisp
  
  Finally, the @code{match-default} is a variable that refers to
the default matching strategy for this module, e.g.:

@smalllisp
(define match-default match-prefix)
@end smalllisp

  The two callbacks left to define are @samp{result-count} and
@samp{output}.  The first of them simply returns the number of
elements in @code{cdr} of the result:

@smalllisp
(define (result-count rh)
  (length (cdr rh)))
@end smalllisp

  The behavior of @samp{output} depends on whether the result is
produced by @samp{define-word} or by @samp{match-word}.  

@smalllisp
(define (output rh n)
  (if (car rh)
      ;; @r{Result comes from DEFINE command.}
      (let ((res (list-ref (cdr rh) n)))
        (display (car res))
        (newline)
        (display (cdr res)))
      ;; @r{Result comes from MATCH command.}
      (display (list-ref (cdr rh) n))))
@end smalllisp

  Finally, at the end of the module the callbacks are made known to
@command{dicod} by the module initialization function:

@smalllisp
(define-public (example-init arg)
  (list (cons "open" open-module)
        (cons "descr" descr)
        (cons "info" info)
        (cons "define" define-word)
        (cons "match" match-word)
        (cons "output" output)
        (cons "result-count" result-count)))
@end smalllisp

  Notice, that in this implementation @samp{close-db} callback was not
needed. 

@node python
@section @command{Python}
@cindex Python
@cindex python module
  The @command{python} module provides an interface which allows
programmers to write loadable modules in Python.  The syntax for
loading the module is:

@example
load-module @var{name} @{
  command "python"
          " init-script=@var{name}"
          " load-path=@var{path}"
          " root-class=@var{name}";
@}
@end example

All parameters are optional:

@deffn {python module} load-path=@var{path}
Augments the default search path for Python modules.  The format of
@var{path} is the usual UNIX path specification: a colon-separated
list of directory names.
@end deffn

@deffn {python module} init-script=@var{name}
Specifies the name of the initial Python source file.  This file will
be loaded and interpreted immediately after loading the module.
@end deffn

@deffn {python module} root-class=@var{name}
Sets the name of the Python root class, which is responsible for the
dictionary operations.
@end deffn

A particular instance of the @command{python} module is loaded using
the @code{handler} statement within a @code{database} block.  This
statement takes the same parameters as described above, plus any
number of command line arguments, which will be passed to the root
class constructor.

@menu
* Dictionary Class::
* Dico Python Primitives::
* Python Example::    An Example of Python Module
@end menu

@node Dictionary Class
@subsection Python Dictionary Class

The dictionary class must define the following methods:

@defop Method DictionaryClass __init__ self *argv
Class constructor.  The @var{argv} array supplies positional arguments
from the @code{handler} statement in the configuration file.
@end defop

@defop Method DictionaryClass open self dbname
Opens the database named @var{dbname}.  Returns @samp{True} on success
and @samp{False} on failure.
@end defop

@defop Method DictionaryClass close self
Closes the database.
@end defop

@defop Method DictionaryClass descr self
Returns a short description of the database.
@end defop

@defop Method DictionaryClass info self
Returns a text describing the database.
@end defop

@defop Method DictionaryClass lang self
Optional.  Returns supported languages as @samp{(@var{src}, @var{dst})}.
@end defop

@defop Method DictionaryClass define_word self word
Defines @var{word}.  Returns a result (an opaque Python object) if the
definition was found or @samp{False} otherwise.
@end defop

@defop Method DictionaryClass match_word self strat word
Searches for @var{word} in the database using strategy @var{strat}.
Returns a result (an opaque Python object) if some matches were found
or @samp{False} otherwise.
@end defop

@defop Method DictionaryClass output self result n
Outputs @var{n}th result from the result set @var{result}.
@end defop

@defop Method DictionaryClass result_count self result
Returns number of elements in the result set.
@end defop

@defop Method DictionaryClass compare_count self result
Optional.  Returns the number of comparisons performed when
constructing the result set.
@end defop

@defop Method DictionaryClass result_headers self result hdr
Optional.  Returns a dictionary of MIME headers.
@end defop

@defop Method DictionaryClass free_result self result
Reclaims any resources used by the result set.
@end defop

@node Dico Python Primitives
@subsection Dico Python Primitives

@deffn {Python primitive} register_strat name descr [proc]
Registers new match strategy.  The arguments are:

@table @var
@item name
Strategy name for use in the @code{MATCH} command.

@item descr
The dscription, which will appear in the output of @code{SHOW STRAT}
command.

@item proc
Optional selector procedure.
@end table

@anchor{Python Selector}
If the @var{proc} argument is present, it must be the name of a Python
function declared as:

@example
def select(opcode key headword):
@end example

Its arguments are:

@table @var
@item opcode
Integer operation code.
@item key
An @code{DicoSelectionKey} object identifying the search term
(@pxref{DicoSelectionKey}).
@item headword
The headword being examined.
@end table

@kwindex DICO_SELECT_BEGIN, @r{Python}
At the beginning of the search, the function is called with the
@samp{DICO_SELECT_BEGIN} as its @var{opcode} argument.  It must
perform the necessary initialization and return.

@kwindex DICO_SELECT_END, @r{Python}
At the end of the search loop, the function is called with @var{opcode}
@samp{DICO_SELECT_END}.  It must perform the necessary
deinitialization procedures and exit.

In both cases, the @var{key} and @var{headword} arguments are not
defined.

@kwindex DICO_SELECT_RUN, @r{Python}
Within the search loop, the function will be called for each headword
from the database.  The @var{opcode} parameter will be
@samp{DICO_SELECT_RUN}.  In this case the function must return
@samp{True} if the @var{headword} matches the @var{key} and
@samp{False} otherwise.
@end deffn

@deffn {Python primitive} register_markup name
Registers a markup @var{name}.
@end deffn

@deffn {Python primitive} current_markup
Returns the name of the current markup.
@end deffn

@menu
* DicoSelectionKey::
* DicoStrategy::
@end menu

@node DicoSelectionKey
@subsubsection The @code{DicoSelectionKey} class

The @code{DicoSelectionKey} class represents a search key and is used
when looking for matches.  Calling @code{str} on the object of that
class returns the search term itself, as does the @code{word} method:

@defop {Method} DicoSelectionKey word
Returns the search term.  It is equivalent to the @code{__str__} attribute.
@end defop

@node DicoStrategy
@subsubsection The @code{DicoStrategy} class

A match strategy is represented by an object of the
@code{DicoStrategy} class.

@defcv {Variable} DicoStrategy name
The name of that strategy.
@end defcv

@defcv {Variable} DicoStrategy descr
Textual description of the strategy.
@end defcv

@defcv {Variable} DicoStrategy has_selector
@samp{True} if this strategy has a selector (@pxref{Python Selector}).
@end defcv

@defcv {Variable} DicoStrategy name is_default
@samp{True} if this is the default strategy.
@end defcv

@defop Method DicoStrategy select headword key
Returns @samp{True} if @var{key} matches @var{headword} as per
this strategy.
@end defop

@node Python Example
@subsection Python Example
  In this subsection we will show a simple database module written in
Python.  This module handles simple textual databases in the following
format:

@itemize @bullet
@item Empty lines and lines beginning with double dash are ignored.
@item A line beginning with @samp{descr:} introduces a short
dictionary description for @code{SHOW DB}.  The @samp{descr:} prefix
and the white space immediately following it are removed.  E.g.:

@example
descr: Short English-Norwegian numerals dictionary
@end example

@item Lines beginning with @samp{info:} provide a verbose description
of the database.  These lines are concatenated after removing the
@samp{info:} prefix and white space immediately following it.  E.g.:

@example
info: A short English-Norwegian (Bokm@ringaccent{a}l) dictionary
info: of numerals.
info: 
info: This dictionary is public domain.
@end example

@item A line beginning with @samp{lang:} defines source and
destination languages for this dictionary.  E.g.:

@example
lang: en : nb
@end example

@item Any line consisting of exactly two words defines a dictionary
entry.  E.g.:

@example
one     en
two     to
three   tre
four    fire
@end example
@end itemize

Now, let's create a module for handling this format.  First, we need
to import Dico primitives (@pxref{Dico Python Primitives}) and the
@samp{sys} module.  The latter is needed for output functions:

@example
import dico
import sys
@end example

@noindent
Then, a result class will be needed for @code{match_word} and
@code{define_word} methods.  It will contain the actual data in
the variable @samp{result}:

@example
class DicoResult:
    # @r{actual data.}
    result = @{@}
    # @r{number of comparisons.}
    compcount = 0
    
    def __init__ (self, *argv):
        self.result = argv[0]
        if len (argv) == 2:
             self.compcount = argv[1]

    def count (self):
        return len (self.result)

    def output (self, n):
        pass

    def append (self, elt):
        self.result.append (elt)
@end example

@noindent
The following two classes extend @samp{DicoResult} for use with
@samp{DEFINE} and @samp{MATCH} operations.  The @code{define_word}
method will return an instance of the @samp{DicoDefineResult} class:

@example        
class DicoDefineResult (DicoResult):
    def output (self, n):
        print "%d. %s" % (n + 1, self.result[n])
        print "---------",
@end example

@noindent
The @code{match_word} method will return an instance of the
@samp{MatchResult} class:

@example
class DicoMatchResult (DicoResult):
    def output (self, n):
        sys.stdout.softspace = 0
        print self.result[n],
@end example

@noindent
Now, let's define the dictionary class:

@example
class DicoModule:
    # @r{The dictionary converted to associative array.}
    adict =  @{@}
    # @r{The database name.}
    dbname = ''
    # @r{The name of the corresponding disk file.}
    filename = ''
    # @r{A sort information about the database.}
    mod_descr = ''
    # @r{A verbose description of the database is kept.}
    # @r{as an array of strings.}
    mod_info = []
    # @r{A list of source and destination languages:}
    langlist = ()
@end example

@noindent
The class constructor takes a single argument, defining the name
of the database file:

@example
    def __init__ (self, *argv):
        self.filename = argv[0]
        pass
@end example

@noindent
The @samp{open} method opens the database and reads its data:

@example
    def open (self, dbname):
        self.dbname = dbname
        file = open (self.filename, "r")
        for line in file:
            if line.startswith ('--'):
                continue
            if line.startswith ('descr: '):
                self.mod_descr = line[7:].strip (' \n')
                continue
            if line.startswith ('info: '):
                self.mod_info.append (line[6:].strip (' \n'))
                continue
            if line.startswith ('lang: '):
                s = line[6:].strip (' \n').split(':', 2)
                if (len(s) == 1):
                    self.langlist = (s[0].split (), \
                                     s[0].split ())
                else:
                    self.langlist = (s[0].split (), \
                                     s[1].split ())
                continue
            f = line.strip (' \n').split (' ', 1)
            if len (f) == 2:
                self.adict[f[0].lower()] = f[1].strip (' ')
        file.close()
        return True
@end example

@noindent
The database is kept entirely in memory, so there is no need for
@samp{close} method.  However, it must be declared anyway:

@example
    def close (self):
        return True
@end example

@noindent
The methods returning database information are trivial:

@example
    def descr (self):
        return self.mod_descr

    def info (self):
        return '\n'.join (self.mod_info)
    
    def lang (self):
        return self.langlist
@end example

@noindent
The @samp{define_word} method checks if the search term is present in
the dictionary, and, if so, converts it to the @code{DicoDefineResult}:

@example
    def define_word (self, word):
        if self.adict.has_key (word):
            return DicoDefineResult ([self.adict[word]])
        return False
@end example

The @samp{match_word} method supports the @samp{exact} strategy
natively via the @code{has_key} attribute of @code{adict}:

@example
    def match_word (self, strat, key):
        if strat.name == "exact":
            if self.adict.has_key (key.word.lower ()):
                return DicoMatchResult \
                        ([self.adict[key.word.lower()]])
@end example

@noindent
Other strategies are supported as long as they have selectors:

@example
        elif strat.has_selector:
            res = DicoMatchResult ([], len (self.adict))
            for k in self.adict:
                if strat.select (k, key):
                    res.append (k)
            if res.count > 0:
                return res
        return False
@end example

@noindent
The rest of methods rely on the result object to do the right thing:

@example
    def output (self, rh, n):
        rh.output (n)
        return True

    def result_count (self, rh):
        return rh.count ()

    def compare_count (self, rh):
        return rh.compcount
@end example


@node stratall
@section @command{Stratall}
@cindex stratall module
  The @command{stratall} module provides a new strategy, called @samp{all}.
This strategy always returns a full list of headwords from the
database, no matter what the actual search word is.
 
  To load this strategy, use the following configuration statement:

@example
load-module stratall;
@end example

  Using this strategy on a full set of databases (@samp{MATCH * all
""}) produces enormous amount of output, which may induce a
considerable strain on the server, therefore it is advised to block
such usage as suggested in @ref{Strategies and Default Searches}:

@example
strategy all @{
        deny-all yes;
@}
@end example

@node substr
@section @command{Substr}
@cindex substr module
  The @command{substr} module provides a @samp{substr} search
strategy.  This strategy matches a substring anywhere in the
keyword.  For example:

@example
C: MATCH eng-deu substr orma
S: 152 207 matches found: list follows
S: eng-deu "abnormal"
S: eng-deu "conformable"
S: eng-deu "doorman"
S: eng-deu "format"
@dots{}
@end example

  The loading procedure expects no arguments:

@example
load-module substr;
@end example

@node word
@section @command{Word}
@cindex word module
  The @command{word} module provides the following strategies:

@table @asis  
@item word
Match separate words within headwords.
@item first
Match the first word within headwords.
@item last
Match the last word within headwords.
@end table

The initialization procedure loads all three if given no arguments, as in

@example
load-module word;
@end example  

If arguments are given, the initialization procedure loads only those
strategies that are listed in its command line.  For example, the
statement below loads only @samp{first} and @samp{last} strategies:

@example
load-module word @{
   command "word first last";
@}   
@end example

The following is an example of using one of those strategies in a dico
session:

@example
C: MATCH devdict word government
S: 152 1 matches found: list follows
S: devdict "MONARCHICAL GOVERNMENT"
S: .
S: 250 Command complete
@end example

@node nprefix
@section @command{Nprefix}
@cindex nprefix module
The @command{nprefix} module provides a strategy similar to
@samp{prefix}, but which returns the specified range of bytes.  For
example, the statement

@example
MATCH @var{dict} nprefix @var{skip}#@var{count}#@var{string}
@end example

@noindent
where @var{skip} and @var{count} are positive integer numbers, returns
at most @var{count} headwords whose prefix matches @var{string},
omitting first @var{skip} unique matches.

The entire @samp{@var{skip}#@var{count}#} construct is optional.  If
not supplied, the @samp{nprefix} strategy behaves exactly as
@samp{prefix}.

The module is loaded using this simple statement:

@example
load-module nprefix;
@end example

@node metaphone2
@section @command{metaphone2}
@cindex metaphone2
@cindex Double Metaphone
@cindex Lawrence Philips
The @command{metaphone2} module provides a strategy based on
@dfn{Double Metaphone} phonetic encoding algorithm, published by
Lawrence Philips.

The module is normally loaded as follows:

@example
load-module metaphone2;
@end example

The only available initialization parameter is

@deffn {metaphone2 parameter} size @var{number}
Defines the size of computed Double Metaphone codes, in characters.
The default is 4.

@example
load-module metaphone2 @{
   command "metaphone2 size=16";
@}
@end example
@end deffn

@node pcre
@section @command{Pcre}
@cindex pcre module
@cindex regexp, Perl-compatible
@cindex Perl-compatible regular expressions
The @command{pcre} module provides a matching strategy using
Perl-compatible regular expressions.  The module is loaded
using a simple statement:

@example
load-module pcre;
@end example

The strategy has the same name as the module and is reflected in the
server's HELP output as shown below:

@example
pcre  "Match using Perl-compatible regular expressions"
@end example

The headword argument to the @code{pcre} MATCH statement should be
a valid Perl regular expression.  It can optionally be enclosed in
a pair of slashes, in which case one or more of the following flags
can appear after the closing slash:

@table @code
@item a
The regexp is @dfn{anchored}, that is, it is constrained to match only
at the first matching point in the string that is being searched.

@item e
Ignore whitespace and @samp{#} comments in the expression.

@item i
Ignore case when matching.

@item G
Inverts the @dfn{greediness} of the quantifiers so that they are not
greedy by default, but become greedy if followed by @samp{?}.  The
same can also be achieved by setting the @samp{(?U)} option within the
pattern.
@end table

Any of these flags can also be used in reverted case, which also
reverts its meaning.  For example, @samp{I} means case-sensitive matching.

Here is an example of using this strategy in a dico session:

@example
MATCH ! pcre "/\\stext/i"
@end example

@node ldap
@section @command{Ldap}
@cindex ldap module
The @command{ldap} module loads the support for @acronym{LDAP} user
databases.  It is available if Dico has been configured with
@acronym{LDAP}.

The module needs no additional configuration parameters:

@example
load-module ldap;
@end example

@xref{ldap userdb}, for a description of its use.

@node pam
@section @command{pam}
@cindex PAM
@cindex pam module
The @command{pam} module implements user authentication via PAM.
It can be used only with @samp{LOGIN} and @samp{PLAIN} GSASL
authentication methods.

The module is loaded as follows:

@example
@group
load-module pam @{
    command "pam [service=@var{sname}]";
@}
@end group
@end example

@noindent
where @var{sname} is the name of PAM service to use.  If not supplied,
@samp{dicod} service will be used.

The user database is normally initialized as:

@example
user-db "pam://localhost";
@end example

If @code{password-resource} statement is given, its value will be used
as service name, instead of the one specified in the
@code{load-module} statement, e.g.:

@example
@group
user-db "pam://localhost" @{
    password-resource "local";
@}    
@end group
@end example

The @code{group-resource} statement is not used, because there is no
mechanism to return textual data from PAM.

@node greek_kbd
@section @command{greek_kbd}

The @command{greek_kbd} module provides an input converter
(@pxref{Input Conversions}) for translating greek words from Latin
@dfn{keyboard transliteration} into Greek script.  A keyboard
transliteration associates a Greek letter with a corresponding Latin
one using the standard Greek keyboard layout.  Thus, @samp{a}
transliterates to @samp{Alpha}, @samp{y} to @samp{Ypsilon}, and
@samp{u} to @samp{Thita}.  Diacritics are introduced by @samp{:} (for
diaeresis), and @samp{'} (for acute accent) after the letter they
apply to.  If a letter has both diaeresis and accent, the marks should
appear in this order, e.g. @samp{y:'}.

This conversion is applied only if the search term begins with a Latin
letter.

To load the module, use the following statement:

@example
load-module greek_kbd;
@end example

The module takes one parameter:

@table @option
@item casemap=@var{value}
Translate letter case on output.  If @var{value} is @samp{keep}, the
case remains unchanged (this is the default).  If it is @samp{upper},
letters are converted to upper case, and if it is @samp{lower} they
are converted to lowercase.
@end table

For example:

@example
@group
load-module greek_kbd @{
    command "greek_kbd casemap=lower";
@}
@end group
@end example

You can define several converters in one command line, like this:

@example
@group
load-module greek_kbd @{
    command "greek_kbd greek_kbd_lo casemap=lower";
@}
@end group
@end example

In this case, the converter @command{greek_kbd} will use the default
behavior (keep letter case unchanged) and converter
@command{greek_kbd_lo} will produce lower-cased output.

The following example illustrates the use of this module with the
@samp{ell-eng} dictionary from Freedict:

@example
load-module dictorg @{
    command "dictorg trim-ws dbdir=/var/db sort";
@}
load-module greek_kbd;
database @{
    name "ell-eng";
    handler "dictorg database=ell-eng";
    conv "greek_kbd";
@}
@end example

@node Interface
@chapter Dico Module Interface
This chapter describes the API for Dico loadable modules.

@menu
* dico_database_module::
* Strategies::
* Output::
* Unit Testing::
@end menu

@node dico_database_module
@section dico_database_module
@cindex dico_database_module, a structure
@kwindex DICO_EXPORT
Each module must export exactly one symbol of type @code{struct
dico_database_module}.  This symbol must be declared as

@example
DICO_EXPORT(@var{name}, module)
@end example

@noindent
where @var{name} is the name of the module file (without suffix).
For example, a module @file{word.so} would have in its sourse the
following declaration:

@example
struct dico_database_module DICO_EXPORT(word, module) = @{
@dots{}
@};
@end example

The @code{dico_database_module} has the following members:

@deftypevr {dico_database_module} unsigned dico_version
@vrindex DICO_MODULE_VERSION
Interface version being used.  It is recommended to use the macro
@code{DICO_MODULE_VERSION}, which keeps the version number of the
current interface.
@end deftypevr

@deftypevr {dico_database_module} unsigned dico_capabilities
@vrindex DICO_CAPA_DEFAULT
Module capabilities.  As of version @value{VERSION}, this member can
be one of the following:

@table @code
@item DICO_CAPA_DEFAULT
This module defines a handler for a specific database format.

@item DICO_CAPA_NODB
This module does not handle any databases.  When this capability is
specified, @command{dicod} will call only the @command{dico_init}
member of the structure.

This capability is used by modules defining new matching strategies or
authentication methods.
@end table
@end deftypevr

@anchor{dico_init}
@deftypefn {Dico Callback} int dico_init (int @var{argc}, char **@var{argv})
This callback is called right after loading the module.  It is
responsible for module initialization.  The arguments are:

@table @var
@item argc
Number of elements in @var{argv}.

@item argv
The command line given by @code{command} configuration statement
(@pxref{Handlers, command}), split into words.  The element
@code{@var{argv}[0]} is the name of the module.  The element
@code{@var{argv}[@var{argc}]} is @samp{NULL}.  Word splitting
follows the rules similar to those used in shell.  In particular,
a quoted string (using both single and double quotes) is handled
as a single word.
@end table

If @code{dico_capabilities} is @code{DICO_CAPA_DEFAULT}, this
method is optional.  If @code{dico_capabilities} is set to
@code{DICO_CAPA_NODB}, @code{dico_init} is mandatory and must be
the only method defined.
@end deftypefn

@deftypefn {Dico Callback} dico_handle_t dico_init_db (const char *@var{db}, @
 int @var{argc}, char **@var{argv})
Initialize the database.  This method is called as a part of database
initialization routine at startup of @command{dicod}, after processing
@code{dictionary} configuration statement (@pxref{Databases}).  Its
arguments are:

@table @var
@item db
The name of the database, as given by the @code{name} statement.

@item argc
Number of elements in @var{argv}.

@item argv
The command line given by @code{handler} configuration statement
(@pxref{Databases, handler}).  The array is @samp{NULL}-terminated.
@end table

This method returns a @dfn{database handle}, an opaque structure
identifying the database.  This handle will be passed as the first
argument to other methods.  On error, @code{dico_init_db} shall return
@code{NULL}.

Notice, that this function is not required to actually open the
database, if the @samp{open} notion is supported by the underlying
mechanism.  Another method, @code{dico_open} is responsible for that.
@end deftypefn

@deftypefn {Dico Callback} int dico_free_db (dico_handle_t @var{dh})
Reclaim any resources associated with database handle @var{dh}.  This
method is called as part of exit cleanup routine, before the main
@command{dicod} process terminates.

It shall return @samp{0} on success, or any non-@samp{0} value on failure.
@end deftypefn

@deftypefn {Dico Callback} int dico_open (dico_handle_t @var{dh})
Open the database identified by the handle @var{dh}.  This method is
called as part of child process initialization routine.

It shall return @samp{0} on success, or any non-@samp{0} value on failure.

The @code{dico_open} method is optional.
@end deftypefn

@deftypefn {Dico Callback} int dico_close (dico_handle_t @var{dh})
Close the database identified by the handle @var{dh}.  This method is
called as part of child process termination routine.

It shall return @samp{0} on success, or any non-@samp{0} value on failure.

The @code{dico_close} method is optional, but if @code{dico_open} is
defined, @code{dico_close} must be defined as well.
@end deftypefn

@anchor{dico_db_info}
@deftypefn {Dico Callback} {char *} dico_db_info (dico_handle_t @var{dh})
Return a database information string for the database identified by
@var{dh}.  This function is called on each @code{SHOW INFO} command,
unless an informational text for this database is supplied in the
configuration file (@pxref{Databases, info}).  This value must be
allocated using malloc(3).  The caller is responsible for freeing it
when no longer needed. 

This method is optional.
@end deftypefn

@deftypefn {Dico Callback} {char *} dico_db_descr (dico_handle_t @var{dh})
Return a short database description string for the database identified
by @var{dh}.  This function is called on each @code{SHOW DB} command,
unless a description for this database is supplied in the
configuration file (@pxref{Databases, descr}).  This value must be
allocated using malloc(3).  The caller is responsible for freeing it
when no longer needed.

This method is optional.
@end deftypefn

@deftypefn {Dico Callback} dico_result_t dico_match (dico_handle_t @var{dh}, @
  const dico_strategy_t @var{strat}, const char *@var{word})
Use the strategy @var{strat} to search in the database @var{dh}, and
return all headwords matching @var{word}.

This method returns a @dfn{result handle}, an opaque pointer that can
then be used to display the obtained results.  It returns @code{NULL}
if no matches were found.
@end deftypefn

@deftypefn {Dico Callback} dico_result_t dico_define (dico_handle_t @var{dh}, @
  const char *@var{word})
Find definitions of headword @var{word} in the database identified by
@var{dh}.

This method returns a @dfn{result handle}, an opaque pointer that can
then be used to display the obtained results.  It returns @code{NULL}
if no matches were found.
@end deftypefn

@deftypefn {Dico Callback} int dico_output_result (dico_result_t @var{rp}, @
  size_t @var{n}, dico_stream_t @var{str})
The @code{dico_output_result} method outputs to stream @var{str} the
@var{n}th result from result set @var{rp}.  The latter is a result
handle, obtained from a previous call to @code{dico_match} or
@code{dico_define}.

Returns @samp{0} on success, or any non-@samp{0} value on failure.

It is guaranteed that the @code{dico_output_result} callback is
called as many times as there are elements in @var{rp} (as determined by the
@code{dico_result_count} callback, described below) and that for each
subsequent call the value of @var{n} equals its value from the
previous call incremented by one.

At the first call @var{n} equals 0.
@end deftypefn

@anchor{dico_result_count}
@deftypefn {Dico Callback} size_t dico_result_count (dico_result_t @var{rp})
Return the number of distinct elements in the result set identified by
@var{rp}.  The latter is a result handle, obtained from a previous
call to @code{dico_match} or @code{dico_define}.
@end deftypefn

@deftypefn {Dico Callback} size_t dico_compare_count (dico_result_t @var{rp})
Return the number of comparisons performed when constructing the result
set identified by @var{rp}.

This method is optional.
@end deftypefn

@deftypefn {Dico Callback} void dico_free_result (dico_result_t @var{rp})
Free any resources used by the result set @var{rp}, which is a result
handle, obtained from a previous call to @code{dico_match} or
@code{dico_define}. 
@end deftypefn

@deftypefn {Dico Callback} int dico_result_headers (dico_result_t @var{rp}, @
         dico_assoc_list_t @var{hdr})
Populate associative list @var{hdr} with the headers describing result
set @var{rp}.  This callback is optional.  If defined, it will be
called before outputting the result set @var{rp} if @code{OPTION MIME}
is in effect (@pxref{OPTION, OPTION MIME}).
@end deftypefn

@deftypefn {Dico Callback} int dico_run_test (int @var{argc}, char **@var{argv})
Runs unit tests for the module.  Argument vector contains all command
line arguments that follow the @option{--runtest} option, up to the
@samp{--} marker or end of line, whichever is encountered first.
@end deftypefn

@node Strategies
@section Strategies

A search strategy is described by the following structure:

@example
struct dico_strategy @{
    char *name;          /* @r{Strategy name} */
    char *descr;         /* @r{Strategy description} */
    dico_select_t sel;   /* @r{Selector function} */
    void *closure;       /* @r{Additional data for SEL} */ 
    int is_default;      /* @r{True, if this is a default strategy} */
    dico_list_t stratcl; /* @r{Strategy access control list} */  
@};
@end example

The first two members are mandatory and must be defined for each strategy:

@deftypecv {member} {struct dico_strategy} @code{char *} name
Short name of the strategy.  It is used as second argument to the
@command{MATCH} command (@pxref{MATCH}) and is displayed in the first
column of output by the @command{SHOW STRAT} command (@pxref{SHOW,SHOW STRAT}).
@end deftypecv

@deftypecv {member} {struct dico_strategy} @code{char *} descr
Strategy description.  It is the string shown in the second column of
@command{SHOW STRAT} output (@pxref{SHOW,SHOW STRAT}).
@end deftypecv

@anchor{selector}
@deftypecv {member} {struct dico_strategy} dico_select_t sel
@kwindex dico_select_t
A @dfn{selector function}, which is used in iterative matches to
select matching headwords.  The @code{sel} function is called for each
headword in the database with the headword and search key as its
arguments and returns 1 if the headword matches the key and 0
otherwise.  The @code{dico_select_t} type is defined as:

@example
typedef int (*dico_select_t) (int, dico_key_t,
                              const char *);
@end example

@xref{Selector}, for a detailed description.
@end deftypecv

@deftypecv {member} {struct dico_strategy} @code{void *} closure
An opaque data pointer intended for use by the selector function.
@end deftypecv

@deftypecv {member} {struct dico_strategy} int is_default
This member is set to 1 by the server if this strategy is selected as
the default one (@pxref{default strategy}).
@end deftypecv

@deftypecv {member} {struct dico_strategy} dico_list_t stratcl
A control list associated with this strategy.  @xref{Strategies and
Default Searches}.
@end deftypecv

@menu
* Key::
* Selector::
@end menu

@node Key
@subsection Search Key Structure
@anchor{dico_key}
@kwindex dico_key_t
@kwindex dico_key
The @code{dico_key_t} is defined as a pointer to the structure
@code{dico_key}:

@example
@group
struct dico_key @{
    char *word;
    void *call_data;
    dico_strategy_t strat;
    int flags;
@};
@end group
@end example

The structure represents a search key for matching algorithms.  Its
members are:

@deftypecv {member} {struct dico_key} @code{char *} word
The search word or expression.
@end deftypecv

@deftypecv {member} {struct dico_key} @code{void *} call_data
@kwindex DICO_SELECT_BEGIN
@kwindex DICO_SELECT_END
A pointer to selector-specific data.  If necessary, it can be
initialized by the selector when called with the
@samp{DICO_SELECT_BEGIN} opcode and deallocated when called with the
@samp{DICO_SELECT_END} opcode.
@end deftypecv

@deftypecv {member} {struct dico_key} dico_strategy_t strat
A pointer to the strategy structure.
@end deftypecv

@deftypecv {member} {struct dico_key} int flags
Key-specific flags.  These are used by the server.
@end deftypecv

@noindent
The following functions are defined to operate on search keys:

@deftypefn {function} int dico_key_init (struct dico_key *@var{key}, @
                              dico_strategy_t @var{strat}, @
                              const char *@var{word})
@kwindex DICO_SELECT_BEGIN
Initialize the key structure @var{key} with the given strategy
@var{strat} and search word @var{word}.  If @var{strat} has a selector
function, it will be called with the @samp{DICO_SELECT_BEGIN} opcode
(@pxref{Selector, DICO_SELECT_BEGIN}) to carry out the necessary
initializations.

The @var{key} itself may point to any kind of memory storage.
@end deftypefn
                              
@deftypefn {function} void dico_key_deinit (struct dico_key *@var{key})
@kwindex DICO_SELECT_END
Deinitialize the @code{dico_key} structure initialized by a prior call
to @code{dico_key_init}.  If the key strategy has a selector, it will
be called with the @samp{DICO_SELECT_END} opcode.

Note that this function makes no assumptions about the storage type of
@var{key}.  If it points to a dynamically allocated memory, it is the
caller responsibility to free it.
@end deftypefn

@deftypefn {function} int dico_key_match (struct dico_key *@var{key}, @
                               const char *@var{word})
@kwindex DICO_SELECT_RUN                               
Match headword and key.  Return 1 if they match, 0 if they don't match
and -1 in case of error.  This function calls the strategy selector with the
@samp{DICO_SELECT_RUN} opcode (@pxref{Selector, DICO_SELECT_RUN}).  It
is an error if the strategy selector is not defined.
@end deftypefn
                               
@node Selector
@subsection Strategy Selectors
Wherever possible, modules should implement strategies using effective
look up algorithms.  For example, @samp{exact} and @samp{prefix}
strategies must normally be implemented using binary search in the
database index.  The @samp{suffix} strategy can also be implemented
using binary search if a special @dfn{reverse index} is built for the
database (this is the approach taken by @command{outline} and
@command{dictorg} modules).

However, some strategies can only be implemented using a relatively
expensive iteration over all keys in the database index.  For example,
@samp{soundex} and @samp{levenshtein} strategies cannot be implemented
otherwise.

A strategy that can be used in iterative look ups must define a
@dfn{selector}.  Strategy selector is a function which is called for
each database headword to determine whether it matches the search key.

It is defined as follows:

@deftypefn {selector} int select (int @var{opcode}, dico_key_t @var{key}, @
                                  const char *@var{headword})
A strategy selector.  Its arguments are:

@table @var
@item opcode
The operation code.  Its possible values are @samp{DICO_SELECT_BEGIN},
@samp{DICO_SELECT_RUN} and @samp{DICO_SELECT_END}, as described below.

@item key
The search key.

@item headword
The database headword.
@end table
@end deftypefn

@kwindex DICO_SELECT_BEGIN
The selector function is called before entering the iteration loop
with @samp{DICO_SELECT_BEGIN} as its argument.  If necessary, it can
perform any additional initialization of the strategy, such as
allocation of auxiliary data structures, etc.  The @code{call_data}
member of @code{dico_key_t} structure (@pxref{dico_key,call_data})
should be used to keep the pointer to the auxiliary data.  The
function should return 0 if it successfully finished its
initialization and non-zero otherwise.

@kwindex DICO_SELECT_END
Once the iteration loop is finished, the selector will be called with
@samp{DICO_SELECT_END} as its first argument.  This invocation is
intended to deallocate any auxiliary memory and release any additional
resources allocated at the initialization state.

In these two additional invocations, the @var{headword} parameter will
be @samp{NULL}.

@kwindex DICO_SELECT_RUN
Once the iteration loop is entered, the selector function will be
called for each headword.  Its @var{opcode} parameter will be
@samp{DICO_SELECT_RUN} and the @var{headword} parameter will point to
the headword.  The function should return 1 if the headword matches
the key, 0 if it does not and a negative value in case of failure.

To illustrate the concept of strategy selector, let's consider the
implementation of the @samp{soundex} strategy in @command{dicod}.
This strategy computes a four-character soundex code for both search
key and the headword and returns 1 (match) if both codes coincide.  To
speed up the process, the code for the search key is computed only
once, at the initialization stage, and stored in a temporary memory
assigned to the @code{key->call_data}.  This memory is reclaimed at
the terminating call:

@example
int
soundex_sel(int cmd, dico_key_t key, const char *dict_word)
@{
    char dcode[DICO_SOUNDEX_SIZE];

    switch (cmd) @{
    case DICO_SELECT_BEGIN:
        key->call_data = malloc(DICO_SOUNDEX_SIZE);
        if (!key->call_data)
            return 1;
        dico_soundex(key->word, key->call_data);
        break;

    case DICO_SELECT_RUN:
        dico_soundex(dict_word, dcode);
        return strcmp(dcode, key->call_data) == 0;

    case DICO_SELECT_END:
        free(key->call_data);
        break;
    @}
    return 0;
@}
@end example

@node Output
@section Output
@cindex output
@kwindex dico_output_result
The @code{dico_output_result} method is called when the server needs
to output the result of a @samp{define} or @samp{match} command.  It
must be defined as follows:

@example
int output_result (dico_result_t @var{rp}, size_t @var{n},
                   dico_stream_t @var{str});
@end example

The @var{rp} argument points to the result in question.  From the server's
point of view it is an opaque pointer.  The application shall define
its own result structure, so normally the first operation the
@code{dico_output_result} method does is typecasting @var{rp} to
a pointer to that structure in order to be able to access its
members.

A result can conceptually contain several @dfn{parts}.  For example,
the result of a @samp{DEFINE} command can contain several definitions
of the term.  Similarly, the result of @samp{MATCH} contains one or
more matches.  The server obtains the exact number of parts in a
result by calling the @code{dico_result_count} method
(@pxref{dico_result_count}).

When outputting a result, the server calls the @code{dico_output_result}
in a loop, once for each result part.  It passes the ordinal
(zero-based) number of the part that needs to be output in the @var{n}
parameter.  It is guaranteed that @var{n} increases by one for each
subsequent call of @code{dico_output_result} with the same @var{rp}
parameter.

The @var{str} parameter identifies the @dfn{output stream}.  The
@code{dico_output_result} function must format the requested part from
the result and output it to that stream.  To do so it should use one
of the following functions:

@deftypefn Function int dico_stream_write (dico_stream_t @var{str}, @
              const void *@var{buf}, size_t @var{count})
Writes @var{count} bytes from the buffer pointed to by @var{buf} to the
output stream @var{str}.  Returns 0 on success, and non-zero on error.
@end deftypefn
              
@deftypefn Function int dico_stream_writeln (dico_stream_t @var{str}, @
              const char *@var{buf}, size_t @var{size})
Same as @code{dico_stream_write}, but ends the output with a
@kbd{newline} character (ASCII 10).              
@end deftypefn

@node Unit Testing
@section Module Unit Testing
@cindex testing, modules
@cindex unit testing
The @code{dico_run_test} member of @code{struct dico_database_module}
(@pxref{dico_database_module, dico_run_test}) points to the function
that serves as entry point for unit tests of that module.  If it is
NULL, the module does not support unit testing.  Otherwise, unit tests
can be run using the following command line syntax:

@example
$ dicod --runtest @var{module} [@var{test_args}] [-- @var{init_args}]
@end example

As usual, square brackets denote optional parts.  The @var{module}
argument specifies the name of the module to test.  The arguments that
follow the @option{--runtest} (@option{-r}) option are collected into
two arrays: arguments up to the @samp{--} marker form the vector that
is passed to the module's @code{dico_run_test} function.  The 
@samp{--} marker is optional.  If present, arguments that follow it
are collected into a separate argument vector starting from slot 1,
the slot 0 is set to point to the module name and the resulting vector
is passed to the @code{dico_init} method of the module.

When running unit tests, configuration file is ignored.  The diagnostic
messages are printed to the standard error output.

@kwindex --load-dir
@kwindex -L
Use the @option{--load-dir} (@option{-L}) command line option, if the
module being tested cannot be found in the default load path
(@pxref{load path}), e.g.:

@example
$ dicod -L ../lib --runtest metaphone2 build A B C
@end example

@node dico client
@chapter Dico --- a client program.
@cindex dico, a program
  The @command{dico} program is a console-based utility for querying
dictionary servers.  It has two operation modes.  In @dfn{single query
mode}, the utility performs a query, displays its result and exits
immediately.  This mode is entered if a word or a @acronym{URL} was
given in the command line.  In @dfn{interactive mode}, the utility
enters a read-and-eval loop, in which it reads requests from the
keyboard, performs the necessary searches, and displays obtained
results on the screen.

@menu
* Single Query Mode::
* Interactive Mode::
* Initialization File::
* Autologin::
* Dico invocation::
@end menu

@node Single Query Mode
@section Single Query Mode
@cindex single query mode

  The simplest way to use @command{dico} utility is to invoke it with
a word as an argument, e.g.:

@example
$ dico entdeckung
@end example

  In the example above, the utility will search definitions of the
word @samp{entdeckung} using its default server name and database.  The
default server name is read from the initialization file
(@pxref{Initialization File}).  If it is not present, a predefined
value specified at configuration time (@pxref{Default Server}) is
used.  The default database is @samp{!}, which means ``search in all
available databases until a match is found, and then display all
matches in that database''. 

  There are two ways to change these defaults.  First, you can use
command line options.  Secondly, you can use a @acronym{DICT URL}.
Which method to use depends on your preferences.  Both methods provide
the same functionality for querying word definitions.  However,
command line options allow the user to query additional data from the server,
which is impossible using @acronym{URL}s.   

@menu
* dico options::
* urls::
@end menu

@node dico options
@subsection Dico Command Line Options

To connect to a particular dictionary server,
use the @option{--host} option, for example:

@example
$ dico --host dico.org entdeckung
@end example

  To search in a particular database, use the @option{--database}
(@option{-d}) option.  For example, to display definitions from
all databases:

@example
$ dico --database '*' entdeckung
@end example

@noindent
Note single quotes around the asterisk.

  To get a list of databases offered by the server, use the @option{--dbs}
(@option{-D}) option.  In this case you may not give any non-option
arguments.   For example:

@example
$ dico --dbs
@end example

  If you wish to get a list of matches, instead of definitions, use
the @option{--match} (@option{-m}) option.  For example, the following
invocation will display all matches from all the databases:

@example
$ dico --database '*' --match entdeckung
@end example

  The match mode uses @samp{.} strategy by default (@pxref{MATCH,
strategy}), which means a server-dependent default strategy, which
suits best for interactive spell checking.  To select another
strategy, use the @option{--strategy} (@option{-s}) option.

  If the remote server supports @samp{xlev} experimental capability
(@pxref{Extended Commands, XLEV}, you may use the @option{--levdist}
(@option{--levenshtein-distance}) option to set maximum Levenshtein
distance, for example:

@example
$ dico --levdist 2 --match entdeckung
@end example

  Note that setting the distance too high is impractical and may imply
unnecessary strain on the server. 

  To get a list of available matching strategies, with
descriptions, use the @option{--strategies} (@option{-S}) option.

@node urls
@subsection DICT URL
@cindex URL, using to query DICT server
  Another way to specify data for a query is by using @acronym{URL},
instead of a word to search, as in the example below:

@example
$ dico dict://gnu.org.ua/d:entdeckung
@end example

A @acronym{DICT} @acronym{URL} consists of the following parts:

@example
dict://@var{user};@var{pass}@@@var{host}:@var{port}/d:@var{word}:@var{database}:@var{n}
dict://@var{user};@var{pass}@@@var{host}:@var{port}/m:@var{word}:@var{database}:@var{strat}:@var{n}
@end example

The @samp{/d} syntax requests the definition of @var{word}, whereas
the @samp{/m} syntax queries for matches, and is similar to the
@option{--match} option.  Some or all of
@samp{@var{user};@var{pass}@@}, @samp{:@var{port}}, @var{database},
@var{strat}, and and @var{n} may be omitted.   The meaning of all
@acronym{URL} parts and their default values (if appropriate) are
explained in the table below: 

@table @var
@item user
The user name to use in authentication.  Similar to the @option{--user}
option.  If @var{user} is omitted and cannot be retrieved by other
means, no authentication is attempted.  @xref{Autologin}, for a
detailed description of authentication procedure and sources which
are used to obtain authentication credentials.

@item pass
A shared key (password) for that user.  This part is similar to the
@option{--key} command line option.

For compatibility with other @acronym{URL}s, @command{dico} tolerates
a colon (instead of semicolon) as a delimiter between @var{user} and
@var{pass}.

If @var{user} is given, but @var{pass} is not, @command{dico} will ask
you to supply a password interactively (@pxref{Autologin}).

@item host
Host name, @acronym{IPv4} address, or @acronym{IPv6} address (in
square brackets) of the server to query.  Same as the
@option{--host} command line option.

@item port
Port number or service name (from @file{/etc/services}).  If it is not
present, the default of 2628 is used.

Same as the @option{--port} command line option.

@item word
The word to look for.

@item database
The database to search in.  If not given, @samp{!} is assumed.

Same as the @option{--database} command line option.

@item strat
The matching strategy to use.  If omitted, @samp{.} is assumed.

Same as the @option{--strategy} command line option.

@item n
Extract and display the @var{n}th definition of the word.  If omitted,
all definitions are displayed.

There is no command line option equivalent for this parameter, because
it is used rarely.
@end table

Trailing colons may be omitted.  For example, the following @acronym{URL}s
might specify definitions or matches:

@example
dict://dict.org/d:shortcake:
dict://dict.org/d:shortcake:*
dict://dict.org/d:shortcake:wordnet:
dict://dict.org/d:shortcake:wordnet:1
dict://dict.org/d:abcdefgh
dict://dict.org/d:sun
dict://dict.org/d:sun::1
dict://dict.org/m:sun
dict://dict.org/m:sun::soundex
dict://dict.org/m:sun:wordnet::1
dict://dict.org/m:sun::soundex:1
dict://dict.org/m:sun:::
@end example

@node Interactive Mode
@section Interactive Mode
  If neither word nor @acronym{URL} nor any operation mode option were
given on the command line, @command{dico} enters interactive mode.  In
this mode it reads commands from the standard input, executes them and
displays results on the standard output.  If the standard input is
connected to a terminal, the readline and history facilities are
enabled (@pxref{Command Line Editing, , Command Line Editing,
readline, GNU Readline Library}).

  When in interactive mode, @command{dico} displays its prompt and
waits for you to enter a command.  The default prompt is the name
of the program, followed by a @samp{greater than} sign and a single
space:

@example
dico> _
@end example

  The input syntax is designed so as to save you the maximum amount of
typing.

  If you type any word, the default action is to look up its
definition using the default server and database settings, for
example:

@example
@group
dico> @kbd{man}
From eng-swa, English-Swahili xFried/FreeDict Dictionary:
man  <n.>

    mwanamume
@end group
@end example

  To match the word, instead of defining it, prefix it with a slash,
much as you do in @command{vi}:

@example
@group
dico> /man
From eng-swa, English-Swahili xFried/FreeDict Dictionary:
0) ``can''
1) ``man''
2) ``many''
3) ``map''
4) ``may''
5) ``men''
@end group
@end example
                        
  Displayed is a list of matches retrieved using the default strategy.
To see a definition for a particular match, type the number shown
at its left.  For example, to define ``men'':

@example
@group
dico> 5
From eng-swa, English-Swahili xFried/FreeDict Dictionary:
men <n.>

    wanaume
@end group
@end example

  Define and match are two basic actions.  To discern from them, the
rest of @command{dico} commands begin with a @dfn{command prefix}, a
single punctuation character selected for this purpose.  The default
command prefix is a dot, but it can be changed using the @code{prefix}
command (@pxref{Other Commands, prefix}).

  We will discuss the @command{dico} commands in the following
subsections.

@menu
* Server Commands::
* Database and Strategy::
* Informational Commands::
* History Commands::
* Pager::
* Program Settings::
* Session Transcript::
* Other Commands::
* Command Summary::
@end menu

@node Server Commands
@subsection Server Commands
@cindex open
  The @code{open} command establishes connection to a remote
server.  It takes up to two arguments, first of them specifying
the IP or host name of the server, and the optional second one
specifying the port number to connect to.  For example:

@example
dico> .open gnu.org.ua
@end example

  If any or both of its arguments are absent, the @code{open} command
reuses the value supplied with its previous invocation, or, if it is
issued for the first time, the default values.  The default for server
name is @samp{gnu.org.ua} and the default port number is 2628.  Both
values can be changed at configuration time, see @ref{Default Server}
for a detailed instruction.

  When given one argument, @code{open} checks if it begins with a
directory separator (@samp{/}).  If so, the argument is handled as the
full file name of a UNIX socket.

  Note that you are not required to issue this command.  If it is not
given, @command{dico} will attempt to establish a connection using its
default settings before executing any command that requires a
connection to the server.

@cindex close
  The @code{close} command closes the connection.  It does not take
any arguments.
  
@node Database and Strategy
@subsection Database and Strategy

@cindex database
  The @code{database} command changes or displays the database name which
is used by define and match commands.  To display the database name,
type the command without arguments:

@example
@group
dico> .database
!
@end group
@end example

  To change the database, give its name as an argument to the command:

@example
dico> .database *
@end example

  Once the connection with the server is established, you may use
command line completion facility to select the database from among
those offered by the server.  Typing @kbd{TAB} will show you a list
of databases that begin with the characters you typed:

@example
dico> .database en@kbd{TAB}
en-pl-naut  eng-afr     eng-deu     eng-swa
@end example

  If you supply enough characters to identify a single choice,
@kbd{TAB} will automatically select it.  In the example above, typing
a @kbd{TAB} after

@example
dico> .database en-
@end example

@noindent
completes the database name to:

@example
dico> .database en-pl-naut
@end example

@cindex strategy
  The @code{strategy} command displays or changes the default strategy
name.  As with @code{database}, the strategy completion is available
for this command.

@example
@group
dico> .strategy
.
dico> .strategy dlev
@end group
@end example

@cindex distance
  If the remote server supports @samp{xlev} experimental capability 
(@pxref{Extended Commands, XLEV}), you can use the @code{distance} command
to set the maximum Levenshtein distance for strategies that use
Levenshtein algorithm.  If used without arguments, this command
displays the distance reported by the server and the configured
distance, e.g.:

@example
@group
dico> .distance
Reported Levenshtein distance: 1
No distance configured
@end group
@end example

  If used with a single numeric argument, it attempts to set the
distance to the supplied value.

@node Informational Commands
@subsection Informational Commands
@cindex ls

  The @code{ls} command lists available strategies (@pxref{SHOW, SHOW
STRAT}):

@example
dico> .ls
exact "Match words exactly"
prefix "Match word prefixes"
soundex "Match using SOUNDEX algorithm"
all "Match everything (experimental)"
lev "Match headwords within given Levenshtein distance"
dlev "Match headwords within given Damerau-Levenshtein
      distance"
re "POSIX 1003.2 (modern) regular expressions"
regexp "Old (basic) regular expressions"
suffix "Match word suffixes"
rev-qu "Reverse search in Quechua databases"
@end example

@kwindex ld
  The @code{ld} command lists available databases (@pxref{SHOW, SHOW
DB}):

@example
dico> .ld
eng-swa "English-Swahili xFried/FreeDict Dictionary"
swa-eng "Swahili-English xFried/FreeDict Dictionary"
afr-eng "Afrikaans-English FreeDict Dictionary"
eng-afr "English-Afrikaans FreeDict Dictionary"
@end example

@cindex info
  The @code{info} command displays information about a database, whose
name is given as its argument.  If used without arguments, it displays
information about the current database.

@example
dico> .info pl-en-naut
pl-en-naut - A Polish-English dictionary of nautical terms.
Copyright (C) 2008 Sergey Poznyakoff

Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation
License, Version 1.2 or any later version published by the
Free Software Foundation; with no Invariant Sections, no
Front-Cover and Back-Cover Texts.
@end example

@node History Commands
@subsection History Commands
@flindex .dico_history
  Each issued command is stored in a history list and assigned a
unique @dfn{event number}.  When @command{dico} exits, it saves the
command history to a file named @file{.dico_history} in your home
directory.  Upon startup, it retrieves the history from this file, so
the history is preserved between sessions.

@cindex history
  You can view the command history using the @code{history} command:

@example
dico> .history
  1) .open dict.org
  2) entdeckung
  3) /geschwindigkeit
@end example

  A number of editing commands is provided, that allow you to refer to
previous events from the history list and to edit them.  For example,
to re-issue the 3rd event from the above list, type @samp{!3}.  The
command with this index will be inserted at the @command{dico} prompt
and you will be given a possibility to edit it.  For a detailed
description of all history-editing commands, please refer to
@ref{Using History Interactively, , Using History Interactively,
history, GNU History User Manual}.

@node Pager
@subsection Pager

@cindex pager
@vindex PAGER
  When a command produces output that contains more lines than
there are rows on the terminal, @command{dico} attempts to use a
@dfn{pager program} to display it.  The name (and arguments) of
the pager program are taken from the @command{dico} internal variable,
or, if it is not set, from the @env{PAGER} environment variable.

  The @command{dico} pager setting can be examined or changed using
the @code{pager} command.  When used without arguments, it displays
the current setting:

@example
dico> .pager
less
(Pager set from environment)
@end example

  When used with a single argument, it sets the pager:

@example
dico> .pager "less -R"
@end example

  The argument @samp{-} (a dash) disables pager.

@node Program Settings
@subsection Program Settings

  The commands described in this subsection are designed mostly for
use in @command{dico} initialization file (@pxref{Initialization
File}).

@cindex autologin
@cindex tilde expansion
  The @command{autologin} command sets the name of autologin file to
be used for authentication.  When used without arguments, it displays
the current setting.  The argument to @command{autologin} command is
subject to @dfn{tilde expansion}, i.e. if it begins with @samp{~/},
this prefix is replaced with the name of the current user home
directory, followed by @samp{/}.  Similarly, a prefix
@samp{~@var{login}/} is replaced by the home directory for user
@var{login}, followed by a slash.

@xref{Autologin}, for a detailed discussion of the autologin feature.

@cindex quiet
  The @command{quiet} command toggles the display of @command{dico}
startup banner.  When started, @command{dico} prints a short list
of information useful for beginning users: the program version and
warranty conditions and a command to get help, e.g.:

@example
@group
dico @value{VERSION}
Copyright (C) 2005-2016 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later
<http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and
redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Type ? for help summary

dico>
@end group
@end example

 If you find this output superfluous and useless, you can suppress it
by setting

@example
quiet yes
@end example

@noindent
in your initialization file.

@node Session Transcript
@subsection Session Transcript
@cindex transcript
  @dfn{Session transcript} is a special mode, which displays raw
@acronym{DICT} commands and answers as they are executed.  It is
useful for debugging purposes.

  You enable session transcript by issuing the following command:

@example
dico> .transcript yes
# @r{or}
dico> .transcript on
@end example

  Starting from then, each @acronym{DICT} transaction will be
displayed on standard error output, for example: 

@example
dico> .open
dico: Debug: S:220 Pirx.gnu.org.ua dicod (dico @value{VERSION})
  <mime.xversion.xlev> <32004.1216639476@@gnu.org.ua>
dico: Debug: C:CLIENT "dico 1.99.91"
dico: Debug: S:250 ok
dico: Debug: C:SHOW DATABASES
dico: Debug: S:110 26 databases present
@dots{}
dico: Debug: S:.
dico: Debug: S:250 ok
dico: Debug: C:SHOW STRATEGIES
dico: Debug: S:111 10 strategies present: list follows
dico: Debug: S:exact "Match words exactly"
dico: Debug: S:prefix "Match word prefixes"
dico: Debug: S:soundex "Match using SOUNDEX algorithm"
@dots{}
dico: Debug: S:.
dico: Debug: S:250 ok
@end example

In the example above, ellipses are used to replace long lists of data.
As you see, session transcripts may produce large amount of output.

  To turn the session transcript off, use the following command:

@example
dico> .transcript no
# @r{or}
dico> .transcript off
@end example

  Finally, to query the current state of session transcript, issue
this command without arguments:

@example
@group
dico> .transcript
transcript is on
@end group
@end example

@node Other Commands
@subsection Other Commands

@cindex prefix
The @code{prefix} command queries or changes the current command prefix:

@example
@group
dico> .prefix
Command prefix is .
dico> .prefix @@
dico> @@prefix
Command prefix is @@
@end group
@end example

@cindex prompt
  The @code{prompt} command changes the @command{dico} command line
prompt.  For example, to change it to @samp{dico$}, followed by a single
space, type:

@example
@group
dico> .prompt "dico$ "
dico$ _
@end group
@end example

  Note the use of quotes to include the space character in the
argument.
  
@cindex help
  The @code{help} command displays a short command usage summary.  For
convenience, a single question mark can be used instead of it:

@example
dico> ?
/WORD                    Match WORD.
/                        Redisplay previous matches.
NUMBER                   Define NUMBERth match.
!NUMBER                  Edit NUMBERth previous command.

.open [HOST [PORT]]      Connect to a DICT server.
.close                   Close the connection.
@dots{}
@end example

@cindex version
@cindex warranty
  The @code{version} command displays the package name and version
number, and the @code{warranty} command displays the copyright
statement.

@cindex quit
  Finally, the @code{quit} command leaves the dico shell.  Typing
end-of-file character (@kbd{C-d}) has the same effect.

@node Command Summary
@subsection Dico Command Summary
  For convenience, this subsection lists all available @command{dico}
commands along with their short description and a reference to the
part of this manual where they are described in detail.  The command
names are given without prefix.

@table @code
@item open @var{host} @var{port}
Connect to a @acronym{DICT} server.  Both arguments are optional.
If any of them is absent, the value supplied with the previous
@code{open} command is used.  If there was no previous value, the
default is used, i.e., @samp{gnu.org.ua} for @var{host}, and 
2628 for @var{port}.

@xref{Server Commands, open}.

@item close
Close the connection.

@xref{Server Commands, close}.

@item autologin [@var{file}]
Set or display the autologin file name.

@xref{Autologin}.

@item sasl [@var{bool}]
Without argument, show whether the @acronym{SASL} authentication is
enabled.  With argument, enable or disable it, depending on the value
of @var{bool}.  @xref{Autologin}.

@item database [@var{name}]
Set or display the current database name.

@xref{Database and Strategy, database}.

@item strategy [@var{name}]
Set or display the current strategy name.

@xref{Database and Strategy, strategy}.

@item distance [@var{num}]
Set or query Levenshtein distance.  This command takes effect only if
the remote server supports @samp{xlev} experimental capability 
(@pxref{Extended Commands, XLEV}).

@xref{Database and Strategy, distance}.

@item ls
List available matching strategies.

@xref{Informational Commands, ls}.

@item ld
List all accessible databases.

@xref{Informational Commands, ld}.

@item info [@var{db}]
Display information about the database @var{db}, or the current
database, if used without argument.

@item prefix [@var{c}]
Set or display the command prefix.

@xref{Other Commands, prefix}.

@item transcript [@var{bool}]
Set or display session transcript mode.

@xref{Session Transcript}.

@item verbose [@var{number}]
Set or display debugging verbosity level.  Currently (as of version
@value{VERSION}) it is a no-op.

@item prompt @var{string}
Change command line prompt.

@xref{Other Commands, prompt}.

@item pager @var{string}
Change or display pager settings.

@xref{Pager}.

@item history
Display command history.

@xref{History Commands}.

@item help
Display short command usage summary.

@xref{Other Commands, help}.

@item version
Print program version.

@xref{Other Commands, version}.

@item warranty
Print copyright statement.

@xref{Other Commands, warranty}.

@item quiet @var{bool}
Toggle display of @command{dico} welcome banner.  This command can be
used only in initialization file.

@xref{Program Settings, quiet}.

@item quit
Quit the shell.

@xref{Other Commands, quit}.
@end table

@node Initialization File
@section Initialization File
@cindex init file
@cindex initialization file
@findex .dico
  When you start @command{dico}, it automatically executes commands from its
@dfn{initialization files} (or @dfn{init files}, for short), normally
called @file{.dico}.  Two init files are read: the one
located in your home directory, and the one from the current working
directory.  It is not an error if any or both of these files are absent.

  These files contain a series of @command{dico} commands, as
described in @ref{Interactive Mode}, with the only difference that
no command prefix is used by default.  The @samp{#} character
introduces a comment: any characters from (and including) @samp{#} up
to the newline character are ignored@footnote{The same holds true for
interactive mode as well, but you will hardly need comments on a
terminal.}.

  Init files are useful to change the defaults for your @command{dico}
invocation.  Consider, for example, this init file:

@example
@group
# An example init file for @command{dico}

# Turn the welcome banner off
quiet yes
# Set the location of autologin file
autologin ~/.dicologin
# Use this server by default
open dict.org
# Search in all databases
database *
# Finally, set the custom command prefix
prefix :
@end group
@end example

Notice, that if you wish to change your command prefix, it is
preferable to do it as a last command in your init file, as shown in
this example.  

@node Autologin
@section Autologin
@cindex autologin feature
@cindex authentication
@cindex credentials
  After connecting to a remote server, @command{dico} checks if
the server supports authentication and attempts to authenticate itself
if so.  To do this @command{dico} needs a set of parameters called
@dfn{user credentials}.  The exact set of credentials depends on the
authentication mechanism being used, with user name and password being
the two most important ones.

The user credentials can be supplied from the following sources:

@enumerate 1
@item
Command line options @option{--user} and @option{--password}.

@item
An @acronym{URL} given as a command line argument (@pxref{urls,
user}).

@item
Autologin files.
@end enumerate

  These three sources are consulted in that order, i.e., a user name
supplied with the @option{--user} command line option takes precedence
over the one found in an @acronym{URL} and over any names supplied by
autologin files.

  If, after consulting all these sources, the user name is
established, while the password is not, the resulting action
depends on whether the standard input is connected to a terminal.
If it is, @command{dico} will ask the user to supply a password.
If it is not, authentication is aborted and connection to the server
is closed.

  Some authentication mechanisms require additional credentials.  For
example, GSSAPI authentication requires a @dfn{service name}.  These
credentials can be supplied only in autologin file.

@findex .dicologin
@cindex autologin file
  @dfn{Autologin file} is a plaintext file that contains
authentication information for various @acronym{DICT} servers.  At
most two autologin files are consulted: first the session-specific
file, if it is supplied by @command{autologin} command (@pxref{Program
Settings, autologin}) or by the @option{--autologin} command line
option, next the default file @file{.dicologin} in the user's home
directory.  The default autologin file is examined only if 
no matching record was found in the session-specific one.

  The autologin file format is similar to that of @file{.netrc} file
used by @command{ftp} utility.

  Comments are introduced by a pound sign.  Anything starting from
@samp{#} up to the end of physical line is ignored.

  Empty lines and comments are ignored.

  Non-empty lines constitute @dfn{statements}.  Tokens in a statement
are separated with spaces, tabs, or newlines.  A valid statement must
begin with one of the following:

@table @code
@kwindex machine@r{, autologin keyword}
@item machine @var{name}
  This statement contains parameters for authenticating on machine
@var{name}.

@kwindex default, autologin keyword
@item default
  This statement contains parameters for authenticating on any machine,
except those explicitly listed in @code{machine} statements.  There
can be at most one @code{default} statement in autologin file.  Its
exact location does not matter, it will always be matched after all
explicit @code{machine} statements.
@end table

  During the lookup, @command{dico} searches the autologin file for a
@code{machine} statement whose @var{name} matches the remote server
name as given by @option{--host} command line option, host part of an
@acronym{URL} (@pxref{urls}), or the argument to the @code{open}
command (@pxref{Server Commands, open}).  If it reaches end of the
file without having found such an entry, it uses the @code{default}
value, if available.

  Once a matching entry is found, its subsequent tokens are analyzed.
The following tokens are recognized:

@table @code
@kwindex login, autologin keyword
@item login @var{name}
Supply user name for this server.

@kwindex password, autologin keyword
@item password @var{string}
Supply a password.

@kwindex noauth, autologin keyword
@item noauth
Do not perform authentication on this machine.

@kwindex sasl, autologin keyword
@item sasl
Enable @acronym{SASL} authentication.

@kwindex nosasl, autologin keyword
@item nosasl
Disable @acronym{SASL} authentication.

@kwindex mechanisms, autologin keyword
@item mechanisms @var{list}
Declare acceptable @acronym{SASL} mechanisms.  The @var{list} argument
is a comma-separated list of mechanism names, without intervening
whitespace.  Multiple @code{mechanisms} may be given, in which case
the corresponding lists are concatenated.

@kwindex service, autologin keyword
@item service @var{name}
Declare service name, for authentication methods that need it.  If
this token is omitted, the default service name @samp{dico} is used.

@kwindex realm, autologin keyword
@item realm @var{name}
Declare realm for authentication.

@kwindex host, autologin keyword
@item host @var{name}
Set host name for this machine.  By default, it is determined
automatically.
@end table

  Consider the following autologin entry, for example:

@example
@group
machine a.net user smith password guessme
machine b.net
  sasl
  mechanisms gssapi,digest-md5
  realm example.net
  service dico
  user smith password guessme
default noauth
@end group
@end example

  When connecting to the server @samp{a.net}, @command{dico} will attempt
the usual @acronym{APOP} authentication as user @samp{smith} with password
@samp{guessme}.  When connecting to the machine @samp{b.net}, it will
use @acronym{SASL} authentication, via either @acronym{GSSAPI} or
@acronym{DIGEST-MD5} mechanisms, with realm name @samp{example.net},
service name @samp{dico} and the same user name and password, as for
@samp{a.net}.

  The authentication mechanism is suppressed if the @command{--noauth}
option has been given in the command line, or a matching entry was
found in one of the autologin files, which contained the @code{noauth}
keyword. 

@node Dico invocation
@section Dico invocation

  This section contains a short summary of @command{dico} command line
options.

@subheading Command Line
  The following table summarizes the four existing ways of
@command{dico} invocation:
  
@table @command
@item dico [@var{options}] @var{word}
  Connect to the dictionary and define or match a @var{word}.

@xref{dico options}.

@item dico [@var{options}] @var{url}
  Connect to the dictionary and define or match a word, supplied in
the @var{url}.

@xref{urls}.

@item dico [@var{options}] @var{opmode}
  Connect to the dictionary and query the information required by
@var{opmode} option, which is one of @option{--dbs},
@option{--strategies}, @option{--serverhelp}, @option{--info}, or
@option{--serverinfo}.  See below (@pxref{dico-opmode, Operation
modes}) for a description. 
  
@item dico [@var{options}]
Start interactive shell.  @xref{Interactive Mode}.
@end table

@subheading Server selection options:

@table @option
@item --host=@var{server}
Connect to this server.

@xref{dico options, --host}.

@item --port=@var{port}
@itemx -p @var{port}
Specify the port to connect to.  The argument @var{port} can be either a
port number or its symbolic service name, as listed in
@file{/etc/services}. 

@item --database=@var{name}
@itemx -d @var{name}
Select a database to search.  The @var{name} can be either a name of
one of the databases offered by the server (as returned by
@option{--dbs} option), or one of the predefined database names:
@samp{!} or @samp{*}.

@xref{dico options, --database}.

@item --source=@var{addr}
Set source address for @acronym{TCP} connections.
@end table

@subheading Operation modifiers

@table @option
@item --match
@itemx -m
Match instead of define.

@xref{dico options,--match}.

@item --strategy=@var{name}
@itemx -s @var{name}
Select a strategy for matching.  The argument is either a name of one
of the matching strategies supported by server (as displayed by
@option{--strategies} option) or a dot (@samp{.}) meaning a
server-dependent default strategy.

This option implies @option{--match}.

@xref{dico options,--strategy}.

@item --levdist=@var{n}
@itemx --levenshtein-distance=@var{n}
Sets maximum Levenshtein distance.  Allowed values of @var{n} are
between 1 and 9 inclusively.  This option has effect only if the
remote server supports @samp{xlev} extension (@pxref{Extended
Commands, XLEV}). 

@xref{dico options,--levdist}.

@item --quiet
@itemx -q
Do not print the normal @command{dico} welcome banner when entering
interactive shell.

@xref{Program Settings, quiet}.
@end table

@anchor{dico-opmode}
@subheading Operation modes

@table @option
@item --dbs
@itemx -D
Show available databases.

@xref{dico options, --dbs}.

@item --strategies
@itemx -S
Show available search strategies.

@xref{dico options, --strategies}.

@item --serverhelp
@itemx -H
Show server help.

@item --info=@var{dbname}
@itemx -i @var{dbname}
Show information about database @var{dbname}.

@item --serverinfo
@itemx -I
Show information about the server.

@end table

@subheading Authentication

@table @option
@item --noauth
@itemx -a
Disable authentication.

@xref{Autologin}.

@item --sasl
Enable @acronym{SASL} authentication, if the server supports it.
@xref{Autologin}.

@item --nosasl
Disable @acronym{SASL} authentication.  @xref{Autologin}.

@item --user=@var{name}
@item -u @var{name}
Set user name for authentication.

@xref{Autologin}.

@item --key=@var{string}
@itemx -k @var{string}
@itemx --password=@var{string}
Set shared secret for authentication.

@xref{Autologin}.

@item --autologin=@var{name}
Set the name of autologin file to use.

@xref{Autologin}.

@item --client=@var{string}
@itemx -c @var{string}
Additional text for client command, instead of the default @samp{GNU dico
@value{VERSION}}. 
@end table

@subheading Debugging options

@table @option
@item --transcript
@itemx -t
Enable session transcript.  @xref{Session Transcript}, for a
description.

@item --verbose            
@itemx -v
Increase debugging verbosity level.

@item --time-stamp
Include time stamp in the debugging output.

@item --source-info
Include source line information in the debugging output.
@end table

@subheading Other options

@table @option
@item --help                
@itemx -h
Display a short description of command line options.

@item --usage
Display a short usage message

@item --version
Print program version.
@end table

@node gcider
@chapter GCIDER
@cindex GCIDE
@cindex gcider
@cindex GNU Collaborative International Dictionary of English
@command{Gcider} is a window-based application for browsing the
@dfn{GNU Collaborative International Dictionary of English}
(@acronym{GCIDE}).  When started, it launches a copy of @command{dicod}
with a specially crafted configuration file and interfaces with it via
stdin/stdout.  For operation it needs to know the location of the
@command{dicod} binary and of the directory where the @acronym{GCIDE}
files reside.  When started for the first time it will present you
with a dialog box to help it locate the needed components.  The
location of the @command{dicod} binary is normally guessed by scanning
the @env{PATH} environment variable.  The only parameter you need to
supply is the directory where the dictionary files reside.  Once these
data are entered, the program will save them in its configuration file
(located in @file{~/.gcider}) and will reuse them in subsequent
invocations.

The @command{gcider} user documentation is available online at
@uref{http://dico.gnu.org.ua/gcider.html}.

The program display is organized in three areas, ordered vertically.
The topmost area is the @dfn{menu bar}, which contains pull-down menus.
It is followed by a @dfn{search control} area.  It provides an input
line for you to enter the term to look-up in the dictionary, a set
of widgets for bringing back prior inputs from the history and for
controlling the search types and matching strategies.  The area that
follows presents two windows, side by side.  The leftmost one is the
@dfn{article window}, where definitions of the search terms are
shown.  The rightmost one is the @dfn{match list}, which will present
the results of the recent @dfn{match} command.  Finally, at the very
bottom of the @command{gcider} window is located the @dfn{status
bar}.  Its purpose is twofold.  First, it displays a status of the last
search.  Secondly, it provides a terse contextual help describing what
you can do using the widget your mouse pointer points to.

To look up a word, type it in the input line in the search area and
hit @kbd{CR} or click on the @samp{Define} button.  The definition, if
found, is then displayed in the article window.  This text may contain
@dfn{cross-references} to other words in the dictionary, which are shown
underlined, to draw your attention.  To define a cross-reference,
click on it with your mouse.  You can also define any other word from
the text.  To do so, select it and click on the right button.  Then,
in the menu that will appear, select @samp{Define}. 

If you are not sure about the exact spelling of your search term, try
searching for closest matches first.  To do so, click on
@samp{Match} instead of @samp{Define}.  To find closest matches for a
word in a definition, select the word (or part of it) and select
@samp{Match} in the contextual menu.  In both cases, the program will
try to match the word using the @dfn{strategy} selected currently in
the strategy widget at the right of the search control area.  Matching
headwords will then be displayed in a listbox to the right of the
article window.  Clicking on a headword will bring its definition to
the article window.

To select a match strategy, click on the strategy widget and select
the desired strategy in the pop-down list that will appear.  The list
contains short strategy names.  To help you select the right one, the
status line will show a full description of the currently highlighted
strategy.

Those search terms for which a definition was found are saved in a
@dfn{history list}.  Several ways are provided to retrieve definitions
from that list.  First, clicking on the input widget brings a popdown
list with all headwords from the history list shown in a reverse
chronological order.  Selecting a word from that list brings back its
definition.  Secondly, two special buttons to the right of the input
widget can be used to navigate through the history.  The button marked
with a left arrow brings back previous definition, whereas the one
marked with a right arrow brings back next definition.

By default the history list can accommodate up to 500 search terms.
Once this limit reached, adding a new term to the list discards the
oldest item, so that the total list length remains the same.  Actual
length of the history list can be configured using the
@file{Edit/Appearance} menu.

@node Reporting Bugs
@chapter How to Report a Bug

  Email bug reports to @email{bug-dico@@gnu.org} or
@email{bug-dico@@gnu.org.ua}.  Please include a detailed description
of the bug and information about the conditions under which it occurs,
so we can reproduce it.  To facilitate the task, the following list
shows the basic set of information needed in order to find the bug:

@itemize
@item Package version you use.  The output of @command{dicod
--version} will do.
@item A detailed description of the bug.
@item Conditions under which the bug appears.
@item It is often helpful to send the contents of @file{config.log}
file along with your bug report.  This file is created after running
@command{./configure} in the source root directory of GNU Dico.
@end itemize

@node Available Strategies
@appendix Available Strategies
@include strat.texi

@node Dictionary Server Protocol
@appendix Dictionary Server Protocol
@include proto.texi

@node Time and Date Formats
@appendix Time and Date Formats
@include strftime.texi

@node Libdico
@appendix The Libdico Library
@include libdico.texi

@node Copying This Manual
@appendix GNU Free Documentation License
@include fdl.texi

@node Concept Index
@comment node-name,  next,  previous,  up
@unnumbered Concept Index

This is a general index of all issues discussed in this manual.

@printindex cp

@ifset WEBDOC
@ifhtml
@node This Manual in Other Formats
@unnumbered This Manual in Other Formats
@include otherdoc.texi
@end ifhtml
@end ifset

@bye