|
|
Implementation |
|
| Home | Project Documentation | Mailing Lists | Site Map |
In this section we describe the actual implementation of our documentation system. The section is organized as follows:
Section 3.1 describes the layout of the documentation sources.
Section 3.2 describes our approach to the problem of representing indian language text for which no well-known encodings exist.
Section 3.3 describes the process of installing and using the documentation tool-chain.
TODO:
TODO: describe the issues involved, solution settled on.
A description of project specific extensions to DocBook. TODO.
The document processing tool-chain transforms SGML sources into the desired output format.
The basic transformation engine is jade, a DSSSL engine. Given a DocBook document and a DSSSL stylesheet jade applies the transformation specified in stylesheet to produce the desired output. This process is depicted pictorially in Figure 2.
Figure 2. The Document Processing Tool-chain
DSSSL Downloadable
Stylesheet /-------------> documentation
| | packages
| |
DocBook ----> DSSSL -----> Output ----> Postprocessing ----> Website
Source Processor Format (Webmake/TeX)
(jade) (HTML/tex/...)
The major components of the toolchain are:
The DSSSL processor jade, or its derivative openjade.
Dave Raggett's HTML Tidy tool used to clean up generated HTML.
Norman Walsh's modular DSSSL stylesheets for transforming DocBook SGML to various formats.
Various DTDs: DocBook, LinuxDoc, HTML, XHTML, and the ISO 8879 character entity definitions.
peps, a utility to render encapsulated postscript files.
netpbm, a toolkit for manipulating graphics images in different formats.
xsltproc, a tool to transform XML.
teTeX, a popular package of the TeX typesetting engine.
The jadetex macro package allowing jade's output to be typeset by TeX.
In this section we describe how the requisite documentation tool-chain is installed.
Installation instructions are naturally specific to the operating system under which the tool-chain will run. We describe the procedure for installing the tool-chain on a few popular operating systems.
If the operating system you use is not in the list below, Section 3.3.1 lists the individual programs that make up the tool-chain. You could individually install these. Please do let us know if you do this, so that we can add instructions for your favorite OS to this documentation.
The Indic-Computing project provides a FreeBSD ``port'' skeleton mechanism that provides a convenient way to build and install the necessary tool-chain under FreeBSD.
Note: This procedure assumes that you have a checked out copy of the FreeBSD ports tree under /usr/ports and that you have access to the Internet for the build process to retrieve sources. More information on administering ports on your FreeBSD system can be found in the Installing Applications chapter of the FreeBSD Handbook.
Source builds of the toolchain under FreeBSD
Retrieve the port skeleton from SourceForge
Use the download manager web page on SourceForge to download the latest file release doc-toolchain-freebsd- version -port.tgz in the ``documentation-toolchain'' package.
You can directly fetch this file from one of SourceForge's download servers, as shown in the example below.
% fetch http://prdownloads.sourceforge.net/indic-computing/doc-toolchain-freebsd-1.0-port.tgz
Unpack the archive
Unpack the downloaded archive.
% tar -xvzf doc-toolchain-freebsd-1.0-port.tgz
Change working directory
Change your working directory to the newly unpacked directory.
% cd doc-toolchain/freebsd/
Become super-user
Change your privilege level to root .
% su
Password: *******
#
Build and Install the toolchain
Building the entire toolchain and installing it on your system is automated by a single make install command.
# make install
In this section we describe how to install the pre-built packages that comprise the Indic-Computing documentation toolchain under FreeBSD.
Note: This procedure assumes that you have a repository of pre-built packages on-hand, (typically a CD-ROM mounted on /cdrom ) or that you have access to such a repository on the Internet.
Binary installation under FreeBSD
Retrieve the toolchain package from SourceForge
Use the download manager web page on SourceForge to download the latest file release doc-toolchain-freebsd- version -pkg.tgz in the ``documentation-toolchain'' package.
% fetch http://prdownloads.sourceforge.net/indic-computing/doc-toolchain-freebsd-1.0-pkg.tgz
On successfull completion of this step, you should have a file named doc-toolchain-freebsd-pkg.tgz in the current directory.
Become super-user
Change your privilege level to root .
% su
Password: *******
#
Invoke pkg_add
Invoke pkg_add to install the application and its dependencies.
# pkg_add -R -f doc-toolchain-freebsd-pkg.tgz
The -R option to pkg_add
informs the system to not register
this package in the system package database. This is necessary to avoid confusing certain
third-party package maintenance tools like portupgrade.
In this section we describe how to install the documentation tool-chain under the Debian Gnu/Linux operating system.
Under Debian, the apt package provides tools to install, upgrade and remove packages in a convenient manner. For example, if you use a command such as:
# apt-get install docbook
then, the apt system will check its database for dependencies
or conflicts with other packages and will allow you to install a coherent set of packages
in one go. The rest of this install procedure assumes that you have the apt package installed on your Debian installation. Further information about apt, may be found at http://www.debian.org/doc/manuals/apt-howto/index.en.html.
Note: We are currently working on a convenient way to compile and install the necessary toolchain packages from source. For now, Section 3.3.2.2.1 describes how to install pre-built binaries of the documentation toolchain's components.
In this section we describe how to install, under Debian GNU/Linux, the pre-built packages that comprise the Indic-Computing documentation toolchain,
Note: The installation procedure can be speeded up if you have the primary Debian install media (DVD disks or CDROMs typically) at hand. This procedure assumes that you have access to the Internet from the machine where you are attempting the installation.
Binary installation under Debian GNU/Linux
Retrieve the toolchain package from SourceForge
Use the download manager web page on SourceForge to download the latest file release doc-toolchain-debian- version - arch .tgz in the ``documentation-toolchain'' package.
On successfull completion of this step, you should have a file named doc-toolchain-debian-0.5-i386.tgz in the current directory.
Unpack the archive
Unpack the downloaded archive.
% tar -xvzf doc-toolchain-debian-0.5-i386.tgz
Change working directory
Change your working directory to the newly unpacked directory.
% cd /usr/local/doc-toolchain/debian/
Become super-user
Change your privilege level to root
% su
Password: ****
#
Configure the apt package
Edit the file /etc/apt/sources.list . On a typical system this file would contain lines similar to the following:
deb cdrom:[Debian GNU/Linux 3.0 r1 _Woody_ - Official i386 Binary-4
(20021218)]/ unstable contrib main non-US/contrib non-US/main
deb cdrom:[Debian GNU/Linux 3.0 r1 _Woody_ - Official i386 Binary-3
(20021218)]/ unstable contrib main non-US/contrib non-US/main
deb cdrom:[Debian GNU/Linux 3.0 r1 _Woody_ - Official i386 Binary-2
(20021218)]/ unstable contrib main non-US/contrib non-US/main
deb cdrom:[Debian GNU/Linux 3.0 r1 _Woody_ - Official i386 Binary-1
(20021218)]/ unstable contrib main non-US/contrib non-US/main
Add the following lines to the very end of this file, to inform apt of the locations for Indic-Computing related packages.
deb file:/usr/local/doc-toolchain/debian/debs/
deb-src file:/usr/local/doc-toolchain/debian/deb-src/
Do not remove the trailing slash "/" in the path name of each "deb" listing.
Invoke apt-get
Invoke apt-get to install the documentation tool chain and its dependencies.
# apt-get install doctoolchain
When this command completes successfully, you should have the necessary tools to build Indic-Computing documentation on your system.
In this section we will describe the processing of editing documentation in this system.
At the end of reading this section you should:
Be able to checkout a copy of the current documentation sources from the repository on SourceForge (Section 3.3.3.1).
Understand how to edit the documentation (Section 3.3.3.2).
Know how to invoke the toolchain to build the documentation (Section 3.3.3.3).
Understand how to view the resulting output (Section 3.3.3.4).
Be able to submit your modifications back to the Indic-Computing project (Section 3.3.3.5).
Use the cvs checkout command to access the documentation repository on SourceForge. Detailed instructions on how to do this are present at the project's CVS Repository page. An example session is show below.
% cvs -d:pserver:anonymous@cvs.indic-computing.sourceforge.net:/cvsroot/indic-computing login
CVS password:
% cvs -d:pserver:anonymous@cvs.indic-computing.sourceforge.net:/cvsroot/indic-computing co doc
Note: If your machine is behind a firewall of some sort, you will need to modify the procedure shown above to access SourceForge through it.
SGML documents are ``plain text'' and are editable by nearly every editor. For example, the standard unix text editor vi is quite enough to edit these source documents.
EMACS users can use the PSGML customization package to provide very convenient editing for SGML documents.
Invocations of the tool-chain are best doing using make. You can invoke make at any level of the directory tree. The controlling makefile is setup to automatically do the right thing.
For example, building the complete documentation (including all translations) can be accomplished by running make inside the top-level doc/ directory.
% cd doc
% make
Note: The make program used here is BSD make. On some GNU/Linux systems this is named bmake and on others as bsdmake. The recommended way to build our documentation on GNU/Linux systems is to install and use the toolchain package appropriate to the variant of GNU/Linux that you use. Instructions on downloading and using the pre-packaged documentation toolchain may be found in Section 3.3.2.
You can view the output using the viewer appropriate for the output format selected (e.g. xpdf or acroread for PDF files and a web browser like links or Netscape for HTML output).
% netscape article.html
Once you have successfully edited and built your changes, you should submit the changes to the project.
Submitting changes
Create a patch
Create a patch against the checked-out documentation source tree. If you had modified article.sgml in the sources, you would do:
% cvs diff -u article.sgml > /tmp/diff
Submit the patch
Use SourceForge's patch manager to submit your patch along with a short description of what you have changed (and why).
One of our project developers will respond to you in a few days.
This, and other project documentation, can be downloaded from [ http://indic-computing.sourceforge.net/documentation.html ].
|
Copyright © 2001--2009 The Indic-Computing Project. Contact: jkoshy |
View document revision history
|