Okapi Framework - Developers Notes

IMPORTANT NOTICE - Apr-30-2009:
This .NET implementation of Okapi is no longer actively developed.
Instead, a NEW JAVA IMPLEMENTATION IS AVAILABLE and is being actively developed.
The material on this Web site is for archive propose. Some applications of the old .NET implementation (e.g. Olifant) will be maintained to some degree until they have a replacement in the Java project.

Testing

Test Suite for Microsoft .NET

Each release of the Okapi tools comes with an automated test suite that you can run to verify if your installation works as expected. The test suite does not test every parts of the tools, but it exercises many of its components allowing to spot many potential issues.

To run the test suite:

Install the latest Rainbow release.
Download the latest Test Suite.
Unzip the TestSuite-RNNNNN.zip file in a folder called C:\Okapi\Data\Test (the batch files expect this location)
Run the file _00_RunEverything.bat located in that folder.
When the tests are done look at the The CMP_*.txt files for errors.
See the ReadMe.txt file in the package for more information.

To remove the test suite, simply delete the C:\Okapi\Data\Test folder.

Tests for Mono .NET

There is a small set of test files for the Mono distribution. To run it:

Go the the directory where you have installed the Okapi package.
Go to the sub-directory Shared\Samples\Mono
Make sure to set the Okapi assemblies accessible, for example if working with bash, use the following command:
export MONO_PATH=$MONO_PATH:/usr/local/OkapiMono/Shared/Assemblies
The run the Extraction.sh script.

Your Own Testing

In addition to running the test suite, you can also run your own tests. This is very important for Okapi's developers because you will be doing things they have not thought of. Make sure to report any issue, suggestion, etc.

Text Rewriting

One of the best way to test any filter is to use the Text Rewriting utility with the option Keep the original content. This allows you to generate a copy of the input files that will show you the differences between the original input file and the output file after being gone through the filter.

You can then compare the input and the output file with a comparison utility such as CSDiff, Beyond Compare, Windows' comp tool, or any other similar program. Keep in mind that some filters have different options for the output, and the default ones may not be the one generating the output as close as it could be from the original.

Text Extraction to RTF

Another efficient test for the filters is to use the Text Extraction utility with the output format set to Original format + RTF layer. This will create a first output file in RTF. There you can visually check for issues with inline codes, text to be translated that is not identified, missing text, etc. Then you can then use the RTF Conversion utility on that file to remove the RTF layer and generate a second output that you can compare with the original input file.

Text Extraction to XLIFF

A third way to test filters is to use the Text Extraction utility with the output format set to XLIFF (XML Localisation Interchange File Format). This will generate an XLIFF output, where you can verify some special information (not necessarily visibly recognized in an RTF output) has been processed correctly: things like resname, restype, etc. The _Merge.bat batch file generated during extraction allows you to easily use the Text Merging utility to re-create the merged file. Here again, you can compare this output with the original input.

Source Code Access

Snapshots of the source code corresponding to releases can be download from the SourceForge.net Files Release System.

All the files of the Okapi Framework (including source for help, etc.) is accessible from the CVS repository. SourceForge.net maintains two CVS servers: The first one is the development server, the second one is for all other CVS services (including Web browsing).

The content of the Web server can be seen here: http://okapi.cvs.sourceforge.net/okapi/Okapi/. Be aware that sometimes it takes a few hours for the change in the development server to be reflected on the Web server.

As for development server: it is not visible through the Web. You need a CVS client application to access it. If you are running Windows, you can use TortoiseCVS (tortoisecvs.sourceforge.net).

Here are the instructions on how to get the inital source code from the development server using TortoiseCVS:

Make sure you have an account on SourceForge.net, and that you have been added as a developer to the Okapi project.
In Windows Explorer go to the folder where you would like to check out the code.
Right click and from the context menu choose the command CVS Checkout it's next to the Tortoise icon.
Fill in the dialog as follows:
- Protocol: Secure Shell (:ext)
- Server: okapi.cvs.sourceforge.net
- Directory: /cvsroot/okapi
- Username: <your SourceForge.net username>
Click the Fetch List button to get a choice of modules. You will need to enter your password in the dialog at this point. Then pick the module that you would like.
Click OK. TortoiseCVS will now check out the code. You will need to enter your password.

You should have now all the Okapi directory structure and files.

If you are part of the Okapi Development Team and need to integrate the changes you have made select the CVS Commit from the context menu on the top level folder to copy your changes in the repository. See TortoiseCVS help manual for more details.

Source Code Documentation

Some of the .NET library modules have online help for the developers:

Okapi .NET Library Overview

Build Tools

This section lists the different tools you may need to build the Okapi Framework software and help:

.NET Implementation

The .NET parts of the Okapi Framework are built for the Microsoft .NET Framework version 2.0 (version 1.1 for the releases prior Release 9). In order to compile the source code you need to have Microsoft .NET SDK (freely available) installed on your machine.

For editing the source code, if you do not have a development environment such as Microsoft Visual Studio, you can use one of the open source IDEs for C# projects. One that is fairly robust and effective is SharpDevelop (sharpdevelop.sourceforge.net).

The build for the Microsoft .NET platform should run on the Mono .NET platform as well. There are a few specialized methods like Routines.IsMono in the Base library that help if conditions are needed at runtime.

Help and Web Site

The source code documentation is generated from the special comments in the source files using NDoc (ndoc.sourceforge.net) a documentation generator utility.

Parts of the help and Web site are generated using a tool called BlockMerger, provided with the distribution. It uses XSLT templates, so you need an XSLT processor to build the Web site. You can use Microsoft MSXSL (freely available).

Compression

Some of the build processes use ZIP as output. You need to have a command-line ZIP creation tool. The project uses 7zip (sevenzip.sourceforge.net).

Localization

All Okapi the components and tools are internationalized and can be localized in any of the languages supported by the .NET platform.

If you wish to localize a component or an application of Okapi contact the project administrator.