![[image of the Head of a GNU]](/graphics/gnu-head-sm.jpg)
|
|
Dico |
GNU Dictionary Server |
Sergey Poznyakoff |
Dédié à la mémoire de Jacques Brel.
dicod daemon.
This edition of the GNU Dico Manual, last updated 29 March 2009, documents Dico Version 2.0.
(This message will disappear, once this node revised.)
GNU Dico is an implementation of DICT dictionary server
(described in RFC 2229) and a set of accompanying utilities.
The GNU Dico server uses two-layer model. The protocol
layer is responsible for correct DICT protocol dialog and
is served by the dicod daemon itself. The database
layer is responsible for look ups in dictionary databases. This
layer is handled by external 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:
This module provides full support for the format designed by the DICT development group (http://dict.org). This is a de facto standard for DICT databases. A number of dictionary databases in this format are provided by the FreeDict project (http://freedict.org).
This module provides an interface to Guile, the GNU's Ubiquitous Intelligent Language for Extensions (http://www.gnu.org/software/guile) and allows to write database modules in Scheme programming language.
This module provides an interface to database modules written in Python (http://www.python.org).
This module handles simple databases in GNU Emacs outline format. It is designed mostly for test purposes.
This manual describes how to configure and use the Dico dictionary system. It also describes the API for writing Dico database modules both in C and in Scheme.
Building Dico is quite straightforward. You run
./configure, then make, followed by make
install, and you are done.
Actions the 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
autoconf system. For a detailed description of these option
see the ‘INSTALL’ file shipped with the sources. Yet another
options are specific for Dico. We will describe them in this chapter.
The runtime configuration system uses m4 to preprocess
the configuration file (see section Using Preprocessor to Improve the Configuration., which makes the
configuration extremely flexible. We recommend to use GNU m4 as a
preprocessor(1).
However, any other implementation of m4 may be used. The
configure script tries to determine full file name of the
preprocessor binary and the necessary command line options. In case
it makes a wrong guess, you can instruct it to use a particular
preprocessor by using DEFAULT_PREPROCESSOR configuration
variable. For example, the following configure invocation
instructs it to use /usr/local/bin/gm4:
$ ./configure DEFAULT_PREPROCESSOR="/usr/local/bin/gm4 -s" |
Note the use of the ‘-s’ preprocessor option. It instructs
m4 to produce line directives which help dicod
produce correct diagnostics about eventual configuration errors.
Unless your m4 implementation does not have this feature, we
recommend to always use it in DEFAULT_PREPROCESSOR value.
Finally, if you do not wish to use preprocessor at all, you can
disable it using ‘--without-preprocessor’ option to
configure.
Unless given an explicit dictionary server, the client program dico
attempts to connect the server <dict://dico.gnu.org.ua>. You may
change this default by defining the DEFAULT_DICT_SERVER variable. For
example, the following command line selects ‘dict.org’ as the default
server:
$ ./configure DEFAULT_DICT_SERVER=dict.org
The value of the 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 ‘/etc/services’.
The GNU's Ubiquitous Intelligent Language for Extensions, or
Guile(2) can
be used to write database modules for GNU Dico. This requires
Guile version 1.8.4 or newer. The configure script will
probe for the presence of Guile on your system and automatically
enable its use if its version number is high enough.
If you do not wish to use Guile, use ‘--without-guile’ to disable it.
The support for Python (http://www.python.org) is enabled
automatically if configure detects that Python version 2.5 or
later is installed on your machine.
If you do not wish to use Python, use ‘--without-python’ to disable it.
The dicod daemon uses syslogd for diagnostics.
The default syslog facility can be set using LOG_FACILITY
configuration variable. Its allowed arguments are ‘user’,
‘daemon’, ‘auth’, ‘authpriv’, ‘mail’, ‘cron’,
and ‘local0’ through ‘local7’. Case is not significant. In
addition, these words can be prefixed with ‘log_’.
By default, the ‘daemon’ facility is used.
dicod daemon. The main component of GNU Dico is dicod daemon. It is
responsible for serving client requests and for coordinating the work
of dictionary modules.
Dicod operates on a set of databases. Each database
contains a set of headwords with corresponding articles,
therefore it can be regarded as a dictionary, in which articles supply
definitions (or translations) for headwords.
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 database information string (or info, for short), supplies a short description of the database. It is a sentence, tersely describing the database, e.g. ‘English-German Dictionary’. A 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 SHOW DB lists all available databases along with their
descriptions:
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 |
Each line of output lists a name of the dictionary, and the corresponding description.
The SHOW INFO command displays full information about a
database, whose name is given as its argument:
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 |
A definition for any given headword can be requested using the
DEFINE command. It takes two arguments, the name of the
database and the headword to look for in that database, e.g.:
DEFINE en-pl-naut sprit |
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.
There are two operation modes: ‘daemon’ and ‘inetd’.
The ‘daemon’ mode is enabled by mode daemon statement in
the configuration file (see mode statement)). It is also the
default mode. In daemon mode dicod listens for incoming
requests on one or several interfaces. Unless the
--foreground option is specified, it disconnects from the
controlling terminal and switches to background (becomes a
daemon). When an incoming connection arrives, it forks a
subprocess for handling it.
In this mode the following signals cause dicod to
terminate: ‘SIGTERM’, ‘SIGQUIT’, and ‘SIGINT’. The
‘SIGHUP’ signal causes the program to restart. This works only
if both the program name and its configuration file name (if given
using ‘--config’ option) are absolute file names.
Upon receiving ‘SIGHUP’, dicod first verifies if the
configuration file does not contain fatal errors. To do that, the
program executes a copy of itself with ‘--lint’ option
(see –lint) and analyzes its return value. Only if this check
passes, dicod restarts itself. This ensures that the daemon
will not terminate due to unnoticed errors in its configuration file.
Upon receiving ‘SIGTERM’, ‘SIGQUIT’, or ‘SIGINT’, the
program stops accepting incoming requests and sends the ‘SIGTERM’
signal to all active subprocesses. Then it waits a predefined amount
of time for all processes to terminate (see shutdown-timeout).
Any subprocesses that do not terminate after this time are sent
‘SIGKILL’ signal. Then, the database modules are unloaded and
dicod terminates.
Several command line options are provided that modify the behavior
of dicod in this mode. These options are mainly designed
for debugging and error-hunting purposes.
The ‘--foreground’ option instructs the server to not
disconnect from the controlling terminal and to remain in the
foreground. It is often used with ‘--stderr’ option,
which instructs dicod to output all diagnostic to the
standard error output, instead of syslog which is used by default.
In ‘inetd’ operation mode inetd receives requests
from standard input and sends its replies to the standard output.
This mode is enabled by mode inetd statement (see mode statement) in configuration file, or by the ‘--inetd’ command
line option (see –inetd). This mode is usually used when
invoking dicod from ‘inetd.conf’ file, as in example
below:
dict stream tcp nowait nobody /usr/local/bin/dicod --inetd |
Upon startup, dicod reads its settings and database
definitions from a configuration file ‘dicod.conf’. By
default it is located in $sysconfidr (i.e., in most cases
‘/usr/local/etc’, or ‘/etc’), but an alternative location
may be specified using ‘--config’ command line option
(see –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.
To test the configuration file without starting the server use
‘--lint’ (‘-t’) command line option. It causes
dicod to check configuration file and to exit with status 0
if no errors were detected, and withs status 1 otherwise.
Before parsing, configuration file is preprocessed using
m4 (see section Using Preprocessor to Improve the Configuration.). To see the preprocessed
configuration without actually parsing it, use ‘-E’ command
line option. To avoid preprocessing it, use
‘--no-preprocessor’ option.
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 dicod --config-help.
A 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 white space are ignored except as they serve to separate tokens. Some white space is required to separate otherwise adjacent keywords and values.
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. Single-line comments start with ‘#’ or ‘//’ and continue to the end of the line:
# This is a comment // This too is a comment |
Multi-line or C-style comments start with the two characters ‘/*’ (slash, star) and continue until the first occurrence of ‘*/’ (star, slash).
Multi-line comments cannot be nested.
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 ‘#’ sign and end with the next physical newline character. As of GNU Dico version 2.0, the following pragmatic comments are understood:
#include <file>#include fileInclude the contents of the file file. If file is an absolute file name, both forms are equivalent. Otherwise, the form with angle brackets searches for the file in the 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:
Where prefix is the installation prefix.
New directories can be appended in front of it using ‘-I’ (‘--include-dir’) command line option (see –include-dir).
#include_once <file>#include_once file Same as #include, except that, if the file has already
been included, it will not be included again.
#line num#line num "file" This line causes dicod to believe, for purposes of error
diagnostics, that the line number of the next source line is given by
num and the current input file is named by file.
If the latter is absent, the remembered file name does not change.
# num "file" This is a special form of #line statement, understood for
compatibility with the C preprocessor.
In fact, these statements provide a rudimentary preprocessing features. For more sophisticated ways to modify configuration before parsing, see Using Preprocessor to Improve the Configuration..
A simple statement consists of a keyword and value separated by any amount of whitespace. Simple statement is terminated with a semicolon (‘;’), unless it contains a here-document (see below), in which case semicolon is optional.
Examples of simple statements:
timing yes; access-log-file /var/log/access_log; |
A keyword begins with a letter and may contain letters, decimal digits, underscores (‘_’) and dashes (‘-’). Examples of keywords are: ‘group’, ‘identity-check’.
A value can be one of the following:
A number is a sequence of decimal digits.
A boolean value is one of the following: ‘yes’, ‘true’, ‘t’ or ‘1’, meaning true, and ‘no’, ‘false’, ‘nil’, ‘0’ meaning false.
An unquoted string may contain letters, digits, and any of the following characters: ‘_’, ‘-’, ‘.’, ‘/’, ‘:’.
A quoted string is any sequence of characters enclosed in double-quotes (‘"’). A backslash appearing within a quoted string introduces an escape sequence, which is replaced with a single character according to the following rules:
| Sequence | Replaced with |
| \a | Audible bell character (ASCII 7) |
| \b | Backspace character (ASCII 8) |
| \f | Form-feed character (ASCII 12) |
| \n | Newline character (ASCII 10) |
| \r | Carriage return character (ASCII 13) |
| \t | Horizontal tabulation character (ASCII 9) |
| \\ | A single backslash (‘\’) |
| \" | A double-quote. |
Table 3.1: Backslash escapes
In addition, the sequence ‘\newline’ is removed from the string. This allows to split long strings over several physical lines, e.g.:
"a long string may be\ split over several lines" |
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:
"a long string may be" " split over several lines" |
Here-document is a special construct that allows to introduce strings of text containing embedded newlines.
The <<word construct instructs the parser to read all
the following lines up to the line containing only word, with
possible trailing blanks. Any lines thus read are concatenated
together into a single string. For example:
<<EOT A multiline string EOT |
Body of a here-document is interpreted the same way as double-quoted string, unless word is preceded by a backslash (e.g. ‘<<\EOT’) or enclosed in double-quotes, in which case the text is read as is, without interpretation of escape sequences.
If word is prefixed with - (a dash), then all leading
tab characters are stripped from input lines and the line containing
word. Furthermore, if - 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:
<<- TEXT
All leading whitespace will be
ignored when reading these lines.
TEXT
|
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:
help-text <<-EOT
A sample help text.
EOT;
|
A 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:
capability (mime,auth); |
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. ‘capability mime;’ is equivalent to ‘capability (mime);’.
A 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:
load-module outline {
command "outline";
}
|
The closing curly brace may be followed by a semicolon, although this is not required.
Server settings control how dicod is executed on the
server machine.
Run with the privileges of this user. Dicod does not
require root privileges, so it is recommended to always use this
statement when running dicod in daemon mode.
See section Daemon Operation Mode.
Example:
user nobody; |
If user is given, 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 group statement retains the supplementary
groups listed in list, e.g.:
user nobody; group (man, dict); |
This statement is ignored if user statement is not present or
if dicod is running in inetd mode. See section Inetd Operation Mode.
Sets server operation mode. The argument is one of:
Run in daemon mode. See section Daemon Operation Mode, for a detailed description.
Run in inetd mode. See section Inetd Operation Mode, for a detailed description.
This statement is overridden by the ‘--inetd’ command line option. See –inetd.
Specify IP addresses and ports to listen on in daemon mode.
By default, dicod will listen on port 2628 on all existing
interfaces. Use listen statement to abridge the list of
interfaces to listen on, or to change the port number.
Elements of list can have the following form:
Specifies an IPv4 socket to listen on. The host part is either a host name or an IP in “dotted-quad” form. The port part is either a numeric port number or a symbolic service name which is found in ‘/etc/services’ file.
Either of the two parts may be omitted. If host is omitted, it defaults to ‘0.0.0.0’, which means “listen on all interfaces”. If port is omitted, it defaults to 2628. In this case the colon may be omitted, too.
Examples:
listen localhost:2628; listen 127.0.0.1; listen :2628; |
Specifies the name of a UNIX socket to listen on.
The following statement instructs dicod to listen on
the address ‘10.10.10.1’, port 2628 and on the UNIX
socket ‘/var/run/dict’:
listen (10.10.10.1, /var/run/dict); |
Store PID of the master process in this file.
Default is ‘localstatedir/run/dicod.pid’.
Notice that the privileges of this default directory are
may be insufficient for dicod to write there after switching
to users privileges (see user statement). One solution to this is
to create a subdirectory with the same owner as given by user
statement and to point the PID file there:
pidfile /var/run/dict/dicod.pid; |
Another solution is to make PID directory group-writable and
to add the owner group to the group statement (see group statement).
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.
Set inactivity timeout to the 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 max-children allows to control
the server load.
When the master server is shutting down, wait this number of seconds for all children to terminate. Default is 5 seconds.
Enable identification check using AUTH protocol
(RFC 1413). The received user name or UID can
be shown in access log using %l format (see section Access Log).
Use encryption keys from the named file to decrypt AUTH replies encrypted using DES.
Set timeout for AUTH input/output operation to number of seconds. Default timeout is 3 seconds.
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 auth
server capability (see section Server Capabilities):
capability auth; |
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 DICT authentication scheme (see section The AUTH Command), 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 user-db block statement:
Declare user authentication database.
Dico's authentication is designed so that various authentication database formats may easily be added. A database is identified by its URL, or Universal Resource Locator. It consists of the following parts (square brackets denoting optional ones):
type://[[user[:password]@]host]/path[params] |
A database type, or format. See below for the list of available database formats.
User name necessary to access the database.
User password necessary to access the database.
Domain name or IP address of a machine running the database.
A 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.
A list of protocol-dependent parameters. Each parameter is of the
form keyword=name, multiple parameters are separated
with semicolons.
An 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:
Database resource returning user password.
Database resource returning user groups.
The exact semantics of 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 SQL databases, resource is an SQL query, etc. Below we will discuss URLSs and resources used by each database type.
To summarize, the definition of an authentication database is:
# Define user database for authentication. user-db url { # Name of a password resource. password-resource resource; # Name of a resource returning user group information. group-resource resource; } |
A text authentication database consists of one or two flat text files — a password file, which contains user passwords, and a group file, which contains user groups. The latter is optional. Both files have the same format:
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:
$ grep smith pass smith guessme $ grep smith group smith user smith timing smith tester |
This means that user ‘smith’ has password ‘guessme’ and is a member of three groups: ‘user’, ‘timing’ and ‘tester’.
An URL of a text database begins with ‘text’ and
contains only path element, which gives the name of the
directory where the database files reside. The name of a password
file is given by password-resource statement. The name of a
group file is given by group-resource statement.
For example, if user passwords are kept in file ‘passwd’ and user groups are kept in file ‘user’, and both files reside in ‘/var/db/dico’ directory, then the appropriate database configuration will be:
user-db text:///var/db/dico {
password-resource passwd;
group-resource group;
}
|
Access control lists, or ACLs for short, are lists of
permissions that can be applied to certain dicod objects.
They can be used to control who can connect to the dictionary server
and what resources are offered to whom.
An ACL is defined using acl block statement:
acl name {
definitions
}
|
The name parameter specifies a unique name for that ACL. This name will be used by another configuration statements (See section Security Settings, and see section Database Visibility) to refer to that ACL.
A part between the curly braces (denoted by definitions above), is a list of access statements. There are two types of such statements:
Allow access to resource.
Deny access to resource.
All parts of an access statement are optional, but at least one of them must be present.
The user-group part specifies which users match this entry. Allowed values are the following:
allAll users.
authenticatedOnly authenticated users.
group group-listAuthenticated users which are members of at least one of groups listed in group-list.
The sub-acl part, if present, allows to branch to another ACL. The syntax of this group is:
acl name |
where name is the name of a previously defined ACL.
Finally, the host-list group allows to match client addresses.
It consists of a from keyword followed by a list of
address specifiers. Allowed address specifiers are:
Matches if the client IP equals addr. The latter may be given either as an IP address or as a host name, in which case it will be resolved and the first of its IP addresses will be used.
Matches if first netlen bits from the client IP address equal to addr. The network mask length, netlen must be an integer number in the range from 0 to 32. The address part, addr, is as described above.
The specifier matches if the result of logical AND between the client IP address and netmask equals to addr. The network mask must be specified in “dotted quad” form, e.g. ‘255.255.255.224’.
Matches if connection was received from a UNIX socket filename, which must be given as an absolute file name.
To summarize, the syntax of an access statement is:
allow|deny [all|authenticated|group group-list]
[acl name] [from addr-list]
|
where square brackets denote optional parts and vertical bar means ‘one of’.
When an 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, allow
or deny, defines the result of ACL match. If the end
of list is reached, the result is ‘allow’, unless explicitly
specified otherwise.
For example, the following statement defines an ACL named ‘common’, that allows access for any user connected via local UNIX socket ‘/tmp/dicod.sock’ or coming from a local network ‘192.168.10.0/24’. Any authenticated users are allowed, provided that they are allowed by another ACL ‘my-nets’ (which should have been defined before this definition). Users coming from the network ‘10.10.0.0/24’ are allowed if they authenticate themselves and are members of groups ‘dicod’ or ‘users’. Access is denied for anybody else:
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;
}
|
See section Security Settings, for information on how to control daemon security settings.
See section Database Visibility, for a detailed description on how to use ACLs to control access to databases.
This subsection describes configuration settings that control access
to various resources served by dicod.
Use ACL acl-name to control incoming connections. The ACL itself must be defined before this statement. Using user-group (see previous subsection) in this ACL makes no sense, because authentication is performed after connection is established.
acl incoming-conn {
allow from 213.130.0.0/19;
deny any;
}
connection-acl incoming-conn;
|
This statement controls whether to show system information in reply
to SHOW SERVER command (see section SHOW SERVER). The
information will be shown only if ACL acl-name allows it.
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:
dicod (dico 2.0) on Linux 2.6.24.4, dict.example.net up 110+04:42:58, 19647044 forks (6867.9/hour) |
The directive described in this subsection provide basic logging capabilities.
Prefix syslog messages with this string. By default, the program name is used.
Set syslog facility to use. Allowed values are: ‘user’, ‘daemon’, ‘auth’, ‘authpriv’, ‘mail’, ‘cron’, ‘local0’ through ‘local7’ (case-insensitive), or a facility number.
Prefix diagnostics messages with a string identifying their severity.
Log session transcript. The lines received from client are prefixed with ‘C:’, those sent in reply are marked with ‘S:’. Here is an excerpt from the transcript output:
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 |
This option produces lots of output and can significantly slow down
the server. Use it only if you are debugging dicod or
some remote client. Never use it in a production environment.
GNU Dico provides a feature similar to Apache's CustomLog, which
allows to keep a log of MATCH and DEFINE requests. To
enable this feature, specify the name of the log file using the
following directive:
Set access log file name.
access-log-file /var/log/dico/access.log; |
The format of log file entries is specified using
access-log-format directive:
Set format string for access log file.
Its argument can contain literal characters, which are copied into the log file verbatim, and format specifiers, i.e. special sequences which begin with ‘%’ and are replaced in the log file as shown in the table below.
The percent sign.
Remote IP-address.
Local IP-address.
Size of response in bytes.
Size of response in bytes in CLF format, i.e. a ‘-’ rather than a ‘0’ when no bytes are sent.
Remote client (from CLIENT command (see section The CLIENT Command)).
The time taken to serve the request, in microseconds.
Request command verb in abbreviated form, suitable for use in
URLs, i.e. ‘d’ for DEFINE, and ‘m’ for
MATCH. See section DICT URL.
Remote host.
Request command verb (DEFINE or MATCH).
Remote logname (from identd, if supplied). This will return a
dash unless identity-check is set to true.
See identity-check.
The search strategy.
The canonical port of the server serving the request.
The PID of the child that serviced the request.
The database from the request.
Full request.
The nth token from the request (n is 0-based).
Reply status. For multiple replies, the form ‘%s’ returns the status of the first reply, while ‘%>s’ returns that of the last reply.
Time the request was received in the standard Apache format, e.g.:
[04/Jun/2008:11:05:22 +0300] |
The time, in the form given by format, which should be a valid
strftime format. See section Time and Date Formats, for a detailed
description.
The standard ‘%t’ format is equivalent to
[%d/%b/%Y:%H:%M:%S %z] |
The time taken to serve the request, in seconds.
Remote user from AUTH command.
The host name of the server serving the request. See hostname directive.
Actual host name of the server (in case it was overridden in configuration).
The word from the request.
For the reference, here is the list of format specifiers that
have different meaning than in Apache: ‘%C’, ‘%H’, ‘%m’,
‘%q’. The following format specifiers are unique to dicod:
‘d’, ‘%{n}R’, ‘%V’, ‘%W’.
Absence of the access-log-format directive is equivalent to
the following statement:
access-log-format "%h %l %u %t \"%r\" %>s %b"; |
It was chosen so as to be compatible with Apache access logs and
be easily parsable by existing log analyzing tools, such as
webalizer.
Extending this format string with the client name produces a log format similar to Apache ‘combined log’:
access-log-format "%h %l %u %t \"%r\" %>s %b \"\" \"%C\""; |
The settings in this subsection configure basic behavior of the DICT daemon.
Display the string in the textual part of the initial server reply.
When connection is established, the server sends an initial reply to the client, that looks like in the example below:
220 Trurl.gnu.org.ua <auth.mime> <520.1212912026@Trurl.gnu.org.ua> |
See section 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
initial-banner-text to append any additional information
there. Note, that string may not contain newlines. For
example:
initial-banner-text "Please authenticate yourself,"; |
This statement produces the following initial reply (split over two lines for readability):
220 Trurl.gnu.org.ua Please authenticate yourself, <auth.mime> <520.1212912026@Trurl.gnu.org.ua> |
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 ‘220’ code (see above) and may also be displayed in the access log file using ‘%v’ escape (see section Access Log).
Set server description to be shown in reply to SHOW SERVER
(see section SHOW SERVER) command.
The first line of the reply, after the usual ‘114’ response line,
shows the name of host where the server is running. If the settings
of show-sys-info (see section show-sys-info) allow, some
additional information about the system is printed.
The lines that follow are taken from the server-info
directive. It is common to specify string using
“here-document” syntax (see here-document), e.g.:
server-info <<EOT Welcome to the FOO dictionary service. Contact <dict@foo.org> if you have questions or suggestions. EOT; |
Set the text to be displayed in reply to the HELP command.
The default reply to HELP command displays a list of commands understood by the server with a short description of each.
You can use help-text directive to append arbitrary
text to that output, provided that you begin string with a
plus sign, e.g.:
help-text <<-EOT + The commands beginning with an X are extensions. EOT; |
If string begins with any character, except ‘+’, it will replace the default help output. For example:
help-text <<-EOT There is no help. See RFC 2229 for detailed information. EOT; |
Set the name of the default matching strategy (see section The MATCH Command). By default, Levenshtein matching is used, which is equivalent to
default-strategy lev; |
Capabilities are certain server features that can be enabled or disabled at the system administrator's will.
Request additional capabilities from list.
The argument to capability directive must contain names
of existing dicod capabilities. These are listed in the
following table:
The AUTH command is supported. See section Authentication.
The OPTION MIME command is supported. Notice that
RFC 2229 requires all servers to support that command, so
you should always specify this capability.
The XVERSION command is supported. It is a GNU extension that
displays the dicod implementation and version number.
See section XVERSION.
The XLEV command is supported. This command allows to set and
query maximal Levenshtein distance for lev matching strategy.
See section strategy. See section XLEV.
Capabilities set using the capability directive are
displayed in the initial server reply (see initial reply), and
appropriate entries are added to the HELP command output.
A 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 dicod can load
at run time.
A handler is an instance of a database module loaded by
dicod and configured for a specific database or a set of
databases.
Database handlers are defined using the following block statement:
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 handler statement is a block statement. The only
sub-statement allowed within it is command statement:
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 initialization function (see dico_init).
For example:
load-module dict {
command "dictorg dbdir=/var/dicodb";
}
|
This statement defines a handler named ‘dict’, which loads the module ‘dictorg’ and passes its initialization function a single argument, ‘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.
A module load path is an internal list of directories which
dicod scans in order to find a loadable file name specified
in command statement of a load-module block. By default the
order of search is as follows:
module-load-path directive (see below).
LTDL_LIBRARY_PATH.
LD_LIBRARY_PATH.
The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be a
colon-separated list of absolute directories, for example,
‘/usr/lib/mypkg:/lib/foo’.
In any of these directories, dicod first attempts to find and
load the given filename. If this fails, it tries to append the
following suffixes to it:
This directive adds the directories listed in its argument to the module load path. Example:
module-load-path (/usr/lib/dico,/usr/local/dico/lib); |
Dictionary databases are defined using database block
statement.
Define a dictionary database. At least two sub-statements must be
defined for each database: name and handler.
Set the name of this database (a single word). This name will be used to identify this database in DICT commands.
Specify the name of a handler for this database and any arguments for
it. This handler must be previously defined using load-module
statement (see section Database Modules and Handlers).
For example, the following fragment defines a database named
‘en-de’, which is handled by ‘dictord’ handler. The handler
is passed one argument, database=en-de:
database {
name "en-de";
handler "dictorg database=en-de";
}
|
More directives are available to fine-tune the database.
Supply a short description, to be shown in reply to SHOW DB
command. The 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 description directive is specified, its value
takes precedence over description string retrieved from the database
itself.
See section SHOW DB, for a description of SHOW DB command.
Supply a full description of the database. This description is shown
in reply to SHOW INFO (see section SHOW INFO) command. The
string is usually a multi-line text, so it is common to use
here-document syntax (see here-document), e.g.:
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; |
Use this statement if the database itself does not supply a full description, or if its full description is malformed.
As with description, the value of info takes precedence
over info strings retrieved from the database.
The following two directives control the content type and transfer
encoding used when formatting replies from this database if
OPTION MIME (see section OPTION MIME) is in effect:
Set the content type of the reply. E.g.:
directory {
name "foo";
handler "dictorg";
content-type "text/html";
...
}
|
Set transfer encoding to use when sending MIME replies for this database. Allowed values for enum are:
Use BASE64 encoding.
Use quoted-printable encoding.
A property called database visibility is associated with each
dictionary database. It determines whether the database appears in
the output of 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 visibility ACLs.
In general, the visibility of a database is controlled by two access control lists: global visibility ACL and database visibility ACL. The latter takes precedence over the former.
Both ACLs are defined using visibility-acl statement:
Set name of an ACL controlling database visibility. If used
in global scope, this statement sets global visibility ACL.
If used within a database block, it sets visibility
ACL for that particular database.
Consider the following example:
acl glob-vis {
allow authenticated;
deny all;
}
acl local-nets {
allow from (192.168.10.0/24, /tmp/dicod.sock);
}
visibility-acl glob-vis;
database {
name "terms";
visibility-acl local-nets;
}
|
In this configuration, the ‘terms’ database is visible to everybody coming from the ‘192.168.10.0/24’ network and from the UNIX socket ‘/tmp/dicod.sock’, without authorization. It is not visible to users coming from elsewhere, unless they authenticate themselves.
Default search is a MATCH request with ‘*’ or
‘!’ as database argument (see section The MATCH Command). 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 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.
Restrict the use of strategy name in default searches.
The statements define conditions the 4th argument of a
MATCH command must match in order to deny the request. The
following statements are defined:
Unconditionally deny this strategy in default searches.
Deny this strategy if the search word matches one of the words from list.
Deny if length of the search word is less than number.
Deny if length of the search word is less than or equal to number.
Deny if length of the search word is greater than number.
Deny if length of the search word is greater than or equal to number.
Deny if length of the search word is equal to number.
Deny if length of the search word is not equal to number.
For example, the following statement denies the use of ‘prefix’ strategy in default searches if its argument is an empty string:
strategy prefix {
deny-length-eq 0;
}
|
If the dicod daemon is configured this way, it will always return
a ‘552’ reply on commands MATCH * prefix "" or MATCH
! prefix "". However, use of empty prefix on a concrete database, as
in MATCH eng-deu prefix "", will still be allowed.
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 timing configuration
directive:
Provide timing information after successful completion of an
operation. This information is displayed after the following
requests: MATCH, DEFINE, and QUIT. It consists
of the following parts:
[d/m/c = nd/nm/nc RTr UTu STs] |
where:
Number of processed define requests. It is ‘0’ after a
MATCH request.
Number of processed match requests. It is ‘0’ after a
DEFINE request.
Number of comparisons made. This value may be inaccurate if the underlying database module is not able to count comparisons.
Real time spent serving the request.
Time in user space spent serving the request.
Time in kernel space spent serving the request.
An example of a server reply with timing information follows:
250 Command complete [d/m/c = 0/63/107265 2.293r 1.120u 0.010s] |
You can also add timing information to your access log files, see %T.
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 alias configuration file
statement:
Create a new alias.
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
d which is equivalent to DEFINE *:
alias d DEFINE "*"; |
Aliases may be recursive, i.e. the first word of command may refer to another alias. For example:
alias d DEFINE; alias da d "*"; |
This configuration will produce the following expansion:
da word ⇒ DEFINE * word |
To prevent endless loops, recursive expansion is stopped if the first word of the replacement text is identical to an alias expanded earlier.
Before parsing configuration file, dicod preprocesses
it. The built-in preprocessor handles only file inclusion
and #line statements (see section Pragmatic Comments), while the
rest of traditional preprocessing facilities, such as macro expansion,
is supported via m4, which is used as an external preprocessor.
The detailed description of m4 facilities lies far beyond
the scope of this document. You will find a complete user manual in
http://www.gnu.org/software/m4/manual.
For the rest of this subsection we assume the reader is sufficiently
acquainted with m4 macro processor.
The external preprocessor is invoked with ‘-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 ‘pp-setup’ file, located in ‘$prefix/share/dico/version/include’ directory (where version means the version of GNU Dico package).
The default ‘pp-setup’ file renames all m4 built-in
macro names so they all start with the prefix ‘m4_’. This
is similar to GNU m4 ‘--prefix-builtin’ options, but has an
advantage that it works with non-GNU m4 implementations as
well.
As an example of how the use of preprocessor may improve
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:
# defdb(NAME[, DESCR]) # Produce a standard definition for a database NAME. # If 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";') } ') |
It takes two arguments. The first one, NAME defines the dictionary
name visible in the output of 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:
defdb(eng-swa) defdb(swa-eng) defdb(afr-eng, Afrikaans-English Dictionary) defdb(eng-afr, English-Afrikaans Dictionary) |
This section summarizes dicod command line options.
Read this configuration file instead of the default ‘$sysconfdir/dicod.conf’. See section Configuration.
Operate in foreground. See section Daemon Operation Mode.
Output diagnostic to stderr. See section –stderr.
After successful startup, output any diagnostic to syslog. This is the default.
Preprocess configuration file and exit. See section Using Preprocessor to Improve the Configuration..
Use prog as a preprocessor for configuration file. The default
preprocessor command line is m4 -s, unless overridden while
configuring the package (see section Default Preprocessor).
See section Using Preprocessor to Improve the Configuration..
Do not use external preprocessor. See section Using Preprocessor to Improve the Configuration..
Add the directory dir to the list of directories to be searched for preprocessor include files. See section Using Preprocessor to Improve the Configuration..
In daemon mode, process connections in the main process, without starting subprocesses for each connection (see section Daemon Operation Mode). This means that the daemon is able to serve only one client at a time. The ‘--single-process’ option is provided for debugging purposes only. Never use it in production environment.
Enable session transcript. This instructs dicod to log
all commands it receives and all responses it sends during the
session. Transcript is logged via the default logging channel
(see section Logging and Debugging). If logging via syslog, the
‘debug’ priority is used.
See also Session Transcript, for a description of the similar
mode in dico, the client program.
Disable transcript mode. This is the default. Use this option if you wish to temporarly disable transcript mode, enabled in the configuration file (see section transcript).
Run in inetd mode. See section Inetd Operation Mode.
Set debug verbosity level. The level argument is an integer ranging from ‘0’ (no debugging) to ‘100’ (maximum debugging information).
Include source line information in the debugging output.
Trace parsing of the config file. The option is provided for debugging purposes.
Trace config file lexer. The option is provided for debugging purposes.
Show configuration file summary. See section Configuration.
Check configuration file syntax and exit with code ‘0’ if it is OK, or with ‘1’ if there are errors. See section Configuration.
Display a short command line option summary and exit.
List all available command line options and exit.
Print program version and exit.
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 ‘$prefix/lib/dico’. Modules are configurable on per-module (see section command) and per-database (see section handler basis.
GNU Dico version 2.0 is shipped with the following modules: ‘Outline’, ‘Dictorg’, ‘Guile’, and ‘Python’. The ‘Outline’ module handles databases written in Emacs Outline format. It is useful for small databases. The ‘Dictorg’ module handles databases in format designed by DICT development group. The most existing free databases are written in this format. Finally, the ‘Guile’ and ‘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.
outline module. The outline module supports databases written in
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.
The outline mode is described in Outline Mode: (emacs)Outline Mode section `Outline Mode' in The Emacs Editor. In short it is a usual plain text file, containing header lines and 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.
The outline dictionary must have at least a chapter named
‘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
‘Description’ chapter gives a short description to be displayed
on SHOW DB command, and the ‘Info’ chapter supplies a full
database description for SHOW INFO output. Both chapters are
optional.
All three reserved chapter names are case-insensitive.
To summarize, the structure of an outline database is:
* Description
line
* Info
text
* Dictionary
** line
text
[any number of entries follows]
|
As an example of outline format, the GNU Dico package includes Ambrose Bierce's Devil's Dictionary in this format, see ‘tests/devils.out’.
Outline module initialization does not require any command line
parameters, specifying command "outline"; is enough. To
declare a database, supply its full file name to handler
directive, as shown in the example below:
load-module outline {
command "outline";
}
database {
name "devdict";
handler "outline /var/db/devils.out";
}
|
dictorg module. The dictorg module supports dictionaries in the format
designed by DICT development group
(http://dict.org). Lots of free dictionaries in this format
are available from FreeDict project.
A dictionary in this format consists of two files: a dictionary database file, named ‘name.dict’ or ‘name.dict.dz’ (a compressed form), and an index file, which lists article headwords and corresponding offsets in the database. The index file is named ‘name.index’. The common part of these two file names, name, is called the base name for that dictionary.
An instance of the dictorg module is created using the
following statement:
load-module inst-name {
command "dictorg [options]";
}
|
where square brackets denote optional part. Valid options are the following:
Look for databases in directory dir.
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 ‘00-database-’. By
default they are exempt from database look-ups and cannot be retrieved
using MATCH or DEFINE command.
Using ‘show-dictorg-entries’ removes this limitation and makes these entries behave as other database entries.
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 ‘eng-swa’ database from FreeDict requires this option.
Using sort may considerably slow down initial database loading.
Remove trailing whitespace from dictionary headwords at start up. This might be necessary for some databases.
The values set via these options become defaults for all databases using this module instance, unless overridden in their declarations.
A database that uses this module must be declared as follows:
database {
handler "inst-name database=file [options]";
...
}
|
where inst-name is the instance name used in the load-module
declaration above.
The database argument specifies the base name of the
database. Unless file begins with a slash, the value of
dbdir initialization option is prepended to it. If
dbdir is not given and file does not begin with a slash,
an error is signalled.
The options above are the same options as described in
initialization procedure: show-dictorg-entries, sort,
and trim-ws. If used, they override initialization settings for
that particular database. Forms prefixed with ‘no’ may be used
to disable the corresponding option for this database. For example,
notrim-ws cancels the effect of trim-ws used when
initializing the module instance.
guile module. Guile is an acronym for 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 (r5rs)Top section `Top' in Revised(5) Report on the Algorithmic Language Scheme. For a detailed description of Guile and its features, see (guile)Top section `Overview' in The Guile Reference Manual.
The 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:
load-module mod-name {
command "guile [options]"
" init-script=‘script’"
" init-args=args"
" init-fun=function";
}
|
The init-script parameter specifies the name of a Scheme
source file that must be loaded in order to initialize the module.
The init-args parameter supplies additional arguments to the
module. They will be accessible to the ‘script’ via
command-line function. This parameter is optional.
The init-fun parameter specifies the name of a function that
will be invoked to perform the initialization of the module and of
particular databases. See section Guile Initialization, for a description
of initialization sequence. Optional arguments, options, are:
debugEnable Guile debugging and stack traces.
nodebugDisable Guile debugging and stack traces (default).
load-path=pathAppend directories from path to the list of directories which should be searched for Scheme modules and libraries. The path must be a list of directory names, separated by colons.
This option modifies the value of Guile's %load-path
variable.
See the section Configuration and Installation in the Guile Reference Manual.
Guile databases are declared using the following syntax:
database {
name "dbname";
handler "mod-name [options] cmdline";
}
|
where:
gives the name for this database,
is the name given to Guile module in load-module statement (see
above),
Options, that allow to override global settings given in the
load-module statement. The following options are understood:
init-script, init-args, and init-fun. Their
meaning is the same as for load-module statement (see above),
except that they affect only this particular database.
is the command line that will be passed to the Guile
open-db callback function (see open-db).
A database handled by guile module is associated with a
virtual function table. This table is an association list, that
supplies to the module the Scheme call-back functions implemented to
perform particular tasks on that database. In this association list,
the car of each element contains the name of a function, and
its cdr gives the corresponding function. The defined function
names and their semantics are described in the following table:
Open the database.
Close the database.
Return a short description of the database.
Return a full information about the database.
Define a word.
Look up a word in the database.
Output a search result.
Return number of entries in the result.
For example, the following is a valid virtual function table:
(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))
|
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 Guile API.
The following configuration statement causes loading and
initialization of the guile module:
load-module mod-name {
command "guile init-script=‘script’"
" init-fun=function";
}
|
Upon module initialization stage, the module attempts to load the
file named ‘script’. The file is loaded using
primitive-load call (see primitive-load: (guile)Loading section `Loading' in The Guile Reference Manual, i.e. the load paths are not
searched, so script must be an absolute path name. The
init-fun parameter supplies the name of an 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:
(define (function arg) ...) |
This function is called several times. First of all, it is called after
script is loaded. This time it is given #f as its
argument, and its return value is saved as a global function table.
Then, it is called for each database statement that has
mod-name (used in load-module above) in its
handler keyword, e.g.:
database {
name db-name;
handler "mod-name...";
}
|
This time, it is given 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:
(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)))
|
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.
Virtual table: (cons "open" open-db)
Open the database. The argument name contains database name as
given in name statement of database block
(see section Databases). Optional argument args is a list of
command line parameters obtained from cmdline in handler
statement (see guile-cmdline). For example, if the configuration
file contained:
database {
name "foo";
handler "guile db=file 1 no";
}
|
then the open-db callback will be called as:
(open-db "foo" '("db=file" "1" "no"))
|
The open-db callback returns a database handle, i.e. an
opaque structure that is used to identify this database, and that
keeps its internal state. This value, hereinafter named dbh,
will be passed to another callback functions that need to access the
database.
The return value #f or '() indicates an error.
Virtual Table: (cons "close" close-db)
Close the database. This function is called during the cleanup
procedure, before termination of dicod. The argument
dbh is a database handle returned by open-db.
The return value from close-db is ignored. To communicate
errors to the daemon, throw an exception.
Virtual Table: (cons "descr" descr)
Return a short textual description of the database, for use in
SHOW DB output. If there is no description, return #f
or '().
The argument dbh is a database handle returned by
open-db.
This callback is optional. If it is not defined, or if it returns
#f ('()), the text from description statement
is used (see section description). Otherwise, if no
description statement is present, empty string is used.
Virtual Table: (cons "info" info)
Return a verbose, eventually multi-line, textual description of the
database, for use in SHOW INFO output. If there is no
description, return #f or '().
The argument dbh is a database handle returned by open-db.
This callback is optional. If it is not defined, or if it returns
#f ('()), the text from info statement
is used (see section info). If there is no info statement,
the string ‘No information available’ is used.
Database searches are a two-phase process. First, an appropriate
callback is called to do the search: define-word is called for
DEFINE searches and match-word is called for matches.
This callback returns an opaque entity, called result handle,
which is then passed to output callback, which is responsible
for outputting it.
Virtual Table: (cons "lang" lang)
Virtual Table: (cons "define" define-word)
Find definitions of word word in the database dbh. Return
a result handle. If nothing is found, return #f or '().
The argument dbh is a database handle returned by open-db.
Virtual Table: (cons "match" match-word)
Find all matches of word word from the database dbh, using
matching strategy strat. Return a result handle. If nothing is
found, return #f or '().
The argument dbh is a database handle returned by
open-db. Matching strategy strat is a special Scheme
object that can be accessed using a set of functions described below
(see section Dico Scheme Primitives).
Virtual Table: (cons "output" output)
Output nth result from the result set resh. The argument
resh is a result handle returned by define-word or
match-word callback.
The data must be output to the current output port, e.g. using
display or format primitives. If resh represents
a match result, the output must not be quoted or terminated by newlines.
Virtual Table: (cons "result-count" result-count)
Return the number of elements in the result set resh.
GNU Dico provides the following Scheme primitives, that access various
fields of the strat argument to match callback:
Return true if strat has a selector. .
Return true if key matches word as per strategy selector strat.
Return the name of strategy strat.
Return a textual description of the strategy strat.
Return true if strat is a default
strategy. See section default strategy.
Register a new strategy. If 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 (see section strategy).
The selector function must be declared as follows:
(define (fun key word) ...) |
It must return #t if key matches word, and
#f otherwise.
In this subsection we will show how to build a simple dicod module
written in Scheme. The source code of this module, called
‘example.scm’ and a short database for it, ‘example.db’, are
shipped with the distribution in the directory ‘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 car
contains the headword, and cdr contains the corresponding
dictionary article. Following is an example of such a database:
("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"))
|
We wish to declare such databases in ‘dicod.conf’ the following way:
database {
name "numerals";
handler "guile example.db";
}
|
Thus, the rest argument to ‘open-db’ callback will be
‘("guile" "example.db")’ (see open-db). Given this, we may
write the callback as follows:
(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))))
|
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:
(define-syntax db:get
(syntax-rules (info descr name corpus)
((db:get dbh name) ;; Return the name of the database.
(list-ref dbh 0))
((db:get dbh descr) ;; Return the desctiption.
(list-ref dbh 1))
((db:get dbh info) ;; Return the info string.
(list-ref dbh 2))
((db:get dbh corpus) ;; Return the word list.
(list-tail dbh 3))))
|
Now, we can write ‘descr’ and ‘info’ callbacks:
(define (descr dbh) (db:get dbh descr)) (define (info dbh) (db:get dbh info)) |
The two callbacks ‘define-word’ and ‘match-word’ provide
the core module functionality. Their results will be passed to
‘output’ and ‘result-count’ callbacks as a “result handler”
argument. In the spirit of Scheme, we make the result a list. Its
car is a boolean value: #t, if the result
comes from ‘define-word’ callback, and #f if it comes from
‘match-word’. The cdr of this list contains the list of
matches. For ‘define-word’, it is a list of conses copied from
the database word list, whereas for ‘match-word’, it is a list of
headwords.
The ‘define-word’ callback returns all list entries whose
cars contain the look up word. It uses mapcan
function, which is supposed to be defined elsewhere:
(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))))
|
The ‘match-word’ callback (see match-word) takes three arguments: a database handler dbh, a strategy descriptor strat, and a word word to look for. The result handle it returns contains a list of headwords from the database that match word in sense of strat. Thus, the behavior of ‘match-word’ depends on the strat. To implement this, let's define a list of directly supported strategies (see below for definitions of particular ‘match-’ functions):
(define strategy-list
(list (cons "exact" match-exact)
(cons "prefix" match-prefix)
(cons "suffix" match-suffix)))
|
The ‘match-word’ callback will then select an entry from
that list and call its cdr, e.g.:
(define (match-word dbh strat word)
(let ((sp (assoc (dico-strat-name strat) strategy-list)))
(let ((res (cond
(sp
((cdr sp) dbh strat word))
|
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:
((dico-strat-selector? strat)
(match-selector dbh strat word))
(else
(match-default dbh strat word)))))
|
To summarize, the ‘match-word’ callback is:
(define (match-word dbh strat word)
(let ((sp (assoc (dico-strat-name strat) strategy-list)))
(let ((res (cond
(sp
((cdr sp) dbh strat word))
((dico-strat-selector? strat)
(match-selector dbh strat word))
(else
(match-default dbh strat word)))))
(if res
(cons #f res)
#f))))
|
Now, let's create the ‘match-’ functions used in it. The ‘exact’ strategy is easiest to implement:
(define (match-exact dbh strat word)
(mapcan (lambda (elt)
(and (string-ci=? word (car elt))
(car elt)))
(db:get dbh corpus)))
|
The ‘prefix’ and ‘suffix’ strategies are implemented using
SRFI-13 (see (guile)SRFI-13 section `SRFI-13' in The Guile Reference Manual)
functions string-prefix-ci? and string-suffix-ci?, e.g.:
(define (match-prefix dbh strat word)
(mapcan (lambda (elt)
(and (string-prefix-ci? word (car elt))
(car elt)))
(db:get dbh corpus)))
|
Notice that whereas the ‘prefix’ strategy is defined by the server itself, the ‘suffix’ strategy is an extension, and should therefore be registered:
(dico-register-strat "suffix" "Match word suffixes") |
The match-selector function is pretty similar to its
siblings, except that it uses dico-strat-select?
(see section dico-strat-select? to select the
matching elements:
(define (match-selector dbh strat word)
(mapcan (lambda (elt)
(and (dico-strat-select? strat (car elt) word)
(car elt)))
(db:get dbh corpus)))
|
Finally, the match-default may be a variable that refers to
the default matching strategy for this module, e.g.:
(define match-default match-prefix) |
The two callbacks left to define are ‘result-count’ and
‘output’. The first of them simply returns the number of
elements in cdr of the result:
(define (result-count rh) (length (cdr rh))) |
The behavior of ‘output’ depends on whether the result is produced by ‘define-word’ or by ‘match-word’.
(define (output rh n)
(if (car rh)
;; Result comes from DEFINE command.
(let ((res (list-ref (cdr rh) n)))
(display (car res))
(newline)
(display (cdr res)))
;; Result comes from MATCH command.
(display (list-ref (cdr rh) n))))
|
Finally, the callbacks are made known to dicod by the
module initialization function:
(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)))
|
Notice, that in this implementation ‘close-db’ callback was not needed.
python module. (This message will disappear, once this node revised.)
(This message will disappear, once this node revised.)
(This message will disappear, once this node revised.)
Interface version being used. It is recommended to use the macro
DICO_MODULE_VERSION, which keeps the version number of the
current interface.
Additional capabilities. This member is reserved for future use (as
of GNU Dico version 2.0. Use DICO_CAPA_DEFAULT to
initialize it.
This callback is called right after loading the module. It is responsible for module initialization. The arguments are:
Number of elements in argv.
The command line given by command configuration statement
(see section command), split into words. The element
argv[0] is the name of the module. The element
argv[argc] is ‘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.
This method is optional.
Initialize the database. This method is called as part of database
initialization routine at startup of dicod, after processing
dictionary configuration statement (see section Databases). Its
arguments are:
The name of the database, as given by the name statement.
Number of elements in argv.
The command line given by handler configuration statement
(see section handler). The array is ‘NULL’-terminated.
This method returns a database handle, an opaque structure
identifying the database. This handle is passed as the first argument
to other methods. On error, dico_init_db returns NULL.
Notice that this function is not required to actually open the
database, if the ‘open’ notion is supported by the underlying
mechanism. Another method, dico_open is responsible for that.
Reclaim any resources associated with database handle dh. This
method is called as part of exit cleanup routine, before the main
dicod process terminates.
Return ‘0’ on success, or any non-‘0’ value on failure.
Open the database identified by the handle dh. This method is called as a part of child process initialization routine.
Return ‘0’ on success, or any non-‘0’ value on failure.
The dico_open method is optional.
Close the database identified by the handle dh. This method is called as a part of child process termination routine.
Return ‘0’ on success, or any non-‘0’ value on failure.
The dico_close method is optional, but it must be defined, if
dico_open is defined.
Return a database information string for the database identified by
dh. This function is called on each SHOW INFO command,
unless an informational text for this database is supplied in the
configuration file (see section info). After use, the value
returned by dico_db_info is freed using system free
function.
This method is optional.
Return a short database description string for the database identified
by dh. This function is called on each SHOW DB command,
unless a description for this database is supplied in the
configuration file (see section descr). After use, the value
returned by dico_db_descr is freed using system free
function.
This method is optional.
Find in the database identified by dh matches for headword word, using matching strategy strat.
This method returns a result handle, an opaque pointer that can
then be used to display the obtained results. It returns NULL
if no matches were found.
Find definitions of headword word in the database identified by dh.
This method returns a result handle, an opaque pointer that can
then be used to display the obtained results. It returns NULL
if no matches were found.
The dico_output_result method outputs to stream str the
nth result from result set rp. The latter is a result
handle, obtained from a previous call to dico_match or
dico_define.
Return ‘0’ on success, or any non-‘0’ value on failure.
Return number of distinct elements in a result set, identified by
rp, which is a result handle, obtained from a previous call to
dico_match or dico_define.
Return number of comparisons performed when constructing the result set identified by rp.
This method is optional.
Free any resources used by the result set rp, which is a result
handle, obtained from a previous call to dico_match or
dico_define.
(This message will disappear, once this node revised.)
(This message will disappear, once this node revised.)
(This message will disappear, once this node revised.)
(This message will disappear, once this node revised.)
The dico program is a console-based utility for querying
dictionary servers. It has two operation modes. In single query
mode, the utility performs a query, displays its result and exits
immediately. This mode is entered if a word or a URL was
given in the command line. In 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.
The simplest way to use dico utility is to invoke it with
a word as an argument, e.g.:
$ dico entdeckung |
In the example above, the utility will search definitions of the word ‘entdeckung’ using its default server name and database. The default server name is read from the initialization file (see section Initialization File). If it is not present, a predefined value specified at configuration time (see section Default Server) is used. The default database is ‘!’, 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 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 URLs.
To connect to a particular dictionary server, use ‘--host’ option, for example:
$ dico --host dico.org entdeckung |
To search in a particular database, use ‘--database’ (‘-d’) option. For example, to display definitions from all databases:
$ dico --database '*' entdeckung |
Note single quotes around the asterisk.
To get a list of databases offered by the server, use ‘--dbs’ (‘-D’) option. In this case you may not give any non-option arguments. For example:
$ dico --dbs |
If you wish to get a list of matches, instead of definitions, use ‘--match’ (‘-m’) option. For example, the following invocation will display all matches from all the databases:
$ dico --database '*' --match entdeckung |
The match mode uses ‘.’ strategy by default (see section strategy), which means a server-dependent default strategy, which suits best for interactive spell checking. To select another strategy, use ‘--strategy’ (‘-s’) option.
If the remote server supports ‘xlev’ experimental capability (see section XLEV, you may use ‘--levdist’ (‘--levenshtein-distance’) option to set maximum Levenshtein distance, for example:
$ dico --levdist 2 --match entdeckung |
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 ‘--strats’ (‘-S’) option.
Another way to specify data for a query is by using URL, instead of a word to search, as in the example below:
$ dico dict://gnu.org.ua/d:entdeckung |
A DICT URL consists of the following parts:
dict://user;pass@host:port/d:word:database:n dict://user;pass@host:port/m:word:database:strat:n |
The ‘/d’ syntax requests the definition of word, whereas the ‘/m’ syntax queries for matches, and is similar to ‘--match’ option. Some or all of ‘user;pass@’, ‘:port’, database, strat, and and n may be omitted. The meaning of all URL parts and their default values (if appropriate) are explained in the table below:
User name to use in authentication. Similar to ‘--user’ option. If user is omitted and cannot be retrieved by other means, no authentication is performed. See section Autologin, for a detailed description of authentication procedure and sources which are used to obtain authentication credentials.
A shared key (password) for that user. This part is similar to ‘--key’ command line option.
For compatibility with other URLs, dico allows to
delimit user and pass with a colon (‘:’), instead of
semicolon.
If user is given, but pass is not, dico will ask
you to supply a password interactively (see section Autologin).
Host name or IP address of the server to query. Same as ‘--host’ command line option.
Port number or service name (from ‘/etc/services’). If it is not present, the default of 2628 is used.
Same as ‘--port’ command line option.
The word to look for.
The database to search in. If not given, ‘!’ is assumed.
Same as ‘--database’ command line option.
The matching strategy to use. If omitted, ‘.’ is assumed.
Same as ‘--strategy’ command line option.
Extract and display the nth 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.
Trailing colons may be omitted. For example, the following URLs might specify definitions or matches:
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::: |
If neither word nor URL nor any operation mode option were
given on the command line, 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 (see (readline)Command Line Editing section `Command Line Editing' in GNU Readline Library).
When in interactive mode, dico displays its prompt and
waits for you to enter a command. The default prompt is the name
of the program, followed by a ‘greater than’ sign and a single
space:
dico> _ |
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:
dico> man
From eng-swa, English-Swahili xFried/FreeDict Dictionary:
man <n.>
mwanamume
|
To match the word, instead of defining it, prefix it with a slash
much as you do in vi:
dico> /man From eng-swa, English-Swahili xFried/FreeDict Dictionary: 0) ``can'' 1) ``man'' 2) ``many'' 3) ``map'' 4) ``may'' 5) ``men'' |
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”:
dico> 5
From eng-swa, English-Swahili xFried/FreeDict Dictionary:
men <n.>
wanaume
|
Define and match are two basic actions. To discern from them, the
rest of dico commands begins with a command prefix, a
single punctuation character selected for this purpose. The default
command prefix is a dot, but it can be changed using the prefix
command (see section prefix).
We will discuss the dico commands in the following
subsections.
The 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:
dico> .open gnu.org.ua |
If any or both of its arguments are absent, the 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 ‘gnu.org.ua’ and the default port number is 2628. Both
values can be changed at configuration time, see Default Server
for a detailed instruction.
Note that you are not required to issue this command. If it is not
given, dico will attempt to connect using its default
settings before executing any command that requires a connection to
the server.
The close command closes the connection. It does not take
any arguments.
The 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:
dico> .database ! |
To change the database, give its name as an argument to the command:
dico> .database * |
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 TAB will show you a list of databases that begin with the characters you typed:
dico> .database enTAB en-pl-naut eng-afr eng-deu eng-swa |
If you supply enough characters to identify a single choice, TAB will automatically select it, for example typing it after
dico> .database en- |
completes the database name to:
dico> .database en-pl-naut |
The strategy command displays or changes the default strategy
name. As with database, the strategy completion is available
for this command.
dico> .strategy . dico> .strategy dlev |
If the remote server supports ‘xlev’ experimental capability
(see section XLEV), you can use 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.:
dico> .distance Reported Levenshtein distance: 1 No distance configured |
If used with a single numeric argument, it attempts to set the distance to the supplied value.
The ls command lists available strategies (see section SHOW STRAT):
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'' |
The ld command lists available databases (see section SHOW DB):
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'' |
The 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.
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 |
Each issued command is stored in a history list and assigned a
unique event number. When dico exits, it saves the
command history in a file named ‘.dico_history’ in your home
directory. Upon startup, it retrieves the history from this file, so
the history is preserved between sessions.
You can view the command history using the history command:
dico> .history 1) .open dict.org 2) entdeckung 3) /geschwindigkeit |
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 ‘!3’. The
command with this index will be inserted at the dico prompt
and you will be given a possibility to edit it. For a detailed
description of all history-editing commands, please refer to
(history)Using History Interactively section `Using History Interactively' in GNU History User Manual.
When any command produces an output that contains more lines than
there are rows on the terminal, dico attempts to use a
pager program to display it. The name (and arguments) of
the pager program is taken from the dico internal variable,
or, if it is not set, from the PAGER environment variable.
The dico pager setting can be set or listed using
pager command. When used without arguments, it displays
the current setting:
dico> .pager less (Pager set from environment) |
When used with a single argument, it sets the pager:
dico> .pager "less -R" |
The argument ‘-’ (a dash) disables pager.
The commands described in this subsection are designed mostly for
use in dico initialization file (see section Initialization File).
The 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 autologin command is
subject to tilde expansion, i.e. if it begins with ‘~/’,
this prefix is replaced by the name of the current user home
directory, followed by ‘/’. Similarly, a prefix
‘~login/’ is replaced by the home directory for user
login, followed by a slash.
See section Autologin, for a detailed discussion of the autologin feature.
The quiet command toggles the display of dico
startup banner. When started, 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.:
dico 2.0 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> |
If you find this output superfluous and useless, you can suppress it by setting
quiet yes |
in your initialization file.
Session transcript is a special mode, which displays raw DICT commands and answers as they are executed. It is useful for debugging purposes.
You enable session transcript by issuing the following command:
dico> .transcript yes
# or
dico> .transcript on
|
Starting from then, each DICT transaction will be displayed on standard error output, for example:
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 |
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:
dico> .transcript no
# or
dico> .transcript off
|
Finally, to query the current state of session transcript, issue this command without arguments:
dico> .transcript transcript is on |
The prefix command allows you to change command prefix:
dico> .prefix Command prefix is . dico> .prefix @ dico> @prefix Command prefix is @ |
The prompt command changes the dico command line
prompt. For example, to change it to ‘dico$’, followed by a single
space, type:
dico> .prompt "dico$ " dico$ _ |
Note the use of quotes to include the space character in the argument.
The help command displays a short command usage summary. For
convenience, a single question mark can be used instead of it:
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. ... |
The version command displays the package name and version
number, and the warranty command displays the copyright
statement.
Finally, the quit command leaves the dico shell. Typing
end-of-file character (C-d) has the same effect.
For convenience, this subsection lists all available 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.
open host portConnect to a DICT server. Both arguments are optional.
If any of them is absent, the value supplied with the previous
open command is used. If there was no previous value, the
default is used, i.e., ‘gnu.org.ua’ for host, and
2628 for port.
See section open.
closeClose the connection.
See section close.
autologin [file]Set or display autologin file name.
See section Autologin.
sasl [bool]Without argument, show whether the SASL authentication is enabled. With argument, enable or disable it, depending on the value of bool.
.
database [name]Set or display current database name.
See section database.
strategy [name]Set or display current strategy.
See section strategy.
distance [num]Set or query Levenshtein distance. This command takes effect only if the remote server supports ‘xlev’ experimental capability (see section XLEV).
See section distance.
lsList available matching strategies.
See section ls.
ldList all accessible databases.
See section ld.
info [db]Display information about database db, or the current database, if used without argument.
prefix [c]Set or display command prefix.
See section prefix.
transcript [bool]Set or display session transcript mode.
See section Session Transcript.
verbose [number]Set or display debugging verbosity level. .
prompt stringChange command line prompt.
See section prompt.
pager stringChange or display pager settings.
See section Pager.
historyDisplay command history.
See section History Commands.
helpDisplay short command usage summary.
See section help.
versionPrint program version.
See section version.
warrantyPrint copyright statement.
See section warranty.
quiet boolToggle display of dico welcome banner. This command can be
used only in initialization file.
See section quiet.
quitQuit the shell.
See section quit.
When you start dico, it automatically executes commands from its
initialization files (or init files, for short), normally
called ‘.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 dico commands, as
described in Interactive Mode, with the only difference that
no command prefix is used by default. The ‘#’ character
introduces a comment: any characters from (and including) ‘#’ up
to the newline character are ignored(3).
Init files are useful to change the defaults for your dico
invocation. Consider, for example, this init file:
# An example init file for |
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.
(This message will disappear, once this node revised.)
After connecting to a remote server, dico checks if it
announces ‘auth’ capability, and if so, it attempts to authenticate
to the remote server. To do so dico needs two parameters:
user name and password. These parameters can either be supplied using
different sources:
These three sources are consulted in that order, i.e., a user name supplied with ‘--user’ command line option takes precedence over the one found in an 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, dictd will ask the user to supply a password.
If it is not, authentication is aborted and connection with the server
is closed.
An autologin file is a plaintext file that contains
authentication information for various DICT servers. At
most two autologin files are consulted: first the session-specific
file, if it is supplied by autologin command (see section autologin) or by the ‘--autologin’ command line
option, next the default 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 ‘.netrc’ file
used by ftp utility.
Comments are introduced by a pound sign. Anything starting from ‘#’ up to the end of physical line is ignored.
Empty lines and comments are ignored.
Non-empty lines compose statements. Tokens in a statement may be separated by spaces, tabs, or newlines. A valid statement must begin with one of the following:
machine nameThis statement contains parameters for authenticating on machine name.
default This statement contains parameters for authenticating on any machine,
except those explicitly listed in machine statements. There
can be at most one default statement in autologin file. Its
exact location does not matter, it will always be matched after all
explicit machine statements.
During the lookup, dico searches the autologin file for a
machine statement whose name matches the remote server
name as given by ‘--host’ command line option, host part of an
URL (see section DICT URL), or an argument to the open
command (see section open). If it reaches the end of
file without having found such an entry, it uses the default
value, if available.
Once a matching entry is found, its subsequent tokens are analyzed. The following tokens are recognized:
login nameSupply user name for this server.
password stringSupply a password.
noauthDo not perform authentication on this machine.
saslEnable SASL authentication.
nosaslDisable SASL authentication.
mechanisms listDeclare acceptable SASL mechanisms. The list argument
is a comma-separated list of mechanism names, without intervening
whitespace. Multiple mechanisms may be given, in which case
the corresponding lists are concatenated.
service nameDeclare service name, for authentication methods that need it. If this token is omitted, the default service name ‘dico’ is used.
realm nameDeclare realm for authentication.
host nameSet host name for this machine. By default, it is determined automatically.
Consider the following autologin entry, for example:
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 |
When connecting to the server ‘a.net’, dico will attempt
usual APOP authentication as user ‘smith’ with password
‘guessme’. When connecting to the machine ‘b.net’, it will
use SASL authentication, using either GSSAPI or
DIGEST-MD5 mechanisms, realm name ‘example.net’,
service name ‘dico’ and the same user name and password, as for
‘a.net’.
The authentication mechanism is suppressed if the --noauth
option has been given in the command line, or a matching entry was
found in one of the autologin files, which contained the noauth
keyword.
This section contains a short summary of dico command line
options.
The following table summarizes the four existing ways of
dico invocation:
dico [options] wordConnect to the dictionary and define or match a word.
See section Dico Command Line Options.
dico [options] urlConnect to the dictionary and define or match a word, supplied in the url.
See section DICT URL.
dico [options] opmodeConnect to the dictionary and query the information required by opmode option, which is one of ‘--dbs’, ‘--strats’, ‘--serverhelp’, ‘--info’, or ‘--serverinfo’. See below (see Operation modes) for a description.
dico [options]Start interactive shell. see section Interactive Mode.
Connect to this server.
See section –host.
Specify port to connect to. The argument port can be either a port number or its symbolic service name, as listed in ‘/etc/services’.
Select a database to search. The name can be either a name of one of the databases offered by the server (as returned by ‘--dbs’ option), or one of the predefined database names: ‘!’ or ‘*’.
See section –database.
Set source address for TCP connections.
Match instead of define.
See section –match.
Select a strategy for matching. The argument is either a name of one of the matching strategies supported by server (as displayed by ‘--strats’ option) or a dot (‘.’) meaning a server-dependent default strategy.
This option implies ‘--match’.
See section –strategy.
Sets maximum Levenshtein distance. Allowed values of n are between 1 and 9 inclusively. This option has effect only if the remote server supports ‘xlev’ extension (see section XLEV).
See section –levdist.
Do not print the normal dico welcome banner when entering
interactive shell.
See section quiet.
Show available databases.
See section –dbs.
Show available search strategies.
See section –strats.
Show server help.
Show information about database dbname.
Show information about the server.
Disable authentication.
See section Autologin.
Enable SASL authentication. .
Disable SASL authentication. .
Set user name for authentication.
See section Autologin.
Set shared secret for authentication.
See section Autologin.
Set the name of autologin file to use.
See section Autologin.
Additional text for client command, instead of the default ‘dico 2.0’.
Enable session transcript. See section Session Transcript, for a description.
Increase debugging verbosity level.
Include time stamp in the debugging output.
Include source line information in the debugging output.
Display a short description of command line options.
Display a short usage message
Print program version.
Email bug reports to bug-dico@gnu.org or 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:
dicod
--version will do.
./configure in the source root directory of GNU Dico.
This appendix describes commands understood by Dico dictionary server. Provided examples follow the convention used in RFC documents: a text sent by the server is prefixed with ‘S’, whereas a text sent by the client is prefixed with ‘C’.
When connection is established, the server sends an initial reply to the client. This reply has the following format:
220 hostname text <capabilities> msg-id |
Its parts and their meaning are described in the following table:
The name of the host. It is determined automatically, unless set
using hostname configuration file statement (see hostname directive).
Arbitrary text, as set via initial-banner-text configuration
statement (see section initial-banner-text).
A comma-separated list of server capabilities. It is configured using
capability statement (see section Server Capabilities).
A unique identifier similar to the format specified in RFC822, except that spaces and quoted pairs are not allowed within it.
This identifier will be used by the client when formulating the
authentication string used in the AUTH command (see section The AUTH Command).
An example of initial reply follows:
220 Trurl.gnu.org.ua <auth.mime> <520.1212912026@Trurl.gnu.org.ua> |
The following are standard commands, defined in RFC2229.
The DEFINE command searches for definitions of a word.
Look up the word word in database db. If db is
‘!’, then all the databases will be searched until the word is
found, and all matches in that database will be returned. Similarly,
if db is ‘*’, then all the databases will be searched and
all matches in all databases will be returned. In these two cases,
the databases are searched in the same order as that returned by
SHOW DB command (see section SHOW DB).
If the word was not found, response code 552 is returned.
If the word is found, a response code 150 is sent, followed by the
number of definitions found. Then, for each definition a response
code 151 is returned, followed by the textual body of the definition.
In a 151 response, the first three space-delimited parameters give the
word looked for, the name and a short description of the database.
The latter two are the same as shown in the output from SHOW DB
command.
The textual body of each definition is terminated with a dot (‘.’) on a line alone. If any line in the definition begins with a dot, it is duplicated to avoid confusion with body terminator.
After all of the definitions have been sent, a status code 250 is
sent. If timing is set to ‘true’ in the configuration
file, this latter response also carries timing information.
See section Tuning, for more information about timing output.
Possible responses from DEFINE command are:
Example transaction:
C: DEFINE eng-swa man S: 150 1 definitions found: list follows S: 151 "man" eng-swa "English-Swahili xFried/FreeDict Dictionary" S: man <n.> S: S: mwanamume S: S: . S: 250 Command complete [d/m/c = 1/0/12 0.000r 0.000u 0.000s] |
The MATCH command searches for word in the database index.
The searching algorithm is called strategy. The following
strategies are supported by the server:
Match a word exactly (case-insensitive).
Match a word prefix (case-insensitive).
Match using SOUNDEX algorithm.
Match headwords within given Levenshtein distance. That distance,
called a Levenshtein threshold is by default 1. It can be
modified using the XLEV extension command (see section XLEV).
Match headwords within given Damerau-Levenshtein distance. That distance is the same as for the ‘lev’ strategy.
Match using POSIX 1003.2 (a.k.a ‘extended’) regular expressions.
Match using basic regular expressions.
The dictorg module (see section The dictorg module.) additionally provides the
following strategy:
Match word suffixes (case-insensitive).
Other modules may provide more matching strategies.
Match word in database using strategy. As with
DEFINE, the database can be ‘!’ or ‘*’
(See section The DEFINE Command, for a detailed description of these wildcards).
The strategy is either the name of a strategy to use, or
a dot (‘.’), meaning to use default strategy. The default
strategy is set using default-strategy configuration file
statement (see section default-strategy. Its default
value is ‘lev’, which means ‘use Levenshtein algorithm’ (see
above).
If no matches are found in any of the searched databases, then response code 552 will be returned. Otherwise, response code 152 will be returned followed by a list of matched words, one per line, in the form:
database word |
Thus, prepending a ‘DEFINE ’ to each such response, one obtains a
valid DEFINE command.
The textual body of the match list is terminated with a line containing only a dot character.
Following the list, response code 250 is sent, which includes
timing information, if timing directive is set in the
configuration file (see section Tuning).
Possible responses:
Examples:
C: MATCH * . "weather" S: 152 12 matches found: list follows C: eng-afr "feather" C: eng-afr "leather" C: eng-afr "weather" C: eng-deu "feather" C: eng-deu "heather" C: eng-deu "leather" C: eng-deu "weather" C: eng-deu "wether" C: eng-deu "wheather" C: devils "WEATHER" S: . S: 250 Command complete [d/m/c = 0/12/100677 0.489r 0.479u 0.007s] |
The SHOW command outputs various information about the server
and databases.
Display the list of currently accessible databases, one per line, in the form:
database description |
The list is terminated with is a dot (‘.’) on a line alone.
Possible responses:
Display the list of currently supported search strategies, one per line, in the form:
strategy description |
The list is terminated with is a dot (‘.’) on a line alone.
Possible responses:
Displays the information about the specified database. The information is a free-form text and is suitable for display to the user in the same manner as a definition. The textual body of the response is terminated with is a dot (‘.’) on a line alone.
Possible responses:
The textual body is retrieved from the info statement in the
configuration file (see section info), or, if it is not
specified, from the database itself, using dico_db_info
callback function (see dico_db_info). If neither source
returns anything, the string ‘No information available.’ is returned.
Return a server-specific information.
Response:
The information follows, terminated with a dot on a line alone.
The textual body returned by the SHOW SERVER command consists
of two parts. It begins with a line containing host name of the
server and, optionally an additional information about the daemon and
the system it runs on. The exact look and amount of information in
this line is controlled by show-sys-info configuration
statement (see section show-sys-info). This line is
followed by the text supplied with server-info configuration
statement (see section server-info).
The OPTION command allows to request optional features
on the remote server. Currently the only implemented subcommand is:
Requests that all text responses be prefaced by a MIME header (RFC2045) followed by a single blank line.
After this command is issued, the server begins each textual response with a MIME header. This header consists of ‘Content-type’ and ‘Content-transfer-encoding’ headers, as supplied by the corresponding configuration file statements for this database (See section content-type, see section content-transfer-encoding). Any or both of these headers may be missing.
The AUTH command allows client to authenticate itself to the
server. Depending on the server configuration, authenticated users
may get access to more databases (see section Database Visibility) or more
detailed server information (see section show-sys-info).
Authenticate client to the server using a username and password. The auth-string is computed as in the APOP protocol (RFC1939. Briefly, it is the MD5 checksum of the concatenation of the msg-id (see section Initial Reply) and the shared secret that is stored both on the server and client machines.
See section Authentication, for information on how to configure server for authenticating clients.
This command is supported only if ‘auth’ capability is requested in the configuration (see section auth).
Identify client to server. The info argument contains a string identifying the client program (e.g. its name and version number). This information can then be used in logging (see section %C).
Display cumulative timing information. This command returns a ‘210’ status code, followed by the timing information as described in Tuning, e.g.
C: STATUS S: 210 [d/m/c = 28/1045/119856 21.180r 10.360u 1.040s] |
The HELP command provides a short summary of commands that
are understood by the server. The response begins with a ‘113’
code, followed by textual body defined in help-text
configuration file statement (see section help-text),
which is terminated by a dot on a line by itself. A ‘250’
response code finishes the output. For example:
113 help text follows DEFINE database word -- look up word in database MATCH database strategy word -- match word in database SHOW DB -- list all accessible databases SHOW DATABASES -- list all accessible databases SHOW STRAT -- list available matching strategies SHOW STRATEGIES -- list available matching strategies SHOW INFO database -- provide database information SHOW SERVER -- provide site-specific information CLIENT info -- identify client to server STATUS -- display timing information HELP -- display this help information QUIT -- terminate connection . 250 Ok |
Terminate connection.
This command returns a response code 221, optionally followed by timing information (see section Tuning).
In addition to the standard commands, the Dico server also offers a set of experimental or extended commands.
This command displays the current inactivity timeout setting (see inactivity-timeout), and resets idle timer to 0. The timeout value is printed as the first word after a ‘110’ reply code, e.g.:
C: XIDLE S: 110 180 second(s) |
The value of ‘0’ means there are no timeout.
This command displays the daemon implementation and version number. It becomes available only if ‘xversion’ capability was requested in the configuration file (see section xversion).
C: XVERSION S: 110 dicod (dico 2.0) |
If param is the word ‘tell’, displays the current value of Levenshtein threshold. If param is a positive integer value, sets the Levenshtein threshold to this value.
This command becomes available only if ‘xlev’ capability was requested in the configuration file (see section xlev).
C: xlev tell S: 280 1 C: xlev 3 S: 250 ok - Levenshtein threshold set to 3 C: xlev tell S: 280 3 |
This appendix documents the time format specifications understood by
the ‘%t’ log format specifier (see section Access Log).
Essentially, it is a reproduction of the man page for GNU
strftime function.
Ordinary characters placed in the format string are reproduced without conversion. Conversion specifiers are introduced by a ‘%’ character, and are replaced as follows:
| %a | The abbreviated weekday name according to the current locale. |
| %A | The full weekday name according to the current locale. |
| %b | The abbreviated month name according to the current locale. |
| %B | The full month name according to the current locale. |
| %c | The preferred date and time representation for the current locale. |
| %C | The century number (year/100) as a 2-digit integer. |
| %d | The day of the month as a decimal number (range 01 to 31). |
| %D | Equivalent to ‘%m/%d/%y’. |
| %e | Like ‘%d’, the day of the month as a decimal number, but a leading zero is replaced by a space. |
| %E | Modifier: use alternative format, see below (see conversion specs). |
| %F | Equivalent to ‘%Y-%m-%d’ (the ISO 8601 date format). |
| %G | The ISO 8601 year with century as a decimal number. The 4-digit year corresponding to the ISO week number (see ‘%V’). This has the same format and value as ‘%y’, except that if the ISO week number belongs to the previous or next year, that year is used instead. |
| %g | Like ‘%G’, but without century, i.e., with a 2-digit year (00-99). |
| %h | Equivalent to ‘%b’. |
| %H | The hour as a decimal number using a 24-hour clock (range 00 to 23). |
| %I | The hour as a decimal number using a 12-hour clock (range 01 to 12). |
| %j | The day of the year as a decimal number (range 001 to 366). |
| %k | The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also ‘%H’.) |
| %l | The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also ‘%I’.) |
| %m | The month as a decimal number (range 01 to 12). |
| %M | The minute as a decimal number (range 00 to 59). |
| %n | A newline character. |
| %O | Modifier: use alternative format, see below (see conversion specs). |
| %p | Either ‘AM’ or ‘PM’ according to the given time value, or the corresponding strings for the current locale. Noon is treated as ‘pm’ and midnight as ‘am’. |
| %P | Like ‘%p’ but in lowercase: ‘am’ or ‘pm’ or a corresponding string for the current locale. |
| %r | The time in ‘a.m.’ or ‘p.m.’ notation. In the POSIX locale this is equivalent to ‘%I:%M:%S %p’. |
| %R | The time in 24-hour notation (‘%H:%M’). For a version including the seconds, see ‘%T’ below. |
| %s | The number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC. |
| %S | The second as a decimal number (range 00 to 61). |
| %t | A tab character. |
| %T | The time in 24-hour notation (‘%H:%M:%S’). |
| %u | The day of the week as a decimal, range 1 to 7, Monday being 1. See also ‘%w’. |
| %U | The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also ‘%V’ and ‘%W’. |
| %V | The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. See also ‘%U’ and ‘%W’. |
| %w | The day of the week as a decimal, range 0 to 6, Sunday being 0. See also ‘%u’. |
| %W | The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01. |
| %x | The preferred date representation for the current locale without the time. |
| %X | The preferred time representation for the current locale without the date. |
| %y | The year as a decimal number without a century (range 00 to 99). |
| %Y | The year as a decimal number including the century. |
| %z | The time-zone as hour offset from GMT. Required to emit RFC822-conformant dates (using ‘%a, %d %b %Y %H:%M:%S %z’) |
| %Z | The time zone or name or abbreviation. |
| %+ | The date and time in date(1) format. |
| %% | A literal ‘%’ character. |
Some conversion specifiers can be modified by preceding them by the ‘E’ or ‘O’ modifier to indicate that an alternative format should be used. If the alternative format or specification does not exist for the current locale, the behaviour will be as if the unmodified conversion specification were used. The Single Unix Specification mentions ‘%Ec’, ‘%EC’, ‘%Ex’, ‘%EX’, ‘%Ry’, ‘%EY’, ‘%Od’, ‘%Oe’, ‘%OH’, ‘%OI’, ‘%Om’, ‘%OM’, ‘%OS’, ‘%Ou’, ‘%OU’, ‘%OV’, ‘%Ow’, ‘%OW’, ‘%Oy’, where the effect of the ‘O’ modifier is to use alternative numeric symbols (say, roman numerals), and that of the ‘E’ modifier is to use a locale-dependent alternative representation.
(This message will disappear, once this node revised.)
struct dico_strategy {
char *name;
char *descr;
dico_select_t sel;
void *closure;
int is_default;
};
|
(This message will disappear, once this node revised.)
(This message will disappear, once this node revised.)
typedef int (*dico_list_iterator_t)(void *item, void *data); |
typedef int (*dico_list_comp_t)(const void *, const void *); |
(This message will disappear, once this node revised.)
struct dico_assoc {
char *key;
char *value;
};
|
(This message will disappear, once this node revised.)
typedef int (*filter_xcode_t) (const char *, size_t,
char *, size_t, size_t *, size_t, size_t *);
|
size_t *pnbytes, size_t line_max, size_t *pline_len)
(This message will disappear, once this node revised.)
DICO_PARSEOPT_PARSE_ARGV0DICO_PARSEOPT_PERMUTEdico_opt_nulldico_opt_booldico_opt_bitmaskdico_opt_bitmask_revdico_opt_longdico_opt_stringdico_opt_enumdico_opt_constdico_opt_const_stringstruct dico_option {
const char *name;
size_t len;
enum dico_opt_type type;
void *data;
union {
long value;
const char **enumstr;
} v;
int (*func) (struct dico_option *, const char *);
};
|
(This message will disappear, once this node revised.)
DICO_STREAM_READ DICO_STREAM_WRITE DICO_STREAM_SEEKdico_buffer_nonedico_buffer_linedico_buffer_fullDICO_SEEK_SETDICO_SEEK_CURDICO_SEEK_END(This message will disappear, once this node revised.)
#define DICO_REQUEST_DEFINE 0
#define DICO_REQUEST_MATCH 1
struct dico_request {
int type;
char *word;
char *database;
char *strategy;
unsigned long n;
};
struct dico_url {
char *string;
char *proto;
char *host;
int port;
char *path;
char *user;
char *passwd;
dico_assoc_list_t args;
struct dico_request req;
};
|
(This message will disappear, once this node revised.)
struct utf8_iterator {
char *string;
char *curptr;
unsigned curwidth;
};
|
DICO_LEV_NORMDICO_LEV_DAMERAU5
(This message will disappear, once this node revised.)
(This message will disappear, once this node revised.)
struct xlat_tab {
char *string;
int num;
};
|
XLAT_ICASEVersion 1.3, 3 November 2008
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. http://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. |
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. |
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
|
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
This is a general index of all issues discussed in this manual.
| Jump to: | #
%
-
.
/
A B C D E F G H I L M N O P Q R S T U V W X |
|---|
| Jump to: | #
%
-
.
/
A B C D E F G H I L M N O P Q R S T U V W X |
|---|
http://www.gnu.org/software/m4
http://www.gnu.org/software/guile.
The same holds true for interactive mode as well, but you will hardly need comments on a terminal.
This document was generated by Sergey Poznyakoff on October, 29 2009 using texi2html 1.78.
The buttons in the navigation panels have the following meaning:
| Button | Name | Go to | From 1.2.3 go to |
|---|---|---|---|
 |
Back | Previous section in reading order | 1.2.2 |
 |
Forward | Next section in reading order | 1.2.4 |
 |
FastBack | Beginning of this chapter or previous chapter | 1 |
 |
Up | Up section | 1.2 |
 |
FastForward | Next chapter | 2 |
 |
Contents | Table of contents | |
 |
Index | Index | |
| [ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.