| Revision History | ||
|---|---|---|
| Revision 4 | 30 May 2002 | rjh |
| Updated XML/XSLT processor instructions and fixed incorrect mailing list statement. | ||
| Revision 3 | 19 March 2002 | ms - [email protected] |
| Added references to the documentation mailing list and the man pages HowTo. | ||
| Revision 2 | 20 July 2001 | rjh |
| Updated XML editor list and man page status. | ||
| Revision 1 | 25 January 2001 | rjh - [email protected] |
| Initial release. | ||
Abstract
What you need to know to contribute to the Darwin documentation project.
This HOWTO will grow as we develop processes and tools. If you have any suggestions for improving it, email <[email protected]>.
Table of Contents
The focus of this discussion is on the details of contributing HowTo documents. But first a bit of the big picture. At this point in the life of Darwin there are three types of documentation we are set up to handle, listed in the order that we're tackling them:
HeaderDoc
HowTo documents
man pages
We'd love to have your contribution in any of these areas, or your suggestions for whatever other kinds of documents we should have. If you are interested in writing documentation about Darwin, please join the <[email protected]> mailing list.
To join the Darwin Documentation list or any other Darwin-related list, see http://lists.apple.com/mailman/listinfo.
If you are writing code for Darwin, you should be using HeaderDoc.
HeaderDoc is an Open Source Perl tool for embedding structured commentary in C and C++ header files and producing rich HTML output from that commentary. HeaderDoc comments are similar in appearance to JavaDoc comments in a Java source file, but there are differences related to handling specifics of C and C++ and a slightly more formal tag set to simplify parsing.
A simple HeaderDoc comment for a function might look like this:
/*! @function HMBalloonRect @discussion Gets information about the size of a help balloon. @param inMessage The help message for the help balloon. @param outRect The coordinates of the rectangle enclosing the balloon. */ OSErr HMBalloonRect (const HMMessageRecord *inMessage, Rect *outRect);
These comments are extracted and poured into a nicely-rendered HTML frameset that allows quick access to the reference comments.
To find out more about HeaderDoc, go to
http://www.opensource.apple.com/projects/headerdoc/
You can join the HeaderDoc mailing lists at
man pages are currently going through a number of changes. The Darwin Man Page HOWTO is essential reading if you are interested in working on man pages. Currently, the man pages themselves are being moved from a centralized project to live with the commands they document. General responsibility for man pages are being moved from the writers to the engineers.