[haiku-doc] Re: Haiku Documentation Team How-To

Hi Alan,

I took the liberty of adding this document to the website here:

http://haiku-os.org/documents/dev/haiku_documentation_team_how_to
You may want to get editing rights (from Waldemar) in order to be able to update this document if necessary. 

Cheers,

Koki

Alan Smale wrote:

Hi Guys,

As promised, here is my first draft of the documentation team how-to.
I haven't got anywhere to host it, so I'm posting it to the list.

Cheers

Alan

Introduction
~~~~~~~~~~~~

This how-to describes getting started with contributing to the Haiku
documentation and the software you will need.

Your feedback is welcome. Please send comments to ajsmale@xxxxxxxxx

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:

http://subversion.tigris.org/

Binaries for BeOS

http://www.bebits.com/app/3962

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:

http://www.doxygen.org

Binaries for BeOS

http://www.bebits.com/app/2990

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.berlios.de/svnroot/repos/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.berlios.de/svnroot/repos/haiku/haiku/trunk/src/kits/

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.

Creating/Editing
~~~~~~~~~~~~~~~~

You can use your favourite ascii text editor to create and edit the
documentation. Please read the "Documenting the API" document to see
the guidelines to which the Haiku API documentation is being written.

Documenting the API -
http://factory.haiku-os.org/documentation/Haiku_Book_doxygen/html/apidoc.html 

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:

Dictionary - http://dictionary.reference.com/

English Usage, Style & Composition - http://www.bartleby.com/usage/

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.

Further Reading
~~~~~~~~~~~~~~~

Version Control with Subversion - http://svnbook.red-bean.com/

Using Subversion with the Haiku Source Repository -
http://haiku-os.org/documents/dev/using_subversion_with_the_haiku_source_repository 

Project: Haiku - SVN - http://developer.berlios.de/svn/?group_id=2556

Doxygen Manual - http://www.doxygen.org/manual.html

Other related posts: