The Darwin Documentation HOWTO

Ron Hayden

Senior Tools Manager
Apple Technical Publications


Revision History
Revision 430 May 2002rjh
Updated XML/XSLT processor instructions and fixed incorrect mailing list statement.
Revision 319 March 2002ms - [email protected]
Added references to the documentation mailing list and the man pages HowTo.
Revision 220 July 2001rjh
Updated XML editor list and man page status.
Revision 125 January 2001rjh - [email protected]
Initial release.


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 .

Table of Contents

The state of the world
HowTo documents
man pages
Questions you should ask first
What license is used for Darwin documentation?
Who can submit documentation?
What if I don't know how to author an XML document?
What if I don't want to learn XML?
Who can make changes to existing documents?
Where is the documentation mailing list?
Authoring a HowTo document
What is XML?
Choosing an XML editor
Getting the DocBook DTD
Learning the DocBook DTD
Using the HOWTO template
Processing XML

The state of the world

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 mailing list.

To join the Darwin Documentation list or any other Darwin-related list, see


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

You can join the HeaderDoc mailing lists at

HowTo documents

The rest of this document will cover authoring HowTo documents.

man pages

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.