1. Home
  2. Documents
  3. Developer Documents
  4. Haiku Documentation Team How-To

Haiku Documentation Team How-To

,

Your feedback is welcome. Please send comments using this contact form (login required).

Required Software

Subversion

Source code and documentation for the Haiku project is stored in a Subversion repository on the BerliOS server (berlios.de). Subversion is an open source revision control system. You can obtain the Subversion binaries for Windows/Linux from the Subversion official site:

Binaries for BeOS

Doxygen

The documentation in Haiku is produced using the open source Doxygen document generator. You can obtain the Doxygen binaries for Windows/Linux from the Doxygen official site:

Binaries for BeOS

Retrieving Documentation

To retrieve the current Haiku documentation from the Haiku repository and put it into the /haiku/trunk/docs/user/ directory on your current drive:

svn checkout http://svn.haiku-os.org/haiku/haiku/trunk/docs/user/ 
/haiku/trunk/docs/user/

To view the Haiku source code files on the BerliOS server, paste the following URL into the address bar of your favourite web browser:

http://svn.haiku-os.org/haiku/haiku/trunk/src/kits/

This will give you access to the various Haiku kits source code.

http://svn.haiku-os.org/haiku/haiku/trunk/headers/

This will give you access to the various Haiku headers. You can use the links within the browser to traverse the repository.

You may also want to checkout these files locally onto your PC:

svn checkout http://svn.haiku-os.org/haiku/haiku/trunk/src/kits/ 
/haiku/trunk/src/kits/
svn checkout http://svn.haiku-os.org/haiku/haiku/trunk/headers/ 
/haiku/trunk/headers/

Generating the Documentation

In order to generate the Haiku documentation from the source files, you need to execute the following Doxygen command in the /haiku/trunk/docs/user/ directory:

doxygen

Note: if you are running Doxygen from Windows, it will be unable to create the output directory, if it doesn't already exist, and will fail. Create this directory yourself by running the following command from the /haiku/trunk/docs/user/ directory:

md ..\..\generated\doxygen

(You will only need to do this once).

Doxgen generated source code will thus be placed in the haiku/trunk/generated/doxygen directory. The output directory can however be changed by editing the Doxyfile file and changing the OUTPUT_DIRECTORY entry.

Note: if you do change the Doxyfile output directory location, please ensure that it is excluded from any patches you submit, as we don't want to update it in the Haiku repository.

Creating/Editing

You can use your favourite ascii text editor to create and edit the documentation, but the editor should be setup to wrap lines that extend beyond 80 characters. It would also be preferable to ensure that newlines are written back to the file in UNIX format. Most modern text editors have an option for this. Please read the "Documenting the API" document to see the guidelines to which the Haiku API documentation is being written.

Proofreading

The documentation will be written in English; to ensure that a good level of grammar and spelling is maintained, the following websites may be useful:

Ensuring your document is current

If you have checked out a file to work on locally, someone else may be doing the same. They may also have made changes and checked the file back in before you. The file you now have cannot be checked in over the top of theirs as you will remove their changes. To avoid these problems, it is always prudent to update your file before checking it in. You can do this with the following command:

svn update

This should be run from within your local source tree where the document file you have edited resides. The effect of this command is to update other peoples changes into your file, whilst leaving your changes intact.

Submission

Documents ready for submission can be posted to this list and someone with Subversion commit privileges will check it in to the BerliOS repository. Alternatively, if you have commit privileges, you can check in the document yourself.

Patches can be created with the following Subversion command:

svn diff > FILENAME.patch

to produce a single diff file for all changes, to a patch file called FILENAME.patch, or;

svn diff FILENAME > FILENAME.patch

to produce a single diff file for changes to a single file called FILENAME, to a patch file called FILENAME.patch.

Subversion can also operate recursively, traversing directories in your local source code tree. This allows you to capture changes in multiple directories by running this command in a common root.

svn diff > FILENAME.patch

Remember: if you have made local changes to the Doxyfile, please ensure that is excluded from patch submissions. This is especially relevant where the patch file has been generated by the recursion technique mentioned above.

Further Reading