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:

• A table-of-contents file named `cs.txi'. This is the platform-independent root of the entire documentation hierarchy.
• Platform-dependent configuration files, such as `unixdef.txi', `macdef.txi', etc.
• Platform-dependent wrapper files, such as `cs-unix.txi', `cs-mac.txi', etc. These are the platform-specific root files for the entire documentation hierarchy. They import the platform-dependent configuration (i.e. `unixdef.txi' and then the TOC file `cs.txi'.
• Other configuration files, like `version.txi', `cpyright.txi', etc., and helper files for conversion to other formats, like `texinfo.tex'.
• One subdirectory for each chapter. Each chapter directory contains at least one file called `chapter.txi', which is the root import file for this chapter. The TOC file will only include `chapter.txi', which then includes one file in this directory for every section.

  If one section in a chapter is too big for a single file, this section is split into several files by subsections. These files are again often placed into a subdirectory.

Formatting Conventions

Here are some general formatting conventions.

• When creating @itemize lists, one blank line should separate each @item except for short lists of items with short descriptions. Also remember to use the @bullet directive after the @itemize directive, as in @itemize @bullet.
• Do not indent the text of items within @itemize or @table blocks. Allow the formatting tools to perform the indentation automatically. This also applies to @example blocks, but here you may indent sub-blocks. For example, you may want to create a block like this:

  @example int Increment(int n) @{ return n + 1; @} @end example

  Then you may, of course, indent the `return' line, but not the other lines.

• Do not use tabs to indent code in @example blocks since the formatting tools do not faithfully reproduce the tab's indentation. Instead, always indent using spaces.
• Attempt to keep the content of Texinfo source files under 80-columns in width if possible. This is a general guidelines rather than a hard rule.

This document was generated using texi2html 1.76.