Browse haiku-doc: This Month's Archive • Main Archive Page • Related posts • Previous by Date • Next by Date

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

From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
To: haiku-doc@xxxxxxxxxxxxx
Date: Thu, 26 Apr 2007 13:02:02 +0200

Hi Alan,

Thanks for the work, I've got a few comments.

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


I think it's a good idea to refer to the mailing list in the introduction

Required Software
~~~~~~~~~~~~~~~~~
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


Let's get that entry (or another) updated to 1.5.0. As soon as I'll
start writing some patches against it, I might put it in the
repository, but so far that seems like an overkill.

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/


You will also need to check out the header files with svn checkout
http://svn.berlios.de/svnroot/repos/haiku/haiku/trunk/headers/
/haiku/trunk/headers/ . I haven't tested the command, and I don't know
if it works if you do these two subsequently.

Also, perhaps we need a note on how to keep the documentation up to date.

Generating the Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.


Make sure you exclude the Doxyfile then if you make patches against
the repository then.

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.


Could we? I'll have to find out if we can mix different kinds of
newlines (UNIX versus windows). I hope doxygen is agnostic and
supports mix'n'match when it comes to this, but I've been converting
the newlines to UNIX'y things.

BTW. perhaps a requirement should be that the editor shows the amount
of columns you are using, since the hard limit is at 80. (is that
actually in the API guidelines???)

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/


Good references.

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.


Always check that your documentation compiles and conforms to the standards.

Patches can be created with the following Subversion command:

svn diff > FILENAME.patch


Perhaps a note on the fact that subversion works recursively and that
you can capture changes in multiple directories by running this
command in a common root.

------

Great howto Alan, thanks for putting this in words. I hope that people
that are going to try it over the weekend can give you some more
feedback.

Niels

Follow-Ups:

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

References:
- [haiku-doc] Haiku Documentation Team How-To
  - From: Alan Smale

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

Other related posts: