Documentation

The DAISY Lion

For creating and maintaining localized versions of DAISY software products, the DAISY Lion contains the following:

I. [#mysqldb] II. [#web] III. [#dbtools] IV. [#dbmodules]

== I. The MySQL Database == #mysqldb

=== i. Connecting === #mysqldb-connecting

The database is called lionutf8 (if you have a different name, you can adjust your config file accordingly.)

How to connect to the database from the shell (assuming your IP has been authorized):

Your code looks like this:

Where the connect_to_db function takes these parameters:

user

 * '''admin''' (ALL permissions)
 * '''ro''' (SELECT)
 * '''rw''' (SELECT/UPDATE/INSERT/DELETE)

hostname

 * '''localhost''' 
 * '''92.243.13.151''' (Gandi)
 * If another server, then use that IP

dbname

 * '''lionutf8'''
 * or, whatever the name of the database

Note that with the current server (Gandi), your IP has to be authorized in order to connect from a local machine. Do the following:

=== ii. The Users Table === #mysqldb-userstable

Note that table ids cannot be hypenated, so while the language ID will be something like "eng-US", the corresponding table will be called "eng_US"

 username::
 	The user's login
 realname::
 	Their real name
 password::
 	Super-secret password.  Probably unencrypted.
 email::
 	How to contact this person
 langid::
   	The language that they're working on.  Uses the hyphenated form like "eng-US"
 lastlogin::
   	Date/time of their last login
 lastactivity::
   	The last time they did anything (useful for timeouts)
 sessionid::
   	Their session id

=== iii. The Application Table === #mysqldb-apptable

This table describes the application being localized.

 name::

The name of the application

 version::

The version of the application

 description::

A brief description of the application

 permanenturi::

The URI path to the online repository for external audio files (not including the language subfolder or filename)

 permanenturiparams::

The parameters for the permanenturi URI, which are appended to the URI string.

 website::

The application's home page

 addldocsuri::

A link to any additional documents that are part of the translation process.

 addldocsdesc::

A description of the additional documents

 translate_mnemonics::
        If true, mnemonics can be translated (if there are any.) This can be overridden at the language level.
 translate_accelerators::
        If true, accelerators can be translated (if there are any.) This can be overridden at the language level.
 logo::
        Path to the application logo file.
 comments::
        Comments for the translator, which will appear on the main task list page.

=== iv. The Languages Table === #mysqldb-langstable

This table contains a list of the languages in the database.

 langid::

The identifier for the language. Consists of the ISO language name code plus a hyphen plus the ISO country code. E.g. eng-US for U.S. English. Some languages may not require a country specification; they may be identified by the language code only. E.g. arb for Arabic or urd for Urdu.

 langname::

The human-readable name for the language.

 translate_mnemonics::
        If true, mnemonics can be translated (if there are any.) Overrides the value in the application table.
 translate_accelerators::
        If true, accelerators can be translated (if there are any.) Overrides the value in the application table.
 rtl::
        Indicates if this is a right-to-left script.  Otherwise it is assumed to be left-to-right.

=== v. A Language Table === #mysqldb-engUStable

All languages have their own table. Each is structured like this and named as the ID of the language with an underscore instead of a hypen.

Each row represents a text element from the amisAccessibleUi.xml file.

 id::

The internal table id, which is managed automatically by the database.

 textstring::

The text contents

 audiouri::

The path to the audiodata, relative to the language's repository directory. the audiodata gets moved here manually after the translation is done.

 textflag::

1 = ok; 2 = todo (marked by the translator); 3 = new (the corresponding english text is new/changed)

 remarks::

Comments from the translator

 xmlid::

The id on the text element in the XML file. Assumed to be unique in the database as well.

 role::

One of the following: "ACCELERATOR" | "MNEMONIC" | "MENUITEM" | "CONTROL" | "DIALOG" | "STRING"

 mnemonicgroup::

This number gives the group that the mnemonic belongs to (a group is a menu or dialog screen). Useful for detecting duplicates.

 target::

Gives the text id of the item that the mnemonic or accelerator is for

 actualkeys::

The programmatic keys for the shortcut or mnemonic. For example, the textstring would say "Espacio" in Spanish, but the actual key is still "Space"

 translate::

1 or 0; indicates whether the item should be translated or not.

 preserve::
        1 or 0; indicates whether this item will persist during a re-building of the table.  If 0, it will be erased.  If 1, it will survive.  

== The Web Interface == #web

 i. [#web-where Where]
 ii. [#web-starting Starting it up]
 iii. [#web-how How it works]

=== i. Where === #web-where

The web interface lives in daisylion/web It uses the daisylion.db.liondb.LionDB object, which in turn, requires the same [#dbmodule] as described above.

=== ii. Starting it up === #web-starting

Example (AMIS-specific):

You can also start the Lion with this command, but you have to specify two options:

 1. the application:  '''amis''' or '''obi'''
 2. the server configuration: '''local''', '''web''', or '''combo'''.

 local::

Use the lion_local.cfg file and run normally The lion_local.cfg file gives "localhost" as the db and web host.

 web::

Use the lion_web.cfg file and run in the background, even after you logout from the web server. The lion_web.cfg file gives the server IP as the db and web host. To stop the lion, kill the process.

 combo::

Use the lion_combo.cfg file and run normally. The lion_combo.cfg file gives the server IP for the db and "localhost" for the web host.

=== iii. How it works === #web-how

The startup scripts:

 1. '''start-lion-web''': specifies how to start the web app (local, web, combo)
 2. '''generate_config.py''': generate one of three possible configuration files (local, web, or combo)
 3. '''web-startup-wrapper''': a wrapper that: 1. uses the '''web''' configuration 2. redirects the output 3. keeps running if you log out

The main application:

 1. '''main.py''': starts cherrypy and brings up the login screen
 2. '''translatestrings.py''', '''chooseaccelerators.py''', '''choosemnemonics.py''': the users use these pages for editing translations

 3. '''translatepages.py''': base class for the files listed in !#2
 4. the '''lionweb/templates''' directory contains cheetah html templates

== III. Database scripts == #dbtools

In a folder called daisylion/db are tools for adding users/languages, adding/removing/changing master language table strings, exporting strings, and using module functions such as importing from XML or exporting to specific formats.

All the functions are exposed as command line scripts in the folder daisylion/scripts. Each script has its own documentation.

== IV. Application-specific modules for database I/O == #dbmodules

 i. [#dbmodules-info About Modules]
 ii. [#dbmodules-amis AMIS]
 iii. [#dbmodules-obi Obi]

=== i. About Modules === #dbmodules-info

 * Each module goes in its own subfolder of /daisylion/db/modules
 * Each module has a main class, which is a subclass of daisylion.db.modules.lion_module.LionIOModule
 * The name of this main class is given in the configuration file.  Edit /daisylion/generate_config.py and add to the static module section.  Follow this format:

Modules must override the following functions from LionIOModule:

 1. ''import_xml(self, session, file, langid, import_type)''

Import data from an XML file. The argument import_type gives the type of import desired by the user.

 2. ''get_removed_ids_after_import(self)''

After an import, get a list of all the IDs that were marked for deletion in the import file. This is important so the other tables can be updated.

 3. ''export(self, session, file, langid, export_type, output_folder = "")''

Export data. The argument export_type gives the type of export desired by the user.

=== ii. AMIS === #dbmodules-amis

First go to daisylion/db/modules/amis/templates and run the script called runmefirst. This small script will compile all the templates required for using the AMIS module. You only need to run this script one time.

Import

All input comes from the file amisAccessibleUi.xml. There are 3 import options:

 1. Import from XML and rewrite the whole table based on the XML file contents.  This does not preserve anything!
 2. Import from XML and just update text/audio for pre-exisiting items.  This option was created to accommodate translations done directly into the XML file, outside the Lion system.
 3. Import from XML and just update the audio for pre-existing items.  This option was created to import audio files from legacy translations.

Export

In addition to the standard Lion export options (string lists), there are 3 AMIS-specific export options:

 1. Export an amisAccessibleUi.xml file
 2. Export a Microsoft resource (RC) file
 3. Export a DAISY book containing all the keyboard shortcuts for AMIS