| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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 |
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 apihtmlGenerate 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 apidevhtmlGenerate 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 manualhtmlConvert the Crystal Space manual to HTML format.
make manualdviConvert the Crystal Space manual to DVI format.
make manualpsConvert the Crystal Space manual to PostScript format.
make manualpdfConvert the Crystal Space manual to PDF format.
make manualinfoConvert the Crystal Space manual to GNU Info format.
make repairdocRepair all ‘@node’ and ‘@menu’ directives in the Texinfo sources.
make cleandocDelete all converted documents.
The ‘CS/docs/texinfo’ directory contains:
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.
Here are some general formatting conventions.
@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.
@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.
@example blocks since the formatting
tools do not faithfully reproduce the tab's indentation. Instead, always
indent using spaces.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated using texi2html 1.76.