====
YABT
====

Contents
========

1. `Introduction`_
2. `Installation`_
3. `Included scripts`_
4. `Documentation`_

Introduction
============

Welcome to YABT written by Michael Whapples. This document is to get you started with 
YABT and to point you in the direction of further documentation should you need it.

What is YABT
------------

YABT is a general translation system written in the python programming language. It is primarily written for Braille 
translation, but due to its general design, it should be possible to use it for other purposes such as preparing text 
for input to a speech synthesiser, or even other uses not imagined by the author.

What YABT is not
----------------

YABT is primarily designed as a translation library to be used by other applications, so is not meant to be a complete 
document translator for use by end users. Particular things YABT is not designed to do which make it unsuited for being 
a complete document translation solution is that it will not perform any formatting of its own, it will only translate 
the information  contained in the original text so maintaining the original formatting. Things such as formatting which 
YABT is unsuited to should be controlled by applications using YABT.

Current development status
--------------------------

This version of YABT is a beta release, so anyone who wishes to use YABT should be aware that YABT is still being 
developed. This means that the API may be subject to some changes, although attempts will be made to keep these to a 
minimum. Should authors wish to ensure that changes in YABT do not break their applications they are encouraged to use 
the version matching in setuptools to specify which versions work, so that users of their applications will only use 
versions of YABT which have been tested by the application developers.

License
-------
YABT is released under the RPL, but this may be relaxed in the future should a more suitable license be found. A full 
copy of the license can be found in the file LICENSE included in the source distribution of YABT.

Contact details
---------------

You can contact the author by emailing `mwhapples@users.berlios.de <mailto:mwhapples@users.berlios.de>`_. The YABT 
website now can be found at `http://yabt.berlios.de <http://yabt.berlios.de>`_.

Installation
============

YABT is written in the python programming language, so will need `python <http://www.python.org/>`_ installed. YABT 
has been written with python 2.5, but it may work with other versions of python, although this is not guaranteed. YABT 
uses setuptools for distribution so the easiest way to install YABT is to install setuptools and run the command 
``easy_install YABT``. This will manage all dependencies for you, so this is all you should need to do. There is one 
package, `psyco <http://psyco.sf.net>`_, which you may wish to install. Psyco is not a dependency of YABT so is not 
installed automatically, but will improve the performance of YABT significantly so is strongly recommended. If there is 
no version of psyco for your system, do not worry, YABT will still function correctly, it just will not run quite as 
fast as it might.

Should you wish to install from source, then you don't need to have setuptools installed as the setup script will 
install it should it be missing. All you should need to do to install from source is to run ``python setup.py install`` 
in the base directory of the source distribution. Please note if you obtained the YABT sources from the mercurial 
repository then you will need hg.setuptools which can be found at `pypi <http://pypi.python.org/pypi/hg.setuptools>`_ 
otherwise setuptools will be unable to work out what files are part of the distribution.

Included scripts
================

YABT comes with one script to perform a translation. The script name is ``YABT_translate``. For details on 
``YABT_translate`` please give it the ``--help`` option. ``YABT_translate`` takes a file on the command line and prints 
the translated version to standard out.

Documentation
=============

More detailed documentation can be found in the docs directory of the YABT source distribution. All the documentation in 
the docs directory and this file are written in the RST format, so can be converted to other formats (eg. HTML). Any 
examples of using YABT in the documentation in the docs directory is suitable for use with doctest and is checked when 
``python setup.py test`` is run.


