====
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 context sensitive string manipulation tool written entirely in the python programming language. YABT has two main aims:

* To provide a translation library to be used with in other applications. The exact translation performed depends on what rules are used in the translator. Currently YABT is shipped with a translation system which uses a finite state machine and context matching along with a table for translating text into British Braille, although other translation systems should be possible to develop and other uses could be found by creating alternative tables (eg. a table could be created for preparing text for a speech synthesiser).
* The other use is to develop other translation systems which can be used by any application using YABT. This side of YABT has not been fully explored and is likely to develop and change over time.

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, in the past it was required that you should have hg.setuptools installed, this is no longer the case and you 
would be recommended to remove it. This has been changed as it was found that hg.setuptools did not seem to behave well 
when using a source distribution so this is why the alteration and the recommendation to remove it has been made.

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

YABT comes with one script to perform a translation. The script name is ``yabt-trans``. For details on 
``yabt-trans`` please give it the ``--help`` option. ``yabt-trans`` takes a file on the command line or input from 
standard input 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.


