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

7.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 SVN repository by an automated mechanism, 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, omitting the various links which the ‘@node’ directive normally requires:

 
@node MySection
@section My Section Title

The repair occurs automatically within the SVN repository by an automated mechanism, however 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 ‘${builddir}/out/docs/’.

make apihtml

Generate HTML version of 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 apidevhtml

Generate HTML version of 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 manualhtml

Convert the Crystal Space manual to HTML format.

make manualdvi

Convert the Crystal Space manual to DVI format.

make manualps

Convert the Crystal Space manual to PostScript format.

make manualpdf

Convert the Crystal Space manual to PDF format.

make manualinfo

Convert the Crystal Space manual to GNU Info format.

make repairdoc

Repair all ‘@node’ and ‘@menu’ directives in the Texinfo sources.

make cleandoc

Delete all converted documents.

Directory Structure

The ‘CS/docs/texinfo’ directory contains:

Formatting Conventions

Here are some general formatting conventions.


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

This document was generated using texi2html 1.76.