De'die' a` la me'moire de Jacques Brel. Short Contents ************** Dico Manual Preface 1 Introduction to GNU Dico 2 Building the Package 3 The `dicod' daemon. 4 Modules 5 Dico Module Interface 6 Dico -- a client program. 7 How to Report a Bug Appendix A Dictionary Server Protocol Appendix B Time and Date Formats Appendix C The Libdico Library Appendix D GNU Free Documentation License Concept Index Table of Contents ***************** Dico Manual Preface 1 Introduction to GNU Dico 2 Building the Package 2.1 Default Preprocessor 2.2 Default Server 2.3 Guile Support 2.4 Pyhton Support 2.5 Other Configure Settings 3 The `dicod' daemon. 3.1 Daemon Operation Mode 3.2 Inetd Operation Mode 3.3 Configuration 3.3.1 Configuration File Syntax 3.3.1.1 Comments 3.3.1.2 Pragmatic Comments 3.3.1.3 Statements 3.3.2 Server Settings 3.3.3 Authentication 3.3.3.1 Text Authentication Database 3.3.4 Access Control Lists 3.3.5 Security Settings 3.3.6 Logging and Debugging 3.3.7 Access Log 3.3.8 General Settings 3.3.9 Server Capabilities 3.3.10 Database Modules and Handlers 3.3.11 Databases 3.3.11.1 Database Visibility 3.3.12 Strategies and Default Searches 3.3.13 Tuning 3.3.14 Command Aliases 3.3.15 Using Preprocessor to Improve the Configuration. 3.4 Dicod Invocation 4 Modules 4.1 The `outline' module. 4.2 The `dictorg' module. 4.3 The `guile' module. 4.3.1 Virtual Functions 4.3.2 Guile Initialization 4.3.3 Guile API 4.3.4 Dico Scheme Primitives 4.3.5 Example Module 4.4 The `python' module. 5 Dico Module Interface 5.1 dico_database_module 5.2 Strategies 5.3 Output 5.4 Error Reporting 6 Dico -- a client program. 6.1 Single Query Mode 6.1.1 Dico Command Line Options 6.1.2 DICT URL 6.2 Interactive Mode 6.2.1 Server Commands 6.2.2 Database and Strategy 6.2.3 Informational Commands 6.2.4 History Commands 6.2.5 Pager 6.2.6 Program Settings 6.2.7 Session Transcript 6.2.8 Other Commands 6.2.9 Dico Command Summary 6.3 Initialization File 6.4 Autologin 6.5 Dico invocation 7 How to Report a Bug Appendix A Dictionary Server Protocol A.1 Initial Reply A.2 Standard Commands A.2.1 The DEFINE Command A.2.2 The MATCH Command A.2.3 The SHOW Command A.2.4 The OPTION Command A.2.5 The AUTH Command A.2.6 The CLIENT Command A.2.7 The STATUS Command A.2.8 The HELP Command A.2.9 The QUIT Command A.3 Extended Commands Appendix B Time and Date Formats Appendix C The Libdico Library C.1 Strategies C.2 argcv C.3 Lists C.4 Associative lists C.5 Diagnostics Functions C.6 Filter C.7 parseopt C.8 stream C.9 url C.10 UTF-8 C.11 util C.12 xlat Appendix D GNU Free Documentation License Concept Index Dico Manual *********** This edition of the `GNU Dico Manual', last updated 29 March 2009, documents Dico Version 2.0. Preface ******* _(This message will disappear, once this node revised.)_ 1 Introduction to GNU Dico ************************** 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: dictorg 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'). guile 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. python This module provides an interface to database modules written in Python (`http://www.python.org'). outline 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. 2 Building the Package ********************** 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. 2.1 Default Preprocessor ======================== The runtime configuration system uses `m4' to preprocess the configuration file (*note Preprocessor::, 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'. ---------- Footnotes ---------- (1) `http://www.gnu.org/software/m4' 2.2 Default Server ================== Unless given an explicit dictionary server, the client program `dico' attempts to connect the server . 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'. 2.3 Guile Support ================= The "GNU's Ubiquitous Intelligent Language for Extensions", or "Guile"(1) 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. ---------- Footnotes ---------- (1) `http://www.gnu.org/software/guile'. 2.4 Pyhton Support ================== 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. 2.5 Other Configure Settings ============================ 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. 3 The `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'. 3.1 Daemon Operation Mode ========================= The `daemon' mode is enabled by `mode daemon' statement in the configuration file (*note 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 (*note --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 (*note 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. 3.2 Inetd Operation Mode ======================== 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 (*note mode statement::) in configuration file, or by the `--inetd' command line option (*note --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 3.3 Configuration ================= 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 (*note --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' (*note Preprocessor::). 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'. 3.3.1 Configuration File Syntax ------------------------------- 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. 3.3.1.1 Comments ................ "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. 3.3.1.2 Pragmatic Comments .......................... Pragmatic comments are similar to usual comments, except that they cause some changes in the way the configuration is parsed. Pragmatic comments begin with a `#' sign and end with the next physical newline character. As of GNU Dico version 2.0, the following pragmatic comments are understood: `#include ' `#include FILE' Include 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: 1. `PREFIX/share/dico/2.0/include' 2. `PREFIX/share/dico/include' Where PREFIX is the installation prefix. New directories can be appended in front of it using `-I' (`--include-dir') command line option (*note --include-dir::). `#include_once ' `#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 *note Preprocessor::. 3.3.1.3 Statements .................. 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: number A number is a sequence of decimal digits. boolean A boolean value is one of the following: `yes', `true', `t' or `1', meaning "true", and `no', `false', `nil', `0' meaning "false". unquoted string An unquoted string may contain letters, digits, and any of the following characters: `_', `-', `.', `/', `:'. quoted string 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 "Here-document" is a special construct that allows to introduce strings of text containing embedded newlines. The `< <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. 3.3.7 Access Log ---------------- 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: -- Configuration: access-log-file STRING 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: -- Configuration: access-log-format STRING 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. %a Remote IP-address. %A Local IP-address. %B Size of response in bytes. %b Size of response in bytes in CLF format, i.e. a `-' rather than a `0' when no bytes are sent. %C Remote client (from `CLIENT' command (*note CLIENT::)). %D The time taken to serve the request, in microseconds. %d Request command verb in abbreviated form, suitable for use in URLs, i.e. `d' for `DEFINE', and `m' for `MATCH'. *Note urls::. %h Remote host. %H Request command verb (`DEFINE' or `MATCH'). %l Remote logname (from identd, if supplied). This will return a dash unless `identity-check' is set to true. *Note identity-check::. %m The search strategy. %p The canonical port of the server serving the request. %P The PID of the child that serviced the request. %q The database from the request. %r Full request. %{N}R The Nth token from the request (N is 0-based). %s Reply status. For multiple replies, the form `%s' returns the status of the first reply, while `%>s' returns that of the last reply. %t Time the request was received in the standard Apache format, e.g.: [04/Jun/2008:11:05:22 +0300] %{FORMAT}t The time, in the form given by FORMAT, which should be a valid `strftime' format. *Note Time and Date Formats::, for a detailed description. The standard `%t' format is equivalent to [%d/%b/%Y:%H:%M:%S %z] %T The time taken to serve the request, in seconds. %u Remote user from `AUTH' command. %v The host name of the server serving the request. *Note hostname directive::. %V Actual host name of the server (in case it was overridden in configuration). %W 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\""; 3.3.8 General Settings ---------------------- The settings in this subsection configure basic behavior of the DICT daemon. -- Configuration: initial-banner-text STRING 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 <520.1212912026@Trurl.gnu.org.ua> *Note 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, <520.1212912026@Trurl.gnu.org.ua> -- Configuration: hostname STRING Set the hostname. By default, the server determines it automatically. If, however, it makes a wrong guess, you can fix it using this directive. The server hostname is used, among others, in the initial reply after `220' code (see above) and may also be displayed in the access log file using `%v' escape (*note Access Log::). -- Configuration: server-info STRING Set server description to be shown in reply to `SHOW SERVER' (*note SHOW SERVER: SHOW.) 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' (*note show-sys-info: Security Settings.) 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 (*note here-document::), e.g.: server-info < if you have questions or suggestions. EOT; -- Configuration: help-text STRING 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; -- Configuration: default-strategy STRING Set the name of the default matching strategy (*note MATCH::). By default, Levenshtein matching is used, which is equivalent to default-strategy lev; 3.3.9 Server Capabilities ------------------------- "Capabilities" are certain server features that can be enabled or disabled at the system administrator's will. -- Configuration: capability LIST Request additional capabilities from LIST. The argument to `capability' directive must contain names of existing `dicod' capabilities. These are listed in the following table: auth The `AUTH' command is supported. *Note Authentication::. mime The `OPTION MIME' command is supported. Notice that RFC 2229 requires all servers to support that command, so you should always specify this capability. xversion The `XVERSION' command is supported. It is a GNU extension that displays the `dicod' implementation and version number. *Note XVERSION: Extended Commands. xlev The `XLEV' command is supported. This command allows to set and query maximal Levenshtein distance for `lev' matching strategy. *Note strategy: MATCH. *Note XLEV: Extended Commands. Capabilities set using the `capability' directive are displayed in the initial server reply (*note initial reply::), and appropriate entries are added to the `HELP' command output. 3.3.10 Database Modules and Handlers ------------------------------------ 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: -- Configuration: load-module STRING Create an instance of a database module. The argument specifies a unique name which will be used by subsequent parts of the configuration to refer to this handler. The `handler' statement is a block statement. The only sub-statement allowed within it is `command' statement: -- load-module config: command STRING Set the command line for this handler. It is similar to shell's command line: it consists of a name of database module, optionally followed by a whitespace-separated list of its arguments. Just as in shell, the name of the module specifies the disk file which should be loaded. Arguments are passed to the module "initialization function" (*note 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: 1. GNU Dico module directory: `$prefix/lib/dico'. 2. Additional search directories specified with the `module-load-path' directive (see below). 3. The value of the environment variable `LTDL_LIBRARY_PATH'. 4. The system dependent library search path (e.g. on Linux it is set by the contents of the file `/etc/ld.so.conf' and the value of the environment variable `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: 1. the libtool archive suffix `.la' 2. the suffix used for native dynamic libraries on the host platform, e.g., `.so', `.sl', etc. -- Configuration: module-load-path LIST 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); 3.3.11 Databases ---------------- Dictionary databases are defined using `database' block statement. -- Configuration: database { STATEMENTS } Define a dictionary database. At least two sub-statements must be defined for each database: `name' and `handler'. -- Database: name STRING Set the name of this database (a single word). This name will be used to identify this database in DICT commands. -- Database: handler STRING Specify the name of a handler for this database and any arguments for it. This handler must be previously defined using `load-module' statement (*note 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. -- Database: description STRING 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. *Note SHOW DB: SHOW, for a description of `SHOW DB' command. -- Database: info STRING Supply a full description of the database. This description is shown in reply to `SHOW INFO' (*note SHOW INFO: SHOW.) command. The STRING is usually a multi-line text, so it is common to use here-document syntax (*note 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' (*note OPTION MIME: OPTION.) is in effect: -- Database: content-type STRING Set the content type of the reply. E.g.: directory { name "foo"; handler "dictorg"; content-type "text/html"; ... } -- Database: content-transfer-encoding ENUM Set transfer encoding to use when sending MIME replies for this database. Allowed values for ENUM are: base64 Use BASE64 encoding. quoted-printable Use quoted-printable encoding. 3.3.11.1 Database Visibility ............................ 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: -- Configuration: visibility-acl ACL-NAME 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. 3.3.12 Strategies and Default Searches -------------------------------------- "Default search" is a `MATCH' request with `*' or `!' as database argument (*note MATCH::). The former means search in all available databases, the latter means search in all databases until a match is found. Default searches may be quite expensive and may cause considerable strain on the server. For example, the command `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. -- Configuration: strategy NAME { STATEMENTS } 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: -- Configuration: deny-all BOOL Unconditionally deny this strategy in default searches. -- Configuration: deny-word LIST Deny this strategy if the search word matches one of the words from LIST. -- Configuration: deny-length-lt NUMBER Deny if length of the search word is less than NUMBER. -- Configuration: deny-length-le NUMBER Deny if length of the search word is less than or equal to NUMBER. -- Configuration: deny-length-gt NUMBER Deny if length of the search word is greater than NUMBER. -- Configuration: deny-length-ge NUMBER Deny if length of the search word is greater than or equal to NUMBER. -- Configuration: deny-length-eq NUMBER Deny if length of the search word is equal to NUMBER. -- Configuration: deny-length-ne 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. 3.3.13 Tuning ------------- While tuning your server, it is often necessary to get timing information which shows how much time is spent serving certain requests. This can be achieved using `timing' configuration directive: -- Configuration: timing BOOLEAN 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: ND Number of processed define requests. It is `0' after a `MATCH' request. NM Number of processed match requests. It is `0' after a `DEFINE' request. NC Number of comparisons made. This value may be inaccurate if the underlying database module is not able to count comparisons. RT Real time spent serving the request. UT Time in user space spent serving the request. ST 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 *note %T: Access Log. 3.3.14 Command Aliases ---------------------- "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: -- Configuration: alias WORD COMMAND 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. 3.3.15 Using Preprocessor to Improve the Configuration. ------------------------------------------------------- Before parsing configuration file, `dicod' preprocesses it. The built-in preprocessor handles only file inclusion and `#line' statements (*note 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 *note GNU M4 manual: (m4)Top. 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) 3.4 Dicod Invocation ==================== This section summarizes `dicod' command line options. `--config=FILE' Read this configuration file instead of the default `$SYSCONFDIR/dicod.conf'. *Note Configuration::. `-f' `--foreground' Operate in foreground. *Note Daemon Mode::. `--stderr' Output diagnostic to stderr. *Note -stderr: Daemon Mode. `--syslog' After successful startup, output any diagnostic to syslog. This is the default. `-E' Preprocess configuration file and exit. *Note Preprocessor::. `--preprocessor=PROG' Use PROG as a preprocessor for configuration file. The default preprocessor command line is `m4 -s', unless overridden while configuring the package (*note Default Preprocessor::). *Note Preprocessor::. `--no-preprocessor' Do not use external preprocessor. *Note Preprocessor::. `-I DIR' `--include-dir=DIR' Add the directory DIR to the list of directories to be searched for preprocessor include files. *Note Preprocessor::. `-s' `--single-process' In daemon mode, process connections in the main process, without starting subprocesses for each connection (*note Daemon 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. `-T' `--transcript' 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 (*note Logging and Debugging::). If logging via syslog, the `debug' priority is used. See also *note Session Transcript::, for a description of the similar mode in `dico', the client program. `--no-transcript' Disable transcript mode. This is the default. Use this option if you wish to temporarly disable transcript mode, enabled in the configuration file (*note transcript: Logging and Debugging.). `-i' `--inetd' Run in inetd mode. *Note Inetd Mode::. `-x' `--debug=LEVEL' Set debug verbosity level. The LEVEL argument is an integer ranging from `0' (no debugging) to `100' (maximum debugging information). `--source-info' Include source line information in the debugging output. `--trace-grammar' Trace parsing of the config file. The option is provided for debugging purposes. `--trace-lex' Trace config file lexer. The option is provided for debugging purposes. `--config-help' Show configuration file summary. *Note Configuration::. `-t' `--lint' Check configuration file syntax and exit with code `0' if it is OK, or with `1' if there are errors. *Note Configuration::. `-h' `--help' Display a short command line option summary and exit. `--usage' List all available command line options and exit. `--version' Print program version and exit. 4 Modules ********* GNU Dico comes with a set of loadable modules for handling several database formats and for extending its functionality. Modules are binary loadable files, installed in `$PREFIX/lib/dico'. Modules are configurable on per-module (*note command: Handlers.) and per-database (*note handler: Databases. 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. 4.1 The `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 *note Outline Mode: (emacs)Outline Mode. 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"; } 4.2 The `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 (http://freedict.org). 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: `dbdir=DIR' Look for databases in directory DIR. `show-dictorg-entries' "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' 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. `trim-ws' 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. 4.3 The `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 *note Top: (r5rs)Top. For a detailed description of Guile and its features, see *note Overview: (guile)Top. 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. *Note Guile Initialization::, for a description of initialization sequence. Optional arguments, OPTIONS, are: `debug' Enable Guile debugging and stack traces. `nodebug' Disable Guile debugging and stack traces (default). `load-path=PATH' Append 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. *Note %load-path: (guile)Build Config. Guile databases are declared using the following syntax: database { name "DBNAME"; handler "MOD-NAME [OPTIONS] CMDLINE"; } where: DBNAME gives the name for this database, MOD-NAME is the name given to Guile module in `load-module' statement (see above), OPTIONS 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. CMDLINE is the command line that will be passed to the Guile `open-db' callback function (*note open-db::). 4.3.1 Virtual Functions ----------------------- 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 Open the database. close Close the database. descr Return a short description of the database. info Return a full information about the database. define Define a word. match Look up a word in the database. output Output a search result. result-count 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 *note Guile API::. 4.3.2 Guile Initialization -------------------------- 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 (*note primitive-load: (guile)Loading, 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))) 4.3.3 Guile API --------------- This subsection describes callback functions that a Guile database module must provide. The description of each function begins with the function prototype and its entry in the virtual function table. Callback functions can be subdivided into two groups: database functions and search functions. Database callback functions are responsible for opening and closing databases and for returning information about them. -- Guile Callback: open-db name . args Virtual table: `(cons "open" open-db)' Open the database. The argument NAME contains database name as given in `name' statement of `database' block (*note Databases::). Optional argument ARGS is a list of command line parameters obtained from CMDLINE in `handler' statement (*note 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. -- Guile Callback: close-db dbh 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. -- Guile Callback: descr dbh 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 (*note description: Databases.). Otherwise, if no `description' statement is present, empty string is used. -- Guile Callback: info dbh 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 (*note info: Databases.). 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. -- Guile Callback: lang dbh Virtual Table: `(cons "lang" lang)' -- Guile Callback: define-word dbh word 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'. -- Guile Callback: match-word dbh strat word 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 (*note Dico Scheme Primitives::). -- Guile Callback: output resh n 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. -- Guile Callback: result-count resh Virtual Table: `(cons "result-count" result-count)' Return the number of elements in the result set RESH. 4.3.4 Dico Scheme Primitives ---------------------------- GNU Dico provides the following Scheme primitives, that access various fields of the `strat' argument to `match' callback: -- Function: dico-strat-selector? STRAT Return true if STRAT has a selector. . -- Function: dico-strat-select? STRAT WORD KEY Return true if KEY matches WORD as per strategy selector STRAT. -- Function: dico-strat-name STRAT Return the name of strategy STRAT. -- Function: dico-strat-description STRAT Return a textual description of the strategy STRAT. -- Function: dico-strat-default? STRAT Return `true' if STRAT is a default strategy. *Note default strategy: MATCH. -- Function: dico-register-strat STRAT DESCR [FUN] 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 (*note strategy: MATCH.). The selector function must be declared as follows: (define (FUN key word) ...) It must return `#t' if KEY matches WORD, and `#f' otherwise. 4.3.5 Example Module -------------------- 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")' (*note 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 `car's 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 (*note 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 (*note SRFI-13: (guile)SRFI-13.) 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?' (*note dico-strat-select?: Dico Scheme Primitives. 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. 4.4 The `python' module. ======================== _(This message will disappear, once this node revised.)_ 5 Dico Module Interface *********************** _(This message will disappear, once this node revised.)_ 5.1 dico_database_module ======================== _(This message will disappear, once this node revised.)_ -- dico_database_module: unsigned dico_version Interface version being used. It is recommended to use the macro `DICO_MODULE_VERSION', which keeps the version number of the current interface. -- dico_database_module: unsigned dico_capabilities Additional capabilities. This member is reserved for future use (as of GNU Dico version 2.0. Use `DICO_CAPA_DEFAULT' to initialize it. -- Dico Callback: int dico_init (int ARGC, char **ARGV) This callback is called right after loading the module. It is responsible for module initialization. The arguments are: ARGC Number of elements in ARGV. ARGV The command line given by `command' configuration statement (*note command: Handlers.), 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. -- Dico Callback: dico_handle_t dico_init_db (const char *DB, int ARGC, char **ARGV) Initialize the database. This method is called as part of database initialization routine at startup of `dicod', after processing `dictionary' configuration statement (*note Databases::). Its arguments are: DB The name of the database, as given by the `name' statement. ARGC Number of elements in ARGV. ARGV The command line given by `handler' configuration statement (*note handler: Databases.). 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. -- Dico Callback: int dico_free_db (dico_handle_t DH) 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. -- Dico Callback: int dico_open (dico_handle_t DH) 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. -- Dico Callback: int dico_close (dico_handle_t DH) 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. -- Dico Callback: char * dico_db_info (dico_handle_t DH) 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 (*note info: Databases.). After use, the value returned by `dico_db_info' is freed using system `free' function. This method is optional. -- Dico Callback: char * dico_db_descr (dico_handle_t DH) 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 (*note descr: Databases.). After use, the value returned by `dico_db_descr' is freed using system `free' function. This method is optional. -- Dico Callback: dico_result_t dico_match (dico_handle_t DH, const dico_strategy_t STRAT, const char *WORD) 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. -- Dico Callback: dico_result_t dico_define (dico_handle_t DH, const char *WORD) 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. -- Dico Callback: int dico_output_result (dico_result_t RP, size_t N, dico_stream_t STR) 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. -- Dico Callback: size_t dico_result_count (dico_result_t RP) 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'. -- Dico Callback: size_t dico_compare_count (dico_result_t RP) Return number of comparisons performed when constructing the result set identified by RP. This method is optional. -- Dico Callback: void dico_free_result (dico_result_t RP) 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'. 5.2 Strategies ============== _(This message will disappear, once this node revised.)_ 5.3 Output ========== _(This message will disappear, once this node revised.)_ 5.4 Error Reporting =================== _(This message will disappear, once this node revised.)_ 6 Dico -- a client program. *************************** _(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. 6.1 Single Query Mode ===================== 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 (*note Initialization File::). If it is not present, a predefined value specified at configuration time (*note 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. 6.1.1 Dico Command Line Options ------------------------------- 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 (*note strategy: MATCH.), 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 (*note XLEV: Extended Commands, 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. 6.1.2 DICT URL -------------- 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 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. *Note Autologin::, for a detailed description of authentication procedure and sources which are used to obtain authentication credentials. PASS 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 (*note Autologin::). HOST Host name or IP address of the server to query. Same as `--host' command line option. PORT 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. WORD The word to look for. DATABASE The database to search in. If not given, `!' is assumed. Same as `--database' command line option. STRAT The matching strategy to use. If omitted, `.' is assumed. Same as `--strategy' command line option. N 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::: 6.2 Interactive Mode ==================== 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 (*note Command Line Editing: (readline)Command Line Editing.). 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 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 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 (*note prefix: Other Commands.). We will discuss the `dico' commands in the following subsections. 6.2.1 Server Commands --------------------- 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 *note 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. 6.2.2 Database and Strategy --------------------------- 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 (*note XLEV: Extended Commands.), 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. 6.2.3 Informational Commands ---------------------------- The `ls' command lists available strategies (*note SHOW STRAT: SHOW.): 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 (*note SHOW DB: SHOW.): 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 6.2.4 History Commands ---------------------- 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 *note Using History Interactively: (history)Using History Interactively. 6.2.5 Pager ----------- 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. 6.2.6 Program Settings ---------------------- The commands described in this subsection are designed mostly for use in `dico' initialization file (*note 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. *Note 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 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. 6.2.7 Session Transcript ------------------------ "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) <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 6.2.8 Other Commands -------------------- 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. 6.2.9 Dico Command Summary -------------------------- 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 PORT' Connect 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. *Note open: Server Commands. `close' Close the connection. *Note close: Server Commands. `autologin [FILE]' Set or display autologin file name. *Note 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. *Note database: Database and Strategy. `strategy [NAME]' Set or display current strategy. *Note strategy: Database and Strategy. `distance [NUM]' Set or query Levenshtein distance. This command takes effect only if the remote server supports `xlev' experimental capability (*note XLEV: Extended Commands.). *Note distance: Database and Strategy. `ls' List available matching strategies. *Note ls: Informational Commands. `ld' List all accessible databases. *Note ld: Informational Commands. `info [DB]' Display information about database DB, or the current database, if used without argument. `prefix [C]' Set or display command prefix. *Note prefix: Other Commands. `transcript [BOOL]' Set or display session transcript mode. *Note Session Transcript::. `verbose [NUMBER]' Set or display debugging verbosity level. . `prompt STRING' Change command line prompt. *Note prompt: Other Commands. `pager STRING' Change or display pager settings. *Note Pager::. `history' Display command history. *Note History Commands::. `help' Display short command usage summary. *Note help: Other Commands. `version' Print program version. *Note version: Other Commands. `warranty' Print copyright statement. *Note warranty: Other Commands. `quiet BOOL' Toggle display of `dico' welcome banner. This command can be used only in initialization file. *Note quiet: Program Settings. `quit' Quit the shell. *Note quit: Other Commands. 6.3 Initialization File ======================= 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 *note 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(1). Init files are useful to change the defaults for your `dico' invocation. Consider, for example, this init file: # An example init file for `dico' # Turn welcome banner off quiet yes # Set the location of autologin file autologin ~/.dicologin # Use this server by default open dict.org # Search in all databases database * # Finally, set the custom command prefix prefix : 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. ---------- Footnotes ---------- (1) The same holds true for interactive mode as well, but you will hardly need comments on a terminal. 6.4 Autologin ============= _(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: 1. Command line options `--user' and `--password'. 2. An URL given as a command line argument (*note user: urls.). 3. Autologin files. 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 (*note autologin: Program Settings.) 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 NAME' This 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 (*note urls::), or an argument to the `open' command (*note open: Server Commands.). 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 NAME' Supply user name for this server. `password STRING' Supply a password. `noauth' Do not perform authentication on this machine. `sasl' Enable SASL authentication. `nosasl' Disable SASL authentication. `mechanisms LIST' Declare 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 NAME' Declare service name, for authentication methods that need it. If this token is omitted, the default service name `dico' is used. `realm NAME' Declare realm for authentication. `host NAME' Set 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. 6.5 Dico invocation =================== This section contains a short summary of `dico' command line options. Command Line ------------ The following table summarizes the four existing ways of `dico' invocation: `dico [OPTIONS] WORD' Connect to the dictionary and define or match a WORD. *Note dico options::. `dico [OPTIONS] URL' Connect to the dictionary and define or match a word, supplied in the URL. *Note urls::. `dico [OPTIONS] OPMODE' Connect to the dictionary and query the information required by OPMODE option, which is one of `--dbs', `--strats', `--serverhelp', `--info', or `--serverinfo'. See below (*note Operation modes: dico-opmode.) for a description. `dico [OPTIONS]' Start interactive shell. *note Interactive Mode::. Server selection options: ------------------------- `--host=SERVER' Connect to this server. *Note -host: dico options. `--port=PORT' `-p PORT' Specify port to connect to. The argument PORT can be either a port number or its symbolic service name, as listed in `/etc/services'. `--database=NAME' `-d NAME' 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 `*'. *Note -database: dico options. `--source=ADDR' Set source address for TCP connections. Operation modifiers ------------------- `--match' `-m' Match instead of define. *Note -match: dico options. `--strategy=NAME' `-s NAME' 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'. *Note -strategy: dico options. `--levdist=N' `--levenshtein-distance=N' 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 (*note XLEV: Extended Commands.). *Note -levdist: dico options. `--quiet' `-q' Do not print the normal `dico' welcome banner when entering interactive shell. *Note quiet: Program Settings. Operation modes --------------- `--dbs' `-D' Show available databases. *Note -dbs: dico options. `--strats' `--strategies' `-S' Show available search strategies. *Note -strats: dico options. `--serverhelp' `-H' Show server help. `--info=DBNAME' `-i DBNAME' Show information about database DBNAME. `--serverinfo' `-I' Show information about the server. Authentication -------------- `--noauth' `-a' Disable authentication. *Note Autologin::. `--sasl' Enable SASL authentication. . `--nosasl' Disable SASL authentication. . `--user=NAME' `-u NAME' Set user name for authentication. *Note Autologin::. `--key=STRING' `-k STRING' `--password=STRING' Set shared secret for authentication. *Note Autologin::. `--autologin=NAME' Set the name of autologin file to use. *Note Autologin::. `--client=STRING' `-c STRING' Additional text for client command, instead of the default `dico 2.0'. Debugging options ----------------- `--transcript' `-t' Enable session transcript. *Note Session Transcript::, for a description. `--verbose' `-v' Increase debugging verbosity level. `--time-stamp' Include time stamp in the debugging output. `--source-info' Include source line information in the debugging output. Other options ------------- `--help' `-h' Display a short description of command line options. `--usage' Display a short usage message `--version' Print program version. 7 How to Report a Bug ********************* Email bug reports to or . 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: * Package version you use. The output of `dicod --version' will do. * A detailed description of the bug. * Conditions under which the bug appears. * It is often helpful to send the contents of `config.log' file along with your bug report. This file is created after running `./configure' in the source root directory of GNU Dico. Appendix A Dictionary Server Protocol ************************************* 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'. A.1 Initial Reply ================= When connection is established, the server sends an "initial reply" to the client. This reply has the following format: 220 HOSTNAME TEXT MSG-ID Its parts and their meaning are described in the following table: HOSTNAME The name of the host. It is determined automatically, unless set using `hostname' configuration file statement (*note hostname directive::). TEXT Arbitrary text, as set via `initial-banner-text' configuration statement (*note initial-banner-text: General Settings.). CAPABILITIES A comma-separated list of server capabilities. It is configured using `capability' statement (*note Capabilities::). MSG-ID A unique identifier similar to the format specified in RFC822 (ftp://ftp.rfc-editor.org/in-notes/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 (*note AUTH::). An example of initial reply follows: 220 Trurl.gnu.org.ua <520.1212912026@Trurl.gnu.org.ua> A.2 Standard Commands ===================== The following are standard commands, defined in RFC2229. A.2.1 The DEFINE Command ------------------------ The `DEFINE' command searches for definitions of a word. -- Command: DEFINE db 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 (*note SHOW DB: SHOW.). 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. *Note Tuning::, for more information about timing output. Possible responses from `DEFINE' command are: 550 Invalid database, use SHOW DB for a list 552 No match 150 N definitions found: list follows 151 WORD DATABASE NAME 250 ok (optional timing information here) 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 S: S: mwanamume S: S: . S: 250 Command complete [d/m/c = 1/0/12 0.000r 0.000u 0.000s] A.2.2 The MATCH Command ----------------------- The `MATCH' command searches for word in the database index. The searching algorithm is called "strategy". The following strategies are supported by the server: exact Match a word exactly (case-insensitive). prefix Match a word prefix (case-insensitive). soundex Match using SOUNDEX algorithm. lev 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 (*note XLEV: Extended Commands.). dlev Match headwords within given Damerau-Levenshtein distance. That distance is the same as for the `lev' strategy. re Match using POSIX 1003.2 (a.k.a `extended') regular expressions. regexp Match using basic regular expressions. The `dictorg' module (*note Dictorg::) additionally provides the following strategy: suffix Match word suffixes (case-insensitive). Other modules may provide more matching strategies. -- Command: MATCH database strategy word Match WORD in DATABASE using STRATEGY. As with `DEFINE', the DATABASE can be `!' or `*' (*Note DEFINE::, 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 (*note default-strategy: General Settings. 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 (*note Tuning::). Possible responses: 550 Invalid database, use SHOW DB for a list 551 Invalid strategy, use SHOW STRAT for a list 552 No match 152 N matches found: list follows 250 ok (optional timing information here) 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] A.2.3 The SHOW Command ---------------------- The `SHOW' command outputs various information about the server and databases. -- Command: SHOW DB -- Command: SHOW 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: 110 N databases present 554 No databases present -- Command: SHOW STRAT -- Command: SHOW STRATEGIES 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: 111 N strategies available 555 No strategies available -- Command: SHOW INFO database 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: 550 Invalid database, use SHOW DB for a list 112 database information follows The textual body is retrieved from the `info' statement in the configuration file (*note info: Databases.), or, if it is not specified, from the database itself, using `dico_db_info' callback function (*note dico_db_info::). If neither source returns anything, the string `No information available.' is returned. -- Command: SHOW SERVER Return a server-specific information. Response: 114 server information follows 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 (*note show-sys-info: Security Settings.). This line is followed by the text supplied with `server-info' configuration statement (*note server-info: General Settings.). A.2.4 The OPTION Command ------------------------ The `OPTION' command allows to request optional features on the remote server. Currently the only implemented subcommand is: -- Command: OPTION MIME Requests that all text responses be prefaced by a MIME header (RFC2045 (ftp://ftp.rfc-editor.org/in-notes/rfc2045.txt)) 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 (*Note content-type: Databases, *note content-transfer-encoding: Databases.). Any or both of these headers may be missing. A.2.5 The AUTH Command ---------------------- The `AUTH' command allows client to authenticate itself to the server. Depending on the server configuration, authenticated users may get access to more databases (*note Database Visibility::) or more detailed server information (*note show-sys-info: Security Settings.). -- Command: AUTH username auth-string Authenticate client to the server using a username and password. The AUTH-STRING is computed as in the APOP protocol (RFC1939 (ftp://ftp.rfc-editor.org/in-notes/rfc1929.txt). Briefly, it is the MD5 checksum of the concatenation of the MSG-ID (*note Initial Reply::) and the "shared secret" that is stored both on the server and client machines. *Note Authentication::, for information on how to configure server for authenticating clients. This command is supported only if `auth' capability is requested in the configuration (*note auth: Capabilities.). A.2.6 The CLIENT Command ------------------------ -- Command: CLIENT info 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 (*note %C: Access Log.). A.2.7 The STATUS Command ------------------------ -- Command: STATUS Display cumulative timing information. This command returns a `210' status code, followed by the timing information as described in *note Tuning::, e.g. C: STATUS S: 210 [d/m/c = 28/1045/119856 21.180r 10.360u 1.040s] A.2.8 The HELP Command ---------------------- -- Command: HELP 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 (*note help-text: General Settings.), 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 A.2.9 The QUIT Command ---------------------- -- Command: QUIT Terminate connection. This command returns a response code 221, optionally followed by timing information (*note Tuning::). A.3 Extended Commands ===================== In addition to the standard commands, the Dico server also offers a set of experimental or extended commands. -- Command: XIDLE This command displays the current inactivity timeout setting (*note 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. -- Command: XVERSION This command displays the daemon implementation and version number. It becomes available only if `xversion' capability was requested in the configuration file (*note xversion: Capabilities.). C: XVERSION S: 110 dicod (dico 2.0) -- Command: XLEV param 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 (*note xlev: Capabilities.). C: xlev tell S: 280 1 C: xlev 3 S: 250 ok - Levenshtein threshold set to 3 C: xlev tell S: 280 3 Appendix B Time and Date Formats ******************************** This appendix documents the time format specifications understood by the `%t' log format specifier (*note 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 (*note 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 (*note 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. Appendix C The Libdico Library ****************************** C.1 Strategies ============== _(This message will disappear, once this node revised.)_ struct dico_strategy { char *name; char *descr; dico_select_t sel; void *closure; int is_default; }; -- Function: dico_strategy_t dico_strategy_dup (const dico_strategy_t STRAT) -- Function: dico_strategy_t dico_strategy_find (const char *NAME) -- Function: int dico_strategy_add (const dico_strategy_t STRAT) -- Function: dico_iterator_t dico_strategy_iterator (void) -- Function: void dico_strategy_iterate (dico_list_iterator_t ITR, void *DATA) -- Function: size_t dico_strategy_count (void) -- Function: int dico_set_default_strategy (const char *NAME) -- Function: const dico_strategy_t dico_get_default_strategy (void) -- Function: int dico_strategy_is_default_p (dico_strategy_t STRAT) C.2 argcv ========= _(This message will disappear, once this node revised.)_ -- enum: dico_argcv_quoting_style -- Variable: enum dico_argcv_quoting_style dico_argcv_quoting_style -- Function: int dico_argcv_get (const char *COMMAND, const char *DELIM, const char *CMNT, int *ARGC, char ***ARGV) -- Function: int dico_argcv_get_n (const char *COMMAND, int LEN, const char *DELIM, const char *CMNT, int *ARGC, char ***ARGV) -- Function: int dico_argcv_get_np (const char *COMMAND, int LEN, const char *DELIM, const char *CMNT, int FLAGS, int *ARGC, char ***ARGV, char **ENDP) -- Function: int dico_argcv_string (int ARGC, const char **ARGV, char **STRING) -- Function: void dico_argcv_free (int ARGC, char **ARGV) -- Function: void dico_argv_free (char **ARGV) -- Function: int dico_argcv_unquote_char (int C) -- Function: int dico_argcv_quote_char (int C) -- Function: size_t dico_argcv_quoted_length (const char *STR, int *QUOTE) -- Function: void dico_argcv_unquote_copy (char *DST, const char *SRC, size_t N) -- Function: void dico_argcv_quote_copy (char *DST, const char *SRC) -- Function: void dico_argcv_remove (int *ARGC, char ***ARGV, int (*SEL) (const char *, void *), void *DATA) C.3 Lists ========= _(This message will disappear, once this node revised.)_ -- Type: dico_list_t -- Type: dico_iterator_t -- Function Type: dico_list_iterator_t typedef int (*dico_list_iterator_t)(void *item, void *data); -- Function Type: dico_list_comp_t typedef int (*dico_list_comp_t)(const void *, const void *); -- Function: dico_list_t dico_list_create (void) -- Function: void dico_list_destroy (dico_list_t *LIST, dico_list_iterator_t FREE, void *DATA) -- Function: void dico_list_iterate (dico_list_t LIST, dico_list_iterator_t ITR, void *DATA) -- Function: void * dico_list_item (dico_list_t LIST, size_t N) -- Function: size_t dico_list_count (dico_list_t LIST) -- Function: int dico_list_append (dico_list_t LIST, void *DATA) -- Function: int dico_list_prepend (dico_list_t LIST, void *DATA) -- Function: int dico_list_push (dico_list_t LIST, void *DATA) -- Function: int dico_list_insert_sorted (dico_list_t LIST, void *DATA, dico_list_comp_t CMP) -- Function: dico_list_t dico_list_intersect (dico_list_t A, dico_list_t B, dico_list_comp_t CMP) -- Function: int dico_list_intersect_p (dico_list_t A, dico_list_t B, dico_list_comp_t CMP) -- Function: void * dico_list_pop (dico_list_t LIST) -- Function: void * dico_list_locate (dico_list_t LIST, void *DATA, dico_list_comp_t CMP) -- Function: void * dico_list_remove (dico_list_t LIST, void *DATA, dico_list_comp_t CMP) -- Function: void * dico_iterator_current (dico_iterator_t ITR) -- Function: dico_iterator_t dico_iterator_create (dico_list_t LIST) -- Function: void dico_iterator_destroy (dico_iterator_t *PITR) -- Function: void * dico_iterator_first (dico_iterator_t ITR) -- Function: void * dico_iterator_next (dico_iterator_t ITR) -- Function: void * dico_iterator_remove_current (dico_iterator_t ITR) -- Function: void dico_iterator_set_data (dico_iterator_t ITR, void *DATA) C.4 Associative lists ===================== _(This message will disappear, once this node revised.)_ struct dico_assoc { char *key; char *value; }; -- Type: dico_assoc_list_t -- Function: dico_assoc_list_t dico_assoc_create (void) -- Function: void dico_assoc_destroy (dico_assoc_list_t *PASSOC) -- Function: int dico_assoc_add (dico_assoc_list_t ASSOC, const char *KEY, const char *VALUE) -- Function: const char * dico_assoc_find ( dico_assoc_list_t ASSOC, const char *KEY) -- Function: void dico_assoc_remove ( dico_assoc_list_t ASSOC, const char *KEY) C.5 Diagnostics Functions ========================= _(This message will disappear, once this node revised.)_ L_DEBUG L_INFO L_NOTICE L_WARN L_ERR L_CRIT L_ALERT L_EMERG -- Variable: const char * dico_program_name -- Variable: const char * dico_invocation_name -- Function: void dico_set_program_name (char *NAME) -- Function Type: void dico_log_printer_t ( int LVL, int EXITCODE, int ERRCODE, const char *FMT, va_list AP) -- Function: void dico_set_log_printer (dico_log_printer_t PRT) -- Function: void dico_vlog ( int LVL, int ERRCODE, const char *FMT, va_list AP) -- Function: void dico_log (int LVL, int ERRCODE, const char *FMT, ...) -- Function: void dico_die (int EXITCODE, int LVL, int ERRCODE, char *FMT, ...) -- Function: int dico_str_to_diag_level (const char *STR) -- Function: dico_stream_t dico_log_stream_create (int LEVEL) C.6 Filter ========== -- Define: FILTER_ENCODE -- Define: FILTER_DECODE -- Function Type: filter_xcode_t typedef int (*filter_xcode_t) (const char *, size_t, char *, size_t, size_t *, size_t, size_t *); -- Function: dico_stream_t filter_stream_create ( dico_stream_t STR, size_t MIN_LEVEL, size_t MAX_LINE_LENGTH, filter_xcode_t XCODE, int MODE) -- Function: dico_stream_t dico_codec_stream_create ( const char *ENCODING, int MODE, dico_stream_t TRANSPORT) -- Function: dico_stream_t dico_base64_stream_create ( dico_stream_t STR, int MODE) -- Function: dico_stream_t dico_qp_stream_create ( dico_stream_t STR, int MODE) -- Function: int dico_base64_input (char C) -- Function: int dico_base64_decode ( const char *IPTR, size_t ISIZE, char *OPTR, size_t OSIZE, size_t *PNBYTES, size_t LINE_MAX, size_t *PLINE_LEN) -- Function: int dico_base64_encode ( const char *IPTR, size_t ISIZE, char *OPTR, size_t OSIZE, size_t *PNBYTES, size_t LINE_MAX, size_t *PLINE_LEN) -- Function: int dico_qp_decode ( const char *IPTR, size_t ISIZE, char *OPTR, size_t OSIZE, size_t *PNBYTES, size_t LINE_MAX, size_t *PLINE_LEN) -- Function: int dico_qp_encode ( const char *IPTR, size_t ISIZE, char *OPTR, size_t OSIZE, size_t *PNBYTES, size_t LINE_MAX, size_t *PLINE_LEN) C.7 parseopt ============ _(This message will disappear, once this node revised.)_ `DICO_PARSEOPT_PARSE_ARGV0' `DICO_PARSEOPT_PERMUTE' -- Enumeration: dico_opt_type `dico_opt_null' `dico_opt_bool' `dico_opt_bitmask' `dico_opt_bitmask_rev' `dico_opt_long' `dico_opt_string' `dico_opt_enum' `dico_opt_const' `dico_opt_const_string' -- struct: dico_option struct 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 *); }; -- Macro: DICO_OPTSTR name -- Function: int dico_parseopt (struct dico_option *OPT, int ARGC, char **ARGV, int FLAGS, int *INDEX) C.8 stream ========== _(This message will disappear, once this node revised.)_ -- Function: int dico_stream_create (dico_stream_t *PSTREAM, int FLAGS, void *DATA) `DICO_STREAM_READ' `DICO_STREAM_WRITE' `DICO_STREAM_SEEK' -- Function: int dico_stream_open (dico_stream_t STREAM) -- Function: void dico_stream_set_open ( dico_stream_t STREAM, int (*OPENFN) (void *, int)) -- Function: void dico_stream_set_seek ( dico_stream_t STREAM, int (*FUN_SEEK) (void *, off_t, int, off_t *)) -- Function: void dico_stream_set_size ( dico_stream_t STREAM, int (*SIZEFN) (void *, off_t *)) -- Function: void dico_stream_set_read ( dico_stream_t STREAM, int (*READFN) (void *, char *, size_t, size_t *)) -- Function: void dico_stream_set_write ( dico_stream_t STREAM, int (*WRITEFN) (void *, const char *, size_t, size_t *)) -- Function: void dico_stream_set_flush ( dico_stream_t STREAM, int (*FLUSHFN) (void *)) -- Function: void dico_stream_set_close ( dico_stream_t STREAM, int (*CLOSEFN) (void *)) -- Function: void dico_stream_set_destroy ( dico_stream_t STREAM, int (*DESTROYFN) (void *)) -- Function: void dico_stream_set_ioctl ( dico_stream_t STREAM, int (*CTL) (void *, int, void *)) -- Function: void dico_stream_set_error_string ( dico_stream_t STREAM, const char *(*ERROR_STRING) (void *, int)) -- Function: int dico_stream_set_buffer ( dico_stream_t STREAM, enum dico_buffer_type TYPE, size_t size) -- Enumeration: dico_buffer_type `dico_buffer_none' `dico_buffer_line' `dico_buffer_full' -- Function: off_t dico_stream_seek ( dico_stream_t STREAM, off_t OFFSET, int WHENCE) `DICO_SEEK_SET' `DICO_SEEK_CUR' `DICO_SEEK_END' -- Function: int dico_stream_size (dico_stream_t STREAM, off_t *PSIZE) -- Function: int dico_stream_read_unbuffered ( dico_stream_t STREAM, void *BUF, size_t SIZE, size_t *PREAD) -- Function: int dico_stream_write_unbuffered ( dico_stream_t STREAM, const void *BUF, size_t SIZE, size_t *PWRITE) -- Function: int dico_stream_read ( dico_stream_t STREAM, void *BUF, size_t SIZE, size_t *PREAD) -- Function: int dico_stream_readln ( dico_stream_t STREAM, char *BUF, size_t SIZE, size_t *PREAD) -- Function: int dico_stream_getdelim ( dico_stream_t STREAM, char **PBUF, size_t *PSIZE, int DELIM, size_t *PREAD) -- Function: int dico_stream_getline ( dico_stream_t STREAM, char **PBUF, size_t *PSIZE, size_t *PREAD) -- Function: int dico_stream_write ( dico_stream_t STREAM, const void *BUF, size_t SIZE) -- Function: int dico_stream_writeln ( dico_stream_t STREAM, const char *BUF, size_t SIZE) -- Function: int dico_stream_ioctl ( dico_stream_t STREAM, int CODE, void *PTR) -- Function: const char * dico_stream_strerror ( dico_stream_t STREAM, int RC) -- Function: int dico_stream_last_error (dico_stream_t STREAM) -- Function: void dico_stream_clearerr (dico_stream_t STREAM) -- Function: int dico_stream_eof (dico_stream_t STREAM) -- Function: int dico_stream_flush (dico_stream_t STREAM) -- Function: int dico_stream_close (dico_stream_t STREAM) -- Function: void dico_stream_destroy (dico_stream_t *STREAM) -- Function: off_t dico_stream_bytes_in (dico_stream_t STREAM) -- Function: off_t dico_stream_bytes_out (dico_stream_t STREAM) C.9 url ======= _(This message will disappear, once this node revised.)_ -- struct: dico_url #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; }; -- Pointer: dico_url_t -- Function: int dico_url_parse (dico_url_t *PURL, const char *STR) -- Function: void dico_url_destroy (dico_url_t *PURL) -- Function: const char * dico_url_get_arg ( dico_url_t URL, const char *ARGNAME) -- Function: char * dico_url_full_path (dico_url_t URL) C.10 UTF-8 ========== _(This message will disappear, once this node revised.)_ -- Function: size_t utf8_char_width (const unsigned char *CP) -- Function: size_t utf8_strlen (const char *STR) -- struct: utf8_iterator struct utf8_iterator { char *string; char *curptr; unsigned curwidth; }; -- Function: int utf8_iter_isascii (struct utf8_iterator ITR) -- Function: int utf8_iter_end_p (struct utf8_iterator *ITR) -- Function: int utf8_iter_first (struct utf8_iterator *ITR, unsigned char *PTR) -- Function: int utf8_iter_next (struct utf8_iterator *ITR) -- Function: int utf8_mbtowc_internal (void *DATA, int (*READ) (void*), unsigned int *PWC) -- Function: int utf8_wctomb (unsigned char *R, unsigned int WC) -- Function: int utf8_symcmp (unsigned char *A, unsigned char *B) -- Function: int utf8_symcasecmp (unsigned char *A, unsigned char *B) -- Function: int utf8_strcasecmp (unsigned char *A, unsigned char *B) -- Function: int utf8_strncasecmp (unsigned char *A, unsigned char *B, size_t MAXLEN) -- Function: unsigned utf8_wc_toupper (unsigned WC) -- Function: int utf8_toupper (char *S, size_t LEN) -- Function: unsigned utf8_wc_tolower (unsigned WC) -- Function: int utf8_tolower (char *S, size_t LEN) -- Function: size_t utf8_wc_strlen (const unsigned *S) -- Function: unsigned * utf8_wc_strdup (const unsigned *S) -- Function: size_t utf8_wc_hash_string (const unsigned *WS, size_t N_BUCKETS) -- Function: int utf8_wc_strcmp (const unsigned *A, const unsigned *B) -- Function: int utf8_wc_to_mbstr (const unsigned *WORDBUF, size_t WORDLEN, char *S, size_t SIZE) -- Function: int utf8_mbstr_to_wc (const char *STR, unsigned **WPTR) -- Function: int utf8_mbstr_to_norm_wc (const char *STR, unsigned **WPTR) -- Function: int dico_levenshtein_distance (const char *A, const char *B, int FLAGS) `DICO_LEV_NORM' `DICO_LEV_DAMERAU' -- Function: int dico_soundex (const char *S, char CODESTR[DICO_SOUNDEX_SIZE]) -- Define: DICO_SOUNDEX_SIZE 5 C.11 util ========= _(This message will disappear, once this node revised.)_ -- Function: char * dico_full_file_name (const char *DIR, const char *FILE) -- Function: size_t dico_trim_nl (char *BUF) -- Function: size_t dico_trim_ws (char *BUF) C.12 xlat ========= _(This message will disappear, once this node revised.)_ -- struct: xlat_tab struct xlat_tab { char *string; int num; }; -- Function: int xlat_string (struct xlat_tab *TAB, const char *STRING, size_t LEN, int FLAGS, int *RESULT) -- Function: int xlat_c_string (struct xlat_tab *TAB, const char *STRING, int FLAGS, int *RESULT); `XLAT_ICASE' Appendix D GNU Free Documentation License ***************************************** Version 1.3, 3 November 2008 Copyright (C) 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. 0. PREAMBLE 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. 1. APPLICABILITY AND DEFINITIONS 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. 2. VERBATIM COPYING 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. 3. COPYING IN QUANTITY 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. 4. MODIFICATIONS 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: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. 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. 5. COMBINING DOCUMENTS 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." 6. COLLECTIONS OF DOCUMENTS 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. 7. AGGREGATION WITH INDEPENDENT WORKS 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. 8. TRANSLATION 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. 9. TERMINATION 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. 10. FUTURE REVISIONS OF THIS LICENSE 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. 11. RELICENSING "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. ADDENDUM: How to use this License for your documents ==================================================== 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. Concept Index ************* This is a general index of all issues discussed in this manual. #include: See 3.3.1.2. (line 458) #include_once: See 3.3.1.2. (line 477) #line: See 3.3.1.2. (line 482) % formats: See 3.3.7. (line 1081) --without-guile, configuration option: See 2.3. (line 253) --without-preprocessor, configuration option: See 2.1. (line 221) --without-python, configuration option: See 2.4. (line 266) -E, introduced: See 3.3. (line 412) .dico: See 6.3. (line 3312) .dico_history: See 6.2.4. (line 3019) .dicologin: See 6.4. (line 3375) .ld: See 6.2.3. (line 2995) /etc/ld.so.conf: See 3.3.10. (line 1369) access control lists: See 3.3.4. (line 883) access log: See 3.3.7. (line 1066) access-log-file: See 3.3.7. (line 1071) access-log-format: See 3.3.7. (line 1079) acl: See 3.3.4. (line 888) ACL: See 3.3.4. (line 883) alias: See 3.3.14. (line 1639) all: See 3.3.4. (line 913) allow: See 3.3.4. (line 902) Ambrose Bierce: See 4.1. (line 1882) Apache: See 3.3.7. (line 1066) article: See 3. (line 287) AUTH: See A.2.5. (line 3979) authenticated: See 3.3.4. (line 916) authentication: See 3.3.3. (line 755) authentication database: See 3.3.3. (line 766) authentication database configuration: See 3.3.3. (line 824) authentication database definition: See 3.3.3. (line 824) authentication database URL: See 3.3.3. (line 778) authentication database, text: See 3.3.3.1. (line 838) authentication resource: See 3.3.3. (line 812) autologin: See 6.2.6. (line 3068) autologin feature: See 6.4. (line 3352) autologin file: See 6.4. (line 3375) block statement: See 3.3.1.3. (line 618) boolean value: See 3.3.1.3. (line 520) capability: See 3.3.9. (line 1290) CLIENT: See A.2.6. (line 3996) close: See 6.2.1. (line 2923) close-db: See 4.3.3. (line 2193) command: See 3.3.10. (line 1337) command line options: See 3.4. (line 1723) Comments in a configuration file: See 3.3.1.1. (line 435) comments, pragmatic: See 3.3.1.2. (line 452) config, --config option, introduced: See 3.3. (line 398) config, --config option, summary: See 3.4. (line 1725) config-help, --config-help option, introduced: See 3.3. (line 417) config-help, --config-help option, summary: See 3.4. (line 1803) configuration file: See 3.3. (line 398) configuration file statements: See 3.3.1.3. (line 500) connection-acl: See 3.3.5. (line 997) content-transfer-encoding: See 3.3.11. (line 1468) content-type: See 3.3.11. (line 1458) daemon operation mode: See 3.1. (line 345) database <1>: See 6.2.2. (line 2929) database <2>: See 4.2. (line 1963) database <3>: See 3.3.11. (line 1398) database: See 3. (line 287) database description: See 3. (line 292) database handler, defined: See 3.3.10. (line 1324) database layer: See 1. (line 150) database module, defined: See 3.3.10. (line 1320) database name: See 3. (line 292) database visibility: See 3.3.11.1. (line 1480) database, authentication: See 3.3.3. (line 766) databases, defining: See 3.3.11. (line 1395) dbdir: See 4.2. (line 1925) debug: See 4.3. (line 2008) debug, --debug option, summary: See 3.4. (line 1786) Default preprocessor: See 2.1. (line 202) default searches: See 3.3.12. (line 1526) default, autologin keyword: See 6.4. (line 3399) default-strategy: See 3.3.8. (line 1278) DEFAULT_DICT_SERVER: See 2.2. (line 231) DEFAULT_PREPROCESSOR: See 2.1. (line 202) DEFINE: See A.2.1. (line 3733) define-word: See 4.3.3. (line 2238) deny: See 3.3.4. (line 905) deny-all: See 3.3.12. (line 1548) deny-length-eq: See 3.3.12. (line 1568) deny-length-ge: See 3.3.12. (line 1564) deny-length-gt: See 3.3.12. (line 1561) deny-length-le: See 3.3.12. (line 1558) deny-length-lt: See 3.3.12. (line 1555) deny-length-ne: See 3.3.12. (line 1571) deny-word: See 3.3.12. (line 1551) descr: See 4.3.3. (line 2202) description: See 3.3.11. (line 1422) description, database: See 3. (line 292) Devil's Dictionary: See 4.1. (line 1882) devils.out: See 4.1. (line 1882) Dico overview: See 1. (line 150) dico, a program: See 6. (line 2686) dico-register-strat: See 4.3.4. (line 2291) dico-strat-default?: See 4.3.4. (line 2287) dico-strat-description: See 4.3.4. (line 2284) dico-strat-name: See 4.3.4. (line 2281) dico-strat-select?: See 4.3.4. (line 2278) dico-strat-selector?: See 4.3.4. (line 2275) dico_argcv_free: See C.2. (line 4260) dico_argcv_get: See C.2. (line 4250) dico_argcv_get_n: See C.2. (line 4252) dico_argcv_get_np: See C.2. (line 4255) dico_argcv_quote_char: See C.2. (line 4266) dico_argcv_quote_copy: See C.2. (line 4274) dico_argcv_quoted_length: See C.2. (line 4269) dico_argcv_quoting_style: See C.2. (line 4245) dico_argcv_remove: See C.2. (line 4277) dico_argcv_string: See C.2. (line 4258) dico_argcv_unquote_char: See C.2. (line 4264) dico_argcv_unquote_copy: See C.2. (line 4272) dico_argv_free: See C.2. (line 4262) dico_assoc_add: See C.4. (line 4360) dico_assoc_create: See C.4. (line 4355) dico_assoc_destroy: See C.4. (line 4357) dico_assoc_find: See C.4. (line 4363) dico_assoc_list_t: See C.4. (line 4353) dico_assoc_remove: See C.4. (line 4366) dico_base64_decode: See C.6. (line 4440) dico_base64_encode: See C.6. (line 4444) dico_base64_input: See C.6. (line 4436) dico_base64_stream_create: See C.6. (line 4431) dico_buffer_type: See C.8. (line 4547) DICO_CAPA_DEFAULT: See 5.1. (line 2535) dico_capabilities: See 5.1. (line 2535) dico_close: See 5.1. (line 2599) dico_codec_stream_create: See C.6. (line 4428) dico_compare_count: See 5.1. (line 2656) dico_db_descr: See 5.1. (line 2617) dico_db_info: See 5.1. (line 2608) dico_define: See 5.1. (line 2636) dico_die: See C.5. (line 4406) dico_free_db: See 5.1. (line 2584) dico_free_result: See 5.1. (line 2662) dico_full_file_name: See C.11. (line 4733) dico_get_default_strategy: See C.1. (line 4236) dico_init: See 5.1. (line 2540) dico_init_db: See 5.1. (line 2559) dico_invocation_name: See C.5. (line 4391) dico_iterator_create: See C.3. (line 4330) dico_iterator_current: See C.3. (line 4328) dico_iterator_destroy: See C.3. (line 4332) dico_iterator_first: See C.3. (line 4334) dico_iterator_next: See C.3. (line 4336) dico_iterator_remove_current: See C.3. (line 4338) dico_iterator_set_data: See C.3. (line 4341) dico_iterator_t: See C.3. (line 4286) dico_levenshtein_distance: See C.10. (line 4717) dico_list_append: See C.3. (line 4306) dico_list_comp_t: See C.3. (line 4291) dico_list_count: See C.3. (line 4304) dico_list_create: See C.3. (line 4294) dico_list_destroy: See C.3. (line 4297) dico_list_insert_sorted: See C.3. (line 4312) dico_list_intersect: See C.3. (line 4315) dico_list_intersect_p: See C.3. (line 4318) dico_list_item: See C.3. (line 4302) dico_list_iterate: See C.3. (line 4300) dico_list_iterator_t: See C.3. (line 4288) dico_list_locate: See C.3. (line 4323) dico_list_pop: See C.3. (line 4320) dico_list_prepend: See C.3. (line 4308) dico_list_push: See C.3. (line 4309) dico_list_remove: See C.3. (line 4326) dico_list_t: See C.3. (line 4284) dico_log: See C.5. (line 4403) dico_log_printer_t: See C.5. (line 4396) dico_log_stream_create: See C.5. (line 4410) dico_match: See 5.1. (line 2627) DICO_MODULE_VERSION: See 5.1. (line 2530) dico_open: See 5.1. (line 2591) dico_opt_type: See C.7. (line 4463) dico_option: See C.7. (line 4482) DICO_OPTSTR: See C.7. (line 4495) dico_output_result: See 5.1. (line 2644) dico_parseopt: See C.7. (line 4498) dico_program_name: See C.5. (line 4389) dico_qp_decode: See C.6. (line 4448) dico_qp_encode: See C.6. (line 4452) dico_qp_stream_create: See C.6. (line 4434) dico_result_count: See 5.1. (line 2651) dico_set_default_strategy: See C.1. (line 4234) dico_set_log_printer: See C.5. (line 4398) dico_set_program_name: See C.5. (line 4393) dico_soundex: See C.10. (line 4723) DICO_SOUNDEX_SIZE: See C.10. (line 4724) dico_str_to_diag_level: See C.5. (line 4408) dico_strategy_add: See C.1. (line 4225) dico_strategy_count: See C.1. (line 4232) dico_strategy_dup: See C.1. (line 4221) dico_strategy_find: See C.1. (line 4223) dico_strategy_is_default_p: See C.1. (line 4238) dico_strategy_iterate: See C.1. (line 4230) dico_strategy_iterator: See C.1. (line 4227) dico_stream_bytes_in: See C.8. (line 4608) dico_stream_bytes_out: See C.8. (line 4610) dico_stream_clearerr: See C.8. (line 4598) dico_stream_close: See C.8. (line 4604) dico_stream_create: See C.8. (line 4506) dico_stream_destroy: See C.8. (line 4606) dico_stream_eof: See C.8. (line 4600) dico_stream_flush: See C.8. (line 4602) dico_stream_getdelim: See C.8. (line 4579) dico_stream_getline: See C.8. (line 4582) dico_stream_ioctl: See C.8. (line 4591) dico_stream_last_error: See C.8. (line 4596) dico_stream_open: See C.8. (line 4513) dico_stream_read: See C.8. (line 4573) dico_stream_read_unbuffered: See C.8. (line 4567) dico_stream_readln: See C.8. (line 4576) dico_stream_seek: See C.8. (line 4556) dico_stream_set_buffer: See C.8. (line 4546) dico_stream_set_close: See C.8. (line 4534) dico_stream_set_destroy: See C.8. (line 4537) dico_stream_set_error_string: See C.8. (line 4543) dico_stream_set_flush: See C.8. (line 4531) dico_stream_set_ioctl: See C.8. (line 4540) dico_stream_set_open: See C.8. (line 4516) dico_stream_set_read: See C.8. (line 4525) dico_stream_set_seek: See C.8. (line 4519) dico_stream_set_size: See C.8. (line 4522) dico_stream_set_write: See C.8. (line 4528) dico_stream_size: See C.8. (line 4564) dico_stream_strerror: See C.8. (line 4594) dico_stream_write: See C.8. (line 4585) dico_stream_write_unbuffered: See C.8. (line 4570) dico_stream_writeln: See C.8. (line 4588) dico_trim_nl: See C.11. (line 4735) dico_trim_ws: See C.11. (line 4737) dico_url: See C.9. (line 4617) dico_url_destroy: See C.9. (line 4645) dico_url_full_path: See C.9. (line 4650) dico_url_get_arg: See C.9. (line 4648) dico_url_parse: See C.9. (line 4643) dico_url_t: See C.9. (line 4641) dico_version: See 5.1. (line 2530) dico_vlog: See C.5. (line 4401) dicod, description: See 3. (line 283) dicod, operation modes: See 3. (line 340) dicod.conf: See 3.3. (line 398) DICT protocol: See 1. (line 150) dict server, default: See 2.2. (line 231) dictorg database declaration: See 4.2. (line 1953) dictorg database format: See 1. (line 162) dictorg handler definition: See 4.2. (line 1915) dictorg initialization options: See 4.2. (line 1925) dictorg module: See 4.2. (line 1903) distance: See 6.2.2. (line 2965) escape sequence: See 3.3.1.3. (line 528) FILTER_DECODE: See C.6. (line 4417) FILTER_ENCODE: See C.6. (line 4415) filter_stream_create: See C.6. (line 4425) filter_xcode_t: See C.6. (line 4419) foreground, --foreground option, introduced: See 3.1. (line 377) foreground, --foreground option, summary: See 3.4. (line 1729) group <1>: See 3.3.4. (line 919) group: See 3.3.2. (line 644) group-resource: See 3.3.3. (line 816) Guile: See 4.3. (line 1979) Guile API: See 4.3.3. (line 2156) Guile strategy functions: See 4.3.4. (line 2271) guile, configuration: See 2.3. (line 247) handler: See 3.3.11. (line 1406) headword: See 3. (line 287) HELP: See A.2.8. (line 4016) help: See 6.2.8. (line 3172) help, --help option, summary: See 3.4. (line 1811) help-text: See 3.3.8. (line 1256) here-document: See 3.3.1.3. (line 566) history: See 6.2.4. (line 3025) host, autologin keyword: See 6.4. (line 3444) hostname: See 3.3.8. (line 1225) ident-keyfile: See 3.3.2. (line 745) ident-timeout: See 3.3.2. (line 749) identity-check: See 3.3.2. (line 740) inactivity-timeout: See 3.3.2. (line 727) include-dir, --include-dir option, summary: See 3.4. (line 1753) inetd operation mode: See 3.2. (line 386) inetd, --inetd option, introduced: See 3.2. (line 386) inetd, --inetd option, summary: See 3.4. (line 1782) inetd.conf: See 3.2. (line 386) info <1>: See 6.2.3. (line 3003) info <2>: See 4.3.3. (line 2215) info: See 3.3.11. (line 1435) information, database: See 3. (line 292) init file: See 6.3. (line 3312) init-args: See 4.3. (line 1997) init-fun <1>: See 4.3.2. (line 2113) init-fun: See 4.3. (line 1997) init-script <1>: See 4.3.2. (line 2113) init-script: See 4.3. (line 1997) initial-banner-text: See 3.3.8. (line 1202) initialization file: See 6.3. (line 3312) invocation: See 3.4. (line 1723) lang: See 4.3.3. (line 2235) LD_LIBRARY_PATH: See 3.3.10. (line 1369) lint, --lint option, introduced: See 3.3. (line 407) lint, --lint option, summary: See 3.4. (line 1806) list: See 3.3.1.3. (line 606) listen: See 3.3.2. (line 672) load path: See 3.3.10. (line 1357) load-module: See 3.3.10. (line 1330) load-path: See 4.3. (line 2014) log-facility: See 3.3.6. (line 1034) log-print-severity: See 3.3.6. (line 1039) log-tag: See 3.3.6. (line 1030) LOG_FACILITY: See 2.5. (line 272) logging requests: See 3.3.7. (line 1066) logging, configuration: See 3.3.6. (line 1026) login, autologin keyword: See 6.4. (line 3416) ls: See 6.2.3. (line 2981) LTDL_LIBRARY_PATH: See 3.3.10. (line 1367) m4: See 3.3.15. (line 1665) machine, autologin keyword: See 6.4. (line 3395) MATCH: See A.2.2. (line 3825) match-word: See 4.3.3. (line 2245) matching strategy: See A.2.2. (line 3787) max-children: See 3.3.2. (line 722) mechanisms, autologin keyword: See 6.4. (line 3431) mode: See 3.3.2. (line 658) module load path: See 3.3.10. (line 1357) module-load-path: See 3.3.10. (line 1387) Modules: See 4. (line 1824) multi-line comments: See 3.3.1.1. (line 443) name: See 3.3.11. (line 1402) name, database: See 3. (line 292) no-preprocessor, --no-preprocessor option, introduced:See 3.3. (line 412) no-preprocessor, --no-preprocessor option, summary:See 3.4. (line 1750) no-transcript, --no-transcript option, summary:See 3.4. (line 1777) noauth, autologin keyword: See 6.4. (line 3422) nodebug: See 4.3. (line 2011) nosasl, autologin keyword: See 6.4. (line 3428) noshow-dictorg-entries: See 4.2. (line 1968) nosort: See 4.2. (line 1968) notrim-ws: See 4.2. (line 1968) open: See 6.2.1. (line 2905) open-db: See 4.3.3. (line 2167) operation modes of dicod: See 3.1. (line 345) OPTION MIME: See A.2.4. (line 3958) options, dicod.: See 3.4. (line 1723) outline dictionary: See 4.1. (line 1856) outline mode: See 4.1. (line 1849) outline module: See 4.1. (line 1844) output: See 4.3.3. (line 2256) PAGER: See 6.2.5. (line 3043) pager: See 6.2.5. (line 3043) password, autologin keyword: See 6.4. (line 3419) password-resource: See 3.3.3. (line 813) pidfile: See 3.3.2. (line 706) pp-setup: See 3.3.15. (line 1676) pragmatic comments: See 3.3.1.2. (line 452) prefix: See 6.2.8. (line 3155) preprocessor: See 3.3.15. (line 1665) preprocessor, --preprocessor option, summary: See 3.4. (line 1743) preprocessor, default: See 2.1. (line 202) prompt: See 6.2.8. (line 3163) protocol layer: See 1. (line 150) Python: See 4.4. (line 2517) python, configuration: See 2.4. (line 262) quiet: See 6.2.6. (line 3079) QUIT: See A.2.9. (line 4043) quit: See 6.2.8. (line 3188) quoted string: See 3.3.1.3. (line 528) realm, autologin keyword: See 6.4. (line 3441) resource, authentication: See 3.3.3. (line 812) restart procedure: See 3.1. (line 359) restarting dicod: See 3.1. (line 359) result-count: See 4.3.3. (line 2265) RFC 2229: See 1. (line 150) sasl, autologin keyword: See 6.4. (line 3425) Scheme: See 4.3. (line 1979) Scheme strategy functions: See 4.3.4. (line 2271) server-info: See 3.3.8. (line 1234) service, autologin keyword: See 6.4. (line 3437) SHOW DATABASES: See A.2.3. (line 3889) SHOW DB: See A.2.3. (line 3888) SHOW INFO: See A.2.3. (line 3918) SHOW SERVER: See A.2.3. (line 3935) SHOW STRAT: See A.2.3. (line 3903) SHOW STRATEGIES: See A.2.3. (line 3904) show-dictorg-entries: See 4.2. (line 1928) show-sys-info: See 3.3.5. (line 1010) shutdown-timeout: See 3.3.2. (line 736) SIGHUP: See 3.1. (line 353) SIGHUP handling: See 3.1. (line 359) SIGINT: See 3.1. (line 353) signals handled by dicod: See 3.1. (line 353) SIGQUIT: See 3.1. (line 353) SIGTERM: See 3.1. (line 353) simple statements: See 3.3.1.3. (line 500) single query mode: See 6.1. (line 2697) single-line comments: See 3.3.1.1. (line 435) single-process, --single-process option, summary:See 3.4. (line 1758) sort: See 4.2. (line 1938) source-info, --source-info option, summary: See 3.4. (line 1792) statement, block: See 3.3.1.3. (line 618) statement, simple: See 3.3.1.3. (line 500) statements, configuration file: See 3.3.1.3. (line 500) STATUS: See A.2.7. (line 4005) stderr, --stderr option, introduced: See 3.1. (line 377) stderr, --stderr option, summary: See 3.4. (line 1733) strategy <1>: See A.2.2. (line 3787) strategy <2>: See 6.2.2. (line 2957) strategy <3>: See 3.3.12. (line 1541) strategy: See 3. (line 340) strategy functions, Guile: See 4.3.4. (line 2271) strategy functions, Scheme: See 4.3.4. (line 2271) string, quoted: See 3.3.1.3. (line 528) string, unquoted: See 3.3.1.3. (line 524) syslog, --syslog option, summary: See 3.4. (line 1736) system information: See 3.3.5. (line 1014) terminating dicod: See 3.1. (line 366) termination procedure: See 3.1. (line 366) text authentication database: See 3.3.3.1. (line 838) tilde expansion: See 6.2.6. (line 3068) time formats, for --time-format option: See Appendix B. (line 4091) timing: See 3.3.13. (line 1593) trace-grammar, --trace-grammar option, summary:See 3.4. (line 1795) trace-lex, --trace-lex option, summary: See 3.4. (line 1799) transcript <1>: See 6.2.7. (line 3105) transcript: See 3.3.6. (line 1043) transcript, --transcript option, summary: See 3.4. (line 1766) trim-ws: See 4.2. (line 1946) two-layer model: See 1. (line 150) URL, authentication database: See 3.3.3. (line 778) URL, using to query DICT server: See 6.1.2. (line 2765) usage, --usage option, summary: See 3.4. (line 1815) user: See 3.3.2. (line 636) user-db: See 3.3.3. (line 776) utf8_char_width: See C.10. (line 4657) utf8_iter_end_p: See C.10. (line 4670) utf8_iter_first: See C.10. (line 4673) utf8_iter_isascii: See C.10. (line 4668) utf8_iter_next: See C.10. (line 4675) utf8_iterator: See C.10. (line 4661) utf8_mbstr_to_norm_wc: See C.10. (line 4714) utf8_mbstr_to_wc: See C.10. (line 4711) utf8_mbtowc_internal: See C.10. (line 4678) utf8_strcasecmp: See C.10. (line 4686) utf8_strlen: See C.10. (line 4659) utf8_strncasecmp: See C.10. (line 4689) utf8_symcasecmp: See C.10. (line 4684) utf8_symcmp: See C.10. (line 4682) utf8_tolower: See C.10. (line 4697) utf8_toupper: See C.10. (line 4693) utf8_wc_hash_string: See C.10. (line 4704) utf8_wc_strcmp: See C.10. (line 4706) utf8_wc_strdup: See C.10. (line 4701) utf8_wc_strlen: See C.10. (line 4699) utf8_wc_to_mbstr: See C.10. (line 4709) utf8_wc_tolower: See C.10. (line 4695) utf8_wc_toupper: See C.10. (line 4691) utf8_wctomb: See C.10. (line 4680) version: See 6.2.8. (line 3185) version, --version option, summary: See 3.4. (line 1818) virtual functions, guile module: See 4.3.1. (line 2053) visibility, database: See 3.3.11.1. (line 1480) visibility-acl: See 3.3.11.1. (line 1495) warranty: See 6.2.8. (line 3185) webalizer: See 3.3.7. (line 1187) XIDLE: See A.3. (line 4055) xlat_c_string: See C.12. (line 4753) xlat_string: See C.12. (line 4751) xlat_tab: See C.12. (line 4744) XLEV: See A.3. (line 4074) XVERSION: See A.3. (line 4066)