Indic-Computing Documentation Infrastructure

Joseph Koshy

The Indic-Computing project

$Date: 2004-01-10 21:09:40 +0530 (Sat, 10 Jan 2004) $

Documenting Indian languages in a manner accessible to wide audience turns out to be a challenging problem without a straightforward solution. This article describes the documentation system adopted by the Indic Computing project. We describe the design of the system along with its strengths and weaknesses. A description of how the project website is synthesized from its components is provided. Installation and use of the documentation system are covered.

The interested reader should be able to read this document and be able to contribute to the project or be able to reuse this infrastructure for her needs.

Table of Contents
1 Introduction
2 Design Goals
3 Implementation
4 The Project Website
5 Additional Reading

1 Introduction

The Indic-Computing project is attempting to bring together and make widely available, information on indian languages in a form useful to software developers.

Documenting indian languages for a wide range of platforms is a challenging task today, since the available platforms vary widely in their ability to support indian languages.

This document describes the documentation system being used by the Indic-Computing project. We describe the design of the documentation system including the tradeoffs that we had to make in its implementation. Installation and use of the system are covered, and the generation of the Indic-Computing website from its components is touched upon.

In keeping with the open-source nature of the Indic-Computing project, the infrastructure described in this document is public, viewable and re-usable by all.

1.1 Who should read this document?

The target audience for this document includes:

people interested in contributing to and improving the Indic-Computing project's documentation and who wish to know how the documentation is managed
developers interested in re-using our infrastructure for their own needs, perhaps for similarly documenting other linguistic information around the world

1.2 Prerequisites

Readers interested in the overall architecture of the documentation system should be able to read and understand this document. Section 2 covers the overall architectural decisions.

For readers seeking a deeper understanding, familiarity with the basic concepts behind structural markup (SGML) would help.

Readers wishing to dive into editing and creating Indic-Computing documents will require additional skills:

experience with DocBook, the popular SGML DTD.
experience with program development in unix-like environments.

In particular, the build system uses make, jade, TeX, PERL, Python and other tools available on open-source unix-like platforms.
tracking ongoing development of documentation requires familiarity with CVS the source control tool used by the SourceForge™ collaborative system.

Section 5 provides references for further reading.

1.3 Goals of this document

After reading this document you should:

have an understanding of the issues involved in documenting and displaying languages on systems that do not support them
understand how the current infrastructure attempts to solve these problems
understand how to create new documentation for the project
understand how to modify existing documentation
understand how to replicate this infrastructure to solve a similar need.

1.4 Structure of this document

The rest of this document is organized as follows:

Section 2 discusses the designs goals for this infrastructure and the choices that arose from these goals.
Section 3 discusses the (current) implementation of our documentation infrastructure.
Section 4 discusses the Indic-Computing website and how it is constructed from its components.
and finally, Section 5 refers you to additional reading that would help in using this infrastructure better.

		Next
		Design Goals