
/*  $Header: /cvs/gnome/GSAPI/README,v 1.1.1.1 2003/08/01 15:17:00 richb Exp $
 *
 *  Copyright (c) 2002-2003 Sun Microsystems, Inc.
 *  All Rights Reserved.
 */

GNOME Speech 0.6.x.
===================

Introduction.
-------------
The GNOME Speech API (GSAPI) allows developers to incorporate speech 
technology into user interfaces for their GNOME applications. This API 
specifies a cross-platform interface to support command and control 
recognizers, dictation systems and speech synthesizers. 

It has been heavily influenced by the Java Speech API (see:
http://java.sun.com/products/java-media/speech for more details).

This GSAPI release is just a specification, not an implementation.
The plan is to release it to the GNOME community for review. From
feedback provided by reviewers and our attempts to implement the API
as defined, the specification will be refined until it provides a
clean and consistent API. This will then be GNOME Speech v1.0.

Please send questions and comments about this specification to either
the authors (as listed in the AUTHORS file), the Desktop Development
mailing list (desktop-devel-list@gnome.org) or the GNOME Accessibility
mailing list <gnome-accessibility-list@gnome.org>

Note that there is currently already a gnome-speech CVS module on
cvs.gnome.org. This provides a simple text-to-speech (TTS) API that 
provides sufficient support to allow the gnopernicus screen reader to 
function appropriately. For now, the GSAPI GNOME Speech module is being
kept as a separate entity to avoid confusion.


Files Provided.
---------------
The distribution consists of three main sub-directories:

1/ .../GSAPI-0.6.0/idl

   These are four IDL files under here that define the GNOME Speech 
   0.6.x API:

   GNOME_Speech_Recognition.idl - interfaces for speech recognition.
   GNOME_Speech_Synthesis.idl   - interfaces for text to speech.
   GNOME_Speech.idl             - interfaces common to both.
   GNOME_Speech_Bonobo_Defs.idl - Bonobo interfaces used by GNOME Speech.


2/ .../GSAPI-0.6.0/doc

   This is HTML documentation for the GNOME Speech API, automatically 
   generated from JavaDoc style comments in the IDL files. A good place to 
   start, is to look at

   .../GSAPI-0.6.0/doc/index.html

   in your web browser.

3/ .../GSAPI-0.6.0/idl/gnome-IDL-for-doc-gen

  This directory contains special versions of the Bonobo and Bonobo
  Activation IDL header files that don't have variables that conflict
  with reserved CORBA keywords (see bugzilla bug #118078 filed on this
  problem).


Rolling Your Own.
-----------------
As it currently stands, the HTML documentation is generated by open-source
tools that are not a standard part of the GNOME distribution. These are:

  Synposis - http://synopsis.sourceforge.net - version 0.5
  OmniORB  - http://omniorb.sourceforge.net  - version 4.0.1
  Graphviz - http://www.graphviz.org         - version 1.9

You will need to download and install these tools if you wish to regenerate 
the HTML documentation.

A script (.../GSAPI-0.6.0/idl/gendoc.sh) has been provided that shows
how to do this assuming these tools have been installed in their default 
locations.
