FD Tool
====

The `fd_tool`and its accompanying scripts in this directory are able to set up
everything required to

-   release dictionaries
-   access out-of-VCS auto-imported dictionaries
-   generate the FD API

As a dictionary developer, you don't need to care about this. :)

Installation
---------

Create a virtual environment for FreeDict and execute in this directory

    pip install .


Configuration
-------------

The utilities require a configuration file with a few options set. Open or
create a configuration file in `$HOME/.config/freedict/freedictrc` in your
favourite editor and enter something like
this:

    [DEFAULT]
    file_access_with = sshfs
    [release]
    user=SFACCOUNT,freedict
    [generated]
    user=USER

-   `file_access_with`: sets the file access strategy; possible values are
    unison or sshfs, default is unison 
    -   unison: synchronisation of all files to local disk -- quicker
        operations, more initial download
    -   sshfs (UNIX only): direct access over a network connection, slower
        actions and problematic, since direct file manipulation
-   `[release]`: server on which to look for the released dictionaries, by
    default freedict.org.
-   `[generated]`: this configures account information for the file services
    containing all auto-generated dictionaries

This minimal configuration should be enough for most of the use cases. For a
more in-depth explanation, you should visit the
[wiki page](https://github.com/freedict/fd-dictionaries/wiki/FreeDict-HOWTO-%E2%80%93-FreeDict-Build-System).
There is a freedictrc.example in this directory, too.


API Generation
--------------

The API generation consists of two steps. In the first step, remote files are
made available, in the second, the actual XML file is generated.

Remote files are all released files and the auto-imported dictionaries. In order
to make them available, either SSHFS or Unison can be used. This can be
configured in the FreeDict configuration, see <ToDo, Chapter 9 of HOWTO>. The
`file_manager` will take care of doing this work, transparently.

The API generation requires the `FREEDICT_TOOLS` environment variable to be set.
Information about this variable can be found
[here](https://github.com/freedict/fd-dictionaries/wiki/FreeDict-HOWTO).\

The invocation of the API generator is automated in the make rule `api`, so in
most cases, `make api` should be enough.


File Management
===============

Fsetup is designed to set up the environment for managing and releasing FreeDict
dictionaries, as well as generating the  API. This mainly involves copying (or
remote-mounting) released dictionaries and out-of-VCS (auto-imported)
dictionaries.


