\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,
51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301 USA 

Copyright @copyright{} 2008, 2010 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, with the Front-Cover texts being ``GNU Dico Manual'',
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@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
@w{ }
@page
@w{ }
@page
@headings on

@ifnothtml
@page
@summarycontents
@end ifnothtml

@page
@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::             
* 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.
* Reporting Bugs::       How to Report a Bug.

Appendices

* Dictionary Server Protocol::
* Time and Date Formats::
* Libdico::
* Copying This Manual::  The GNU Free Documentation License.
* Concept Index::        Index of Concepts.

@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::
* 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::        Flat Text Databases.

Databases

* Database Visibility::

Modules

* Outline::
* Dictorg::
* Guile::
* Python::
* Stratall::
* Substr::

The @command{guile} module.

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

Dico Module Interface

* dico_database_module::
* Strategies::
* Output::
* Error Reporting::

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::

@end detailmenu
@end menu

@node Preface
@unnumbered Preface
@UNREVISED

@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 correct @acronym{DICT} protocol dialog and
is served by the @command{dicod} daemon itself.  The @dfn{database
layer} is responsible for look ups in dictionary databases.  This
layer is handled 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:

@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 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 to write
database modules in Scheme programming language.

@item python
  This module provides an interface to database modules written in
Python (@uref{http://www.python.org}).  

@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 database modules both in @acronym{C} and in
@acronym{Scheme}.

@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 can be altered
using 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} may be used.  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}:

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

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 client program @command{dico}
attempts to connect 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 1.8.4 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 Pyhton 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 @command{dicod} daemon.  It is
responsible for serving client requests and for coordinating the work
of dictionary modules.

@cindex database
@cindex headword
@cindex article
  @command{Dicod} 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.

@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.  A
@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}.  A
@dfn{database description} provides 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:

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

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:

@smallexample
SHOW INFO en-pl-naut
112 information for en-pl-naut
An English-Polish dictionary of nautical terms

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
.
250 ok
@end smallexample

  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.:

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

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

@cindex strategy
  @FIXME{Write it}
  

@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 interfaces.  Unless the
@command{--foreground} option is specified, it disconnects 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 @option{--lint} option
(@pxref{--lint}) and analyzes its return value.  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
@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 not
disconnect from the controlling terminal and to remain 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:

@smallexample
dict  stream  tcp  nowait  nobody /usr/local/bin/dicod --inetd
@end smallexample
  
@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 @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
@option{--lint} (@option{-t}) command line option.  It causes
@command{dicod} to check configuration file and to exit with status 0
if no errors were detected, and withs status 1 otherwise.

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

@xopindex{config-help, introduced}
  The rest of this section describes the 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::
* 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:

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

@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 file @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 value
separated by any amount of whitespace.  Simple statement is terminated
with a semicolon (@samp{;}), unless it contains a @dfn{here-document}
(see below), in which case semicolon is optional.

  Examples of simple statements:

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

  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{:}.

@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 \\ @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 to split long strings over several
physical lines, e.g.:

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

  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.  The following fragment produces the same result as the
example above:

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

@anchor{here-document}
@item Here-document
@cindex here-document
  @dfn{Here-document} is a special construct that allows 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:

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

  Body of a here-document is interpreted the same way as
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 to indent
here-documents in a natural fashion.  For example:

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

  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: 

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

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

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

  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 with a
single member.  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:

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

  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.
@xref{Daemon Mode}. 

Example:
@smallexample
user nobody;
@end smallexample
@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}, e.g.:

@smallexample
user nobody;
group (man, dict);
@end smallexample

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 @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 @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 form:

@table @asis
@item @var{host}:@var{port}
  Specifies an @acronym{IP}v4 socket to listen on.  The @var{host}
part is either a host name or an @acronym{IP} in ``dotted-quad''
form.  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,
it defaults to @samp{0.0.0.0}, which means ``listen on all
interfaces''.  If @var{port} is omitted, it defaults to 2628.  In this
case the colon may be omitted, too.

  Examples:
  
