[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1 Writing Documentation

This section contains guidelines and instructions for writing documentation for the Crystal Space project. Read this section if you are interested in contributing to the documentation project.

These guidelines deal with subdivision of the documentation into files, into chapters and sections, and with node placing and linking. To understand this document, you should know that 'chapters' is the general division of a Texinfo file into several parts, and 'sections' is the next subdivision. TOC means "Table of Contents". "folder" and "directory" have the expected meaning.

Please follow these guidelines when writing documentation for Crystal Space.

General

Write documentation using the Texinfo mark-up language. You can get more information at http://www.texinfo.org.

The documentation is converted from Texinfo to other formats, such as HTML. Conversion to most important formats happens automatically within the CVS repository, so you only have to commit the Texinfo docs if you make any changes.

To make writing the documentation easier, `@node' and `@menu' directives in the Texinfo sources can be repaired, which means that the links to the previous, next and top nodes are generated automatically. So you can safely write the following line, ommitting the various links which the `@node' directive normally requires:

 
@node MySection
@section MySection

The repair occurs automatically within the CVS repository on a daily basis. You can also repair the files manually if you use the GNU makefile system by invoking the following command:

 
make repairdoc

Conversion and Maintenance via Makefile Targets

If you are using the GNU makefile system, you can use the following makefile targets to convert the Texinfo documents to different formats. The output will be placed in subdirectories of `CS/out/docs/'.

make pubapi
Create public API reference via Doxygen. This is the reference manual for people using Crystal Space in their own projects. It only documents public classes and functions.

make devapi
Create developer API reference via Doxygen. This is the reference manual for people actually working on Crystal Space itself. It documents all classes and functions.

make htmldoc
Convert the user's manual to HTML format.

make dvidoc
Convert the user's manual to DVI format.

make psdoc
Convert the user's manual to PostScript format.

make pdfdoc
Convert the user's manual to PDF format.

make infodoc
Convert the user's manual to Info format.

make repairdoc
Repair all `@node' and `@menu' directives in the Texinfo sources.

make cleandoc
Delete all converted documents.

Manual Conversion

Manual conversion to HTML is done with the Perl script `texi2html'. This script is already included in the Crystal Space package in the `CS/bin' directory. If you are using the GNU make system, then you can run the script by invoking the `htmldoc' makefile target.

 
make htmldoc

If you do not use the GNU makefile system, then you can run the script manually with the following line. This example assumes that your current working directory is `CS/'.

 
mkdir out
mkdir out/docs
mkdir out/docs/html
cd docs/texinfo
perl ../../bin/texi2html -init_file \
  ../support/texi2html.init -prefix cs \
  -subdir ../../out/docs/html cs-unix.txi

The `-subdir' option controls where the output files are placed. Replace `cs-unix.txi' by `cs-dos.txi' or `cs-mac.txi' for Windows/DOS or Macintosh (HFS) systems, respectively.

Directory Structure

The `CS/docs/texinfo' directory contains:

Formatting Conventions

Here are some general formatting convensions.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated using texi2html