Copyright (C) 2008  Matteo Vescovi <matteo.vescovi@yahoo.co.uk>
_________________________________________________
Getting started with Presage in 5 minutes or less
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1) Download, build and install presage

Follow the instructions in the README file to install presage on
your system.




2) Run the demo program and the simulator

Presage is an extensible predictive text entry platform. It
provides a clean, simple application programming interface and a higly
configurable and extensible predictive framework in the form of a
library.

Presage is not an end-user application. However, a number of demo
applications are included:
- presage_demo: ncurses based demonstration program
- presage_demo_text: text based demonstration program
- presage_simulator: simulates predictive process and reports on
  predictive performance


2.a) presage_demo 

This demo displays the text entered so far in the top window that
stretches across the screen.  The current prediction is displayed
immediately underneath the text window, at the leftmost position.
Previous predictions are displayed in cronological order to the right
of the current prediction.  Subsequent predictions are displayed in
the lefmost position, and previous predictions are shifted to the
right, so that the current prediction is always on the left hand side.

Context switches are marked in some way (either a vertical bar or a
box enclosing the other prediction boxes). [not implemented yet]


2.b) presage_demo_text

This demo works similarly to presage_demo, except that it is much
more barebones. It is useful when debugging.


2.c) presage_simulator

This simulator evaluates the performance of the predictive engine on a
given text file.

The simulator requires a text file to be passed as argument. It reads
each character from the input file and sends it to the presage
prediction engine. The simulator counts the number of key presses
required to enter the desired text using the presage prediction
engine and the number of key presses required to enter the same text
with no prediction enabled.

At the end of the simulation, it generates a report on predictive
performance (expressed in terms of Keystrokes Savings Rate) and prints
it to standard out.




3) Tweak presage to your needs


3.a) presage.xml

Presage is extensible and configurable. Presage's extensibility
comes from a range of predictive mechanisms used to generate
predictions. You can decide what plugins to enable and what predictive
resources to tie those plugins to. All configuration variables can be
controlled by editing the XML configuration file (either
~/.presage.xml or presage.xml in the etc/ directory where
Presage was installed - usually /etc -, whichever is found first).

Feel free to experiment with different settings: try enabling
different plugins, or changing individual plugins configuration
values. presage.xml comes with comments describe what each
configuration variable is about.


3.b) text2ngram

If you wish to improve presage's predictive performance, or you
want presage to predict in your native language, you will need to
generate resources required by the predictive plugins. Currently, most
predictive plugins are statistical plugins which require an n-gram
database.

You can easily generate an n-gram database suitable for consumption by
presage's plugin with the included text2ngram tool. Feed your
collection of text in your native language or domain-specific text to
text2ngram and generate customized predictive resources to improve the
quality and accuracy of the predictions.




4) Write a program that uses presage

Below is a simple program that demonstrates how to use the C++
interface to presage.

<code>
#include "presage.h"
#include <iostream>

/* Simple example callback that tracks past context with a string.
 *
 * Using a callback object decouples the user application from the
 * chosen text buffer (which could be a simple string, a graphical
 * text widget, a file stream, etc.) and frees the caller from having
 * to explicitly notify of any updates to the context. Presage will
 * invoke on the callback whenever access to contextual data is
 * required.
 *
 */
class ExampleCallback : public PresageCallback
{
public:
    ExampleCallback(const std::string& _past_context) : past_context(_past_context) { }

    std::string get_past_stream() const { return past_context; }
    std::string get_future_stream() const { return empty; }

private:
    const std::string& past_context;
    const std::string empty;

};

int main(int argc, char** argv)
{
    std::string context;
    ExampleCallback callback(context);
    Presage presage(&callback);
    
    std::string buffer;
    std::vector< std::string > predictions;

    for (;;) {
	// prompt user and append line into context buffer
	std::cout << "> ";
	getline(std::cin, buffer);
	context += buffer;

	// request prediction
	predictions = presage.predict ();

	// print predictions
	for (int i = 0; i < predictions.size(); i++) {
	    std::cout << i << ':' << predictions[i] << std::endl;
	}
    }

    return 0;
}
</code>

This program creates an instance of Presage and prints the
predictions generated by presage to screen after each text fragment
input by the user.

The instructions to watch for are on the first line in main() which
initializes presage and on line 21 which tells presage what text
the user entered and asks presage to generate a prediction.

Presage's API includes other methods, all accessible through the
Presage class, defined in presage.h.


########/

Copyright (C) 2008  Matteo Vescovi <matteo.vescovi@yahoo.co.uk>

Presage is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

########\