@smallexample
listen localhost:2628;
listen 127.0.0.1;
listen :2628;
@end smallexample

@item @var{filename}
  Specifies the name of a @acronym{UNIX} socket to listen on.
@end table

  The following statement instructs @command{dicod} to listen on
the address @samp{10.10.10.1}, port 2628 and on the @acronym{UNIX}
socket @file{/var/run/dict}:

@smallexample
listen (10.10.10.1, /var/run/dict);
@end smallexample

@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 privileges of this default directory are
may be insufficient for @command{dicod} to write there after switching
to users 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:

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

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

@FIXME{I am not sure this is quite right.  Should `make install'
create the $localstate/run/dict directory?  But then, make doesn't
know what user to set as its owner...}
@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
will disconnect automatically if remote client did not send any
command within this number of seconds.  Setting timeout to 0 disables
inactivity timeout (the default).

Using this statement along with @code{max-children} allows 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 @code{%l} format (@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.

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

@smallexample
capability auth;
@end smallexample

@cindex authentication database
@cindex database, authentication
  @dfn{User authentication database} keeps, for each user name,
the corresponding plain text password, and, optionally, names of the
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 @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 may 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):

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

@table @var
@item type
A @dfn{database type}, or format.  See below for the 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 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 using @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 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
Database resource returning user password.
@end deffn

@deffn {user-db conf} group-resource arg
Database resource returning user groups.
@end deffn

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

@cindex authentication database configuration
@cindex authentication database definition
To summarize, the definition of an authentication database is:

@smallexample
@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 a resource returning user group information.}
  group-resource @var{resource};
@}
@end group
@end smallexample

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

@node text
@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.  First field is the user name.  It serves as a search
key in the database.  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.  Group file may contain multiple
records with the same key.  For example:

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

  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 @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 file @file{passwd} and user
groups are kept in file @file{user}, and both files reside in
@file{/var/db/dico} directory, then the appropriate database
configuration will be:

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

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

@smallexample
load-module ldap @{
	command "ldap";
@}
@end smallexample

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 option @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 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 given user.  Any
occurrence of @samp{$user} in @var{filter} is replaced with the actual
user name obtaining during the authentication.  Variable expansion
occurs much the same way as in the shell.  In particular, the variable
is expanded only unless it is immediately followed by an alphanumeric
character.  For example, it occurs in:

@smallexample
(uid=$user)
@end smallexample

@noindent
and

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

But it does not occur in

@smallexample
(uid=$users)
@end smallexample

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

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

@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}:

@smallexample
@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 smallexample

  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 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 @code{acl} block statement:

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

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

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 groups listed in
@var{group-list}.
@end table

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

@smallexample
acl @var{name}
@end smallexample

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

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

@table @asis
@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.  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 ``dotted quad''
form, e.g. @samp{255.255.255.224}.

@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:

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

@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}.  Access is denied for anybody else:

@smallexample
@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 smallexample

@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 authentication is performed after connection is
established.

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

connection-acl incoming-conn;
@end group
@end smallexample
@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:

@smallexample
dicod (dico @value{VERSION}) on Linux 2.6.24.4,
dict.example.net up 110+04:42:58, 19647044 forks (6867.9/hour)
@end smallexample
@end deffn

@node Logging and Debugging
@subsection Logging and Debugging
@cindex logging, configuration
  The directive 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}
Set 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}
Log session transcript.  The lines received from client are prefixed
with @samp{C:}, those sent in reply are marked with @samp{S:}.  Here is
an excerpt from the transcript output:

@smallexample
S: 220 Trurl.gnu.org.ua dicod (dico 1.99.90) <mime.xversion>
<1645.1212874507@@Trurl.gnu.org.ua>
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 smallexample

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
allows to keep 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}
Set access log file name.

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

  The format of log file entries is specified using
@code{access-log-format} directive:

@deffn {Configuration} access-log-format @var{string}
Set 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 @asis
@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 @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 serviced 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.:

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

@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

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

@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}.

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

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

@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}:

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


@node General Settings
@subsection General Settings
  The settings in this subsection configure 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:

@smallexample
220 Trurl.gnu.org.ua <auth.mime> <520.1212912026@@Trurl.gnu.org.ua>
@end smallexample

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

The part of this reply after the host name and the first angle
bracket 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.  For
example:

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

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

@smallexample
220 Trurl.gnu.org.ua Please authenticate yourself,
  <auth.mime> <520.1212912026@@Trurl.gnu.org.ua>
@end smallexample
@end deffn

@anchor{hostname directive}
@deffn {Configuration} hostname @var{string}
Set 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 @samp{%v} escape (@pxref{Access Log}).
@end deffn

@deffn {Configuration} server-info @var{string}
Set 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}) allow, 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.:

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

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

@end deffn

@deffn {Configuration} help-text @var{string}
Set 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.

You can use @command{help-text} directive to @emph{append} arbitrary
text to that output, provided that you begin @var{string} with a
plus sign, e.g.:

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

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

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

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

@smallexample
default-strategy lev;
@end smallexample
@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}
Request additional capabilities from @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:

@table @asis
@item auth
The @code{AUTH} command is supported. @xref{Authentication}.

@item 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.

@item 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}.

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

  Capabilities set using the @command{capability} directive are
displayed in the initial server reply (@pxref{initial reply}), and
appropriate entries are added to the @code{HELP} command output.

@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 so that @command{dicod} can load
at run time.

@cindex database handler, defined
  A @dfn{handler} is an instance of a 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}
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 @code{handler} statement is a block statement.  The only
sub-statement allowed within it is @code{command} statement:

@deffn {load-module config} command @var{string}
Set the command line for this handler.  It is similar to shell's
command line: it consists of a name of database module, optionally
followed by a whitespace-separated list of its arguments. Just as in
shell, the name of the module specifies the disk file which should be
loaded.  Arguments are passed to the module @dfn{initialization function}
(@pxref{dico_init}).
@end deffn
@end deffn

For example:

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

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 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 @code{command} statement of a @code{load-module} block.  By default the
order of search is as follows:

@enumerate 1
@item
Optional @dfn{prefix} search directories specified by the
@code{prepend-load-path} directive (see below).

@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 Linux it is set
by the contents of the file @file{/etc/ld.so.conf} and the value of
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 directories, 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:

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

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

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

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

@deffn {Database} name @var{string}
Set 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}
Specify the name of a handler for this database and any arguments for
it.  This handler must be previously defined using @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}:

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

More directives are available to fine-tune the database.

@deffn {Database} description @var{string}
Supply 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 @code{description} directive is specified, its value
takes precedence over 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}
Supply 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.:

@smallexample
@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 smallexample

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} content-type @var{string}
Set the content type of the reply.  E.g.:

@smallexample
directory @{
   name "foo";
   handler "dictorg";
   content-type "text/html";
   ...
@}   
@end smallexample
@end deffn

@deffn {Database} content-transfer-encoding @var{enum}
Set transfer encoding to use when sending @acronym{MIME} replies for
this database.  Allowed values for @var{enum} are:

@table @asis
@item base64
Use @acronym{BASE64} encoding.

@item quoted-printable
Use quoted-printable encoding.
@end table
@end deffn

@menu
* Database Visibility::
@end menu

@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,
however, abridge their 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: global visibility @acronym{ACL} and database visibility
@acronym{ACL}.  The latter takes precedence over the former.

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

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

  Consider the following example:

@smallexample
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 smallexample

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 Strategies and Default Searches
@subsection Strategies and Default Searches
@cindex default searches
  @dfn{Default search} is a @code{MATCH} request with @samp{*} or
@samp{!} as 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 database, 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, Dico allows to limit the use of certain strategies in
default searches.

@deffn {Configuration} strategy @var{name} @{ @var{statements} @}
Restrict the use of 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 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:

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

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, 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 @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:

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

@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:

@smallexample
250 Command complete [d/m/c = 0/63/107265 2.293r 1.120u 0.010s]
@end smallexample
@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}
Create a new alias. 
@end deffn

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

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

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

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

  This configuration will produce the following expansion:

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

  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 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 renames all @command{m4} built-in
macro names so they all start with the prefix @samp{m4_}.  This
is similar to GNU m4 @option{--prefix-builtin} options, 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:

@smallexample
@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 smallexample

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:

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

@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, 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 a 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 option was supplied erroneous argument.

@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
Server exited due to some error not otherwise described in this table.

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

@item 71
@itemx EX_OSERR
Some system error occurred, e.g. the program ran out of memory or file
descriptors, @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.
   
@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{stderr}
@item --stderr
Output diagnostic to stderr.  @xref{Daemon Mode, --stderr}.

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

@item -E
Preprocess configuration file and exit.  @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}).

@xref{Preprocessor}.

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

@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{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{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{no-transcript}
@item --no-transcript
Disable transcript mode.  This is the default.  Use this option if you
wish to temporarly disable transcript mode, enabled in the
configuration file (@pxref{Logging and Debugging, transcript}).

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

@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{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.  The option is provided for debugging
purposes. 

@opsummary{trace-lex}
@item --trace-lex
Trace config file lexer.  The option is provided for debugging
purposes. 

@opsummary{config-help}
@item --config-help
Show configuration file summary.  @xref{Configuration}.

@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}.

@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 Modules
@chapter Modules
@cindex Modules
  GNU Dico comes with a set of loadable modules for handling several
database formats and for extending its functionality.  Modules
are binary loadable files, installed in
@file{@var{$prefix}/lib/dico}.  Modules are configurable on per-module
(@pxref{Handlers, command}) and per-database (@pxref{Databases,
handler}) basis.

  GNU Dico version @value{VERSION} is shipped with the following modules:
@samp{Outline}, @samp{Dictorg}, @samp{Guile}, and @samp{Python}.  The
@samp{Outline} module handles databases written in Emacs Outline
format.  It is useful for small databases.  The @samp{Dictorg} module
handles databases in format designed by @cite{@acronym{DICT} development
group}.  The most existing free databases are written in this format.
Finally, the @samp{Guile} and @samp{Python} allow you to use
arbitrary database modules written in Scheme and Python programming
languages, correspondingly.

  In this chapter we will describe these modules in detail.

@menu
* Outline::
* Dictorg::
* Guile::
* Python::
* Stratall::
* Substr::
* Ldap::
@end menu

@node Outline
@section The @command{outline} module.
@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 depth of 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}, that contains dictionary corpus.  Within it, each
subsection 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:

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

* Dictionary

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

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

@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{tests/devils.out}. 

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

@smallexample
@group
load-module outline @{
   command "outline";
@}

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

@node Dictorg
@section The @command{dictorg} module.
@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 @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 and 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:

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

@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 and makes
these entries behave as other database entries.

@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:

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

@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} may 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 Guile
@section The @command{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 writing
GNU Dico modules in Scheme.  The module is loaded
using the following configuration file statement:

@smallexample
@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 smallexample

@kwindex init-script
@kwindex init-args
@kwindex init-fun
  The @code{init-script} parameter specifies the name of a Scheme
source file that must 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 the 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}
  Guile databases are declared using the following syntax:

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

@noindent
where:

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

@item mod-name
is 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 allow to 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
is 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 @command{guile} module is associated with a 
@var{virtual function table}.  This table is an association list, that
supplies to the module the Scheme @dfn{call-back functions} implemented to
perform particular tasks on that database.  In this association 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 described in the following table:

@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 is used to supply the entries missing in
the former.  Both tables are created during the module initialization,
as described in the next subsection.

Particular virtual 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: 

@smallexample
@group
load-module @var{mod-name} @{
   command "guile init-script=@file{@var{script}}"
           " init-fun=@var{function}";
@}
@end group
@end smallexample
@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 an @dfn{initialization
function}.  This Scheme function is used to construct 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
@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.:

@smallexample
database @{
   name @var{db-name};
   handler "@var{mod-name}...";
@}
@end smallexample

This time, it is given @var{db-name} as its argument and its return 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.  The description of each function 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 @code{name} statement of @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: 

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

@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 structure that is used to identify this database, and that
keeps its internal state.  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, return @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, empty string is used.
@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, return @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

Database searches are 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 @code{output} callback, which is responsible
for outputting it.

@deffn {Guile Callback} lang dbh
Virtual Table: @code{(cons "lang" lang)}@*
@FIXME{Returns (cons (list @var{source}) (list @var{dest}))}
@end deffn

@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 a 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 all matches of @var{key} from the database @var{dbh}, using
matching 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}.  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} 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.
@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

@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, that access 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. @FIXME-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{example.scm} and a short database for it, @file{example.db}, are
shipped with the distribution in the directory @file{tests}.

  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:

@smallexample
("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 smallexample

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

@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 the 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 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 used in it.  The
@samp{exact} strategy is the easiest 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} may be 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, 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 The @command{python} module
@cindex Python
@UNREVISED

@node Stratall
@section The @command{stratall} module
@cindex stratall
@cindex all, strategy
  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:

@smallexample
load-module stratall @{
        command "stratall";
@}
@end smallexample

  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}:

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

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

@smallexample
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 smallexample

  The loading procedure expects no arguments:

@smallexample
load-module substr @{
        command "substr";
@}
@end smallexample

@node Ldap
@section The @command{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:

@smallexample
load-module ldap @{
	command "ldap";
@}
@end smallexample

@xref{ldap}, for a description of its use.

@node Interface
@chapter Dico Module Interface
@UNREVISED

@menu
* dico_database_module::
* Strategies::
* Output::
* Error Reporting::
@end menu

@node dico_database_module
@section dico_database_module
@UNREVISED

@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
Additional capabilities.  This member is reserved for future use (as
of GNU Dico version @value{VERSION}.  Use @code{DICO_CAPA_DEFAULT} to
initialize it.
@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,
quoted strings (using both single and double quotes) are parsed as a
single word.
@end table

This method is optional.
@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 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 is passed as the first argument
to other methods.  On error, @code{dico_init_db} returns @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.

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 a part of child process initialization routine.

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 a part of child process termination routine.

Return @samp{0} on success, or any non-@samp{0} value on failure.

The @code{dico_close} method is optional, but it must be defined, if
@code{dico_open} is defined.
@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}).  After use, the value
returned by @code{dico_db_info} is freed using system @code{free}
function.

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}).  After use, the value
returned by @code{dico_db_descr} is freed using system @code{free}
function.

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})
Find in the database identified by @var{dh} matches for headword
@var{word}, using matching strategy @var{strat}.

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}.

Return @samp{0} on success, or any non-@samp{0} value on failure.
@end deftypefn

@deftypefn {Dico Callback} size_t dico_result_count (dico_result_t @var{rp})
Return number of distinct elements in a result set, identified by
@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} size_t dico_compare_count (dico_result_t @var{rp})
Return 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

@node Strategies
@section Strategies
@UNREVISED

@node Output
@section Output
@UNREVISED

@node Error Reporting
@section Error Reporting
@UNREVISED

@node dico client
@chapter Dico --- a client program.
@UNREVISED
@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 read 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.:

@smallexample
$ dico entdeckung
@end smallexample

  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 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 @option{--host} option, for example:

@smallexample
$ dico --host dico.org entdeckung
@end smallexample

  To search in a particular database, use @option{--database}
(@option{-d}) option.  For example, to display definitions from
all databases:

@smallexample
$ dico --database '*' entdeckung
@end smallexample

@noindent
Note single quotes around the asterisk.

  To get a list of databases offered by the server, use @option{--dbs}
(@option{-D}) option.  In this case you may not give any non-option
arguments.   For example:

@smallexample
$ dico --dbs
@end smallexample

  If you wish to get a list of matches, instead of definitions, use
@option{--match} (@option{-m}) option.  For example, the following
invocation will display all matches from all the databases:

@smallexample
$ dico --database '*' --match entdeckung
@end smallexample

  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 @option{--strategy} (@option{-s}) option.

  If the remote server supports @samp{xlev} experimental capability
(@pxref{Extended Commands, XLEV}, you may use @option{--levdist}
(@option{--levenshtein-distance}) option to set maximum Levenshtein
distance, for example:

@smallexample
$ dico --levdist 2 --match entdeckung
@end smallexample

  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:

@smallexample
$ dico dict://gnu.org.ua/d:entdeckung
@end smallexample

A @acronym{DICT} @acronym{URL} consists of the following parts:

@smallexample
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 smallexample

The @samp{/d} syntax requests the definition of @var{word}, whereas
the @samp{/m} syntax queries for matches, and is similar to
@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
User name to use in authentication.  Similar to @option{--user}
option.  If @var{user} is omitted and cannot be retrieved by other
means, no authentication is performed.  @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
@option{--key} command line option.

For compatibility with other @acronym{URL}s, @command{dico} allows to
delimit @var{user} and @var{pass} with a colon (@samp{:}), instead of
semicolon.

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 or @acronym{IP} address of the server to query.  Same as
@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 @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 @option{--database} command line option.

@item strat
The matching strategy to use.  If omitted, @samp{.} is assumed.

Same as @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:

@smallexample
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 smallexample

@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 the 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:

@smallexample
dico> _
@end smallexample

  The input syntax is designed so as to save you 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:

@smallexample
@group
dico> @kbd{man}
From eng-swa, English-Swahili xFried/FreeDict Dictionary:
man  <n.>

    mwanamume
@end group
@end smallexample

  To match the word, instead of defining it, prefix it with a slash
much as you do in @command{vi}:

@smallexample
@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 smallexample
                        
  Displayed is a list 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'':

@smallexample
@group
dico> 5
From eng-swa, English-Swahili xFried/FreeDict Dictionary:
men <n.>

    wanaume
@end group
@end smallexample

  Define and match are two basic actions.  To discern from them, the
rest of @command{dico} commands begins 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 with 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:

@smallexample
dico> .open gnu.org.ua
@end smallexample

  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.

  Note that you are not required to issue this command.  If it is not
given, @command{dico} will attempt to connect 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 in define and match commands.  To display the database name,
type the command without arguments:

@smallexample
@group
dico> .database
!
@end group
@end smallexample

  To change the database, give its name as an argument to the command:

@smallexample
dico> .database *
@end smallexample

  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:

@smallexample
dico> .database en@kbd{TAB}
en-pl-naut  eng-afr     eng-deu     eng-swa
@end smallexample

  If you supply enough characters to identify a single choice,
@kbd{TAB} will automatically select it, for example typing it
after

@smallexample
dico> .database en-
@end smallexample

@noindent
completes the database name to:

@smallexample
dico> .database en-pl-naut
@end smallexample

@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.

@smallexample
@group
dico> .strategy
.
dico> .strategy dlev
@end group
@end smallexample

@cindex distance
  If the remote server supports @samp{xlev} experimental capability 
(@pxref{Extended Commands, XLEV}), you can use @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.:

@smallexample
@group
dico> .distance
Reported Levenshtein distance: 1
No distance configured
@end group
@end smallexample

  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}):

@smallexample
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 smallexample

@cindex .ld
  The @code{ld} command lists available databases (@pxref{SHOW, SHOW
DB}):

@smallexample
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 smallexample

@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.

@smallexample
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 smallexample

@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 in 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:

@smallexample
dico> .history
  1) .open dict.org
  2) entdeckung
  3) /geschwindigkeit
@end smallexample

  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 any command produces an 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 is 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 set or listed using
@code{pager} command.  When used without arguments, it displays
the current setting:

@smallexample
dico> .pager
less
(Pager set from environment)
@end smallexample

  When used with a single argument, it sets the pager:

@smallexample
dico> .pager "less -R"
@end smallexample

  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 by 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.:

@smallexample
dico @value{VERSION}
Copyright (C) 2005, 2006, 2007, 2008 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 smallexample

 If you find this output superfluous and useless, you can suppress it
by setting

@smallexample
quiet yes
@end smallexample

@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:

@smallexample
dico> .transcript yes
# @r{or}
dico> .transcript on
@end smallexample

  Starting from then, each @acronym{DICT} transaction will be
displayed on standard error output, for example: 

@smallexample
dico> .open
dico: Debug: S:220 Pirx.gnu.org.ua dicod (dico 1.99.90)
<mime.xversion.xlev> <32004.1216639476@@Pirx.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
...
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''
...
dico: Debug: S:.
dico: Debug: S:250 ok
@end smallexample

In the example above, ellipsis replaces 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:

@smallexample
dico> .transcript no
# @r{or}
dico> .transcript off
@end smallexample

  Finally, to query the current state of session transcript, issue
this command without arguments:

@smallexample
@group
dico> .transcript
transcript is on
@end group
@end smallexample

@node Other Commands
@subsection Other Commands

@cindex prefix
The @code{prefix} command allows you to change command prefix:

@smallexample
@group
dico> .prefix
Command prefix is .
dico> .prefix @@
dico> @@prefix
Command prefix is @@
@end group
@end smallexample

@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:

@smallexample
@group
dico> .prompt "dico$ "
dico$ _
@end group
@end smallexample

  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:

@smallexample
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.
...
@end smallexample

@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 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}.

@FIXME-xref{SASL}.

@item database [@var{name}]
Set or display current database name.

@xref{Database and Strategy, database}.

@item strategy [@var{name}]
Set or display current strategy.

@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 database @var{db}, or the current
database, if used without argument.

@item prefix [@var{c}]
Set or display 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. @FIXME-xref{}.

@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:

@smallexample
# An example init file for @command{dico}

# Turn 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 smallexample

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
@UNREVISED

@FIXME{The following paragraph is inaccurate.  It should also describe SASL
authentication and its credentials.}

  After connecting to a remote server, @command{dico} checks if it
announces @samp{auth} capability, and if so, it attempts to authenticate
to the remote server.  To do so @command{dico} needs two parameters:
user name and password.  These parameters can either be supplied using
different 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 @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 the above data source, 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 with the server
is closed.

@findex .dicologin
@cindex autologin file
  An @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 compose @dfn{statements}.  Tokens in a statement may
be separated by spaces, tabs, or newlines.  A valid statement must
begin with one of the following:

@table @code
@kwindex machine, 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 an argument to the @code{open}
command (@pxref{Server Commands, open}).  If it reaches the end of
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:

@smallexample
@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 smallexample

  When connecting to the server @samp{a.net}, @command{dico} will attempt
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, using either @acronym{GSSAPI} or
@acronym{DIGEST-MD5} mechanisms, 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 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}.

@itemx --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.  @FIXME-xref{SASL}.

@item --nosasl
Disable @acronym{SASL} authentication.  @FIXME-xref{SASL}.

@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{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 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 that is 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 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

@bye




