Ron Hayden Senior Tools Manager Apple Technical Publications

rhayden@apple.com

3 19 March 2002 ms - murray@freebsd.org Added references to the documentation mailing list and the man pages HowTo. 2 20 July 2001 rjh Updated XML editor list and man page status. 1 25 January 2001 rjh - rhayden@apple.com 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 rhayden@apple.com. 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 darwin-documentation@lists.apple.com 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 http://www.opensource.apple.com/projects/mail.html The rest of this document will cover authoring HowTo documents. 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. HowTo documents included in the Darwin project are covered by the Common Documentation License (CDL), which you can review here: http://www.opensource.apple.com/cdl/ HeaderDoc and man pages are considered to be a part of the software, covered by the Apple Public Source License (APSL) or other applicable software license(s). You! Who better? If you know about a subject that seems to be sorely lacking in documentation, then go ahead and write up a HowTo and send it to darwin-documentation@lists.apple.com or to rhayden@apple.com. If you can only cover part of a subject, do that part and send it in. Someone else is much more likely to help finish it if it's been started. Keep reading! This document provides everything you need to know to get started. If after reading the XML instructions you still find yourself having trouble, just let us know. We're much more concerned with getting the information out to people than with what format you provide it in. So if you'd prefer not to venture into XML, provide it in whatever way works best for you and we'll get around to putting it into XML for you. Everything eventually has to end up as XML to support automated processing of the document into multiple formats. Although the documentation is maintained as Open Source, we assume that the original author is interested in providing the primary maintenance for the document, and in guiding the nature of any changes and bug fixes. Therefore suggestions, changes, and bug fixes should be sent to the original author so they can decide how best to integrate them. If there is no response, or the author is no longer interested in maintaining the document, or there's no obvious author, then send your comments to darwin-documentation@lists.apple.com or to rhayden@apple.com and they will get handled. We don't have a doc-specific mailing list at this time. Until the documentation project gains its own momentum, we will simply use Darwin-Development@lists.apple.com. A Documentation-specific mailing list is now available. Please join the darwin-documentation@lists.apple.com mailing list, in addition to any general purpose Darwin lists that interest you. The HowTo documents are authored in XML, using the DocBook XML DTD. They are maintained in the Darwin CVS archive and will soon be built regularly. XML is a structured document language that describes text according to what kind of data it is, rather than how it should look. If you are used to simply making text bold when you want it to be bold, then it can take a bit of adjustment to understand the XML authoring model. In traditional text editors if you wanted to make someone's email address stand out in a paragraph, you would provide some special formatting. In an RTF document you might make it bold, or if you are editing an HTML document, you might look up the formatting for a mailTo anchor so poeple can click on the address to send email. XML makes your life easier. All you need to do is identify the data as an email address, such as emailrhayden@apple.comemail, and when the document is processed the tools decide what to do. So for RTF it might become bold, for HTML it might become a hot link. With a structured editing language like XML, the writer's job changes to one of providing content and identifying what that content is. How the content is produced is handled seperately. Authoring XML is a bit like programming. After you create a document, you need a 'compiler' to parse it and make sure it is a legal document, so that the production tools will be able to do their job. This is known as validating the document. Some editors will do the validation for you, but many do not and require you to use a separate tool. Given the young nature of XML there are not a lot of high-quality editors to be found. Hopefully this situation will change soon. The important features to consider in an editor are: automatic tag insertion tag constraints: not allowing you to use illegal tags while editing validation against the Document Type Definition (DTD) If you don't find an XML editor you like that provides validation or tag constraints, then don't worry about it and just use your favorite editor. You'll just have to do a bit of work when you do run a validating parser on your document, to clean up any errors you've made. Editors you might want to check out are: ElfData's XML Editor, a commercial XML editor for the Mac and Mac OS X at http://www.elfdata.com/xmleditor/. ElfData has made it a priority for their editor to work for the Documentation Project, and has added a number of features specifically for the project such as DocBook support. PSGML editing mode for Emacs, at http://www.lysator.liu.se/~lenst/about_psgml/psgml.html. Morphon XML Editor, http://www.morphon.com/. Emile, a commercial XML editor for the Mac, at http://www.in-progress.com/emile/. XMLWriter, a commercial XML editor for Windows, at http://xmlwriter.net/. There are a couple of free GUI-based XML editors in development: IBM's java-based Xeena editor, http://www.alphaworks.ibm.com/tech/xeena. The Conglomerate system, http://www.conglomerate.org/. Now that you have an editor, you need the Document Type Definition (DTD). The DocBook DTD is available at the Oasis site, http://www.oasis-open.org/docbook/xml. Make sure you get the XML DTD, not the SGML version. Technically you don't need to have this on your local system, given that your XML document can point to it on the web (as the released versions of the HOWTO documents do). You may find that during the authoring of a document it's faster and more convenient to point your document to a local copy of the DTD. The HOWTO template provides an example of this. DocBook is the standard DTD used for creating technical documentation in the Open Source world. It's highly flexible, which means you can create documents as diverse as an API reference or this HowTo article with it. This flexibility also leads to the criticism that DocBook has too many tags and is too complex for a mere human to use. Norm Walsh has responded to this with a simplified DocBook DTD, at http://www.nwalsh.com/docbook/simple/index.html, which you can use if you prefer. While DocBook can be complex if you are authoring API reference or using tables, the typical HowTo document is really quite easy to author. This document so far has used less than ten unique tags for the body text (the author and revision information do use a few extra tags, but that's the kind of thing you can just copy anyway). Here are some good tutorials and other resources to get you started using DocBook. Some of these may refer to the SGML version, which is practically identical except for using a different identifier at the top and using mixed-case tags: DocBook: The Definitive Guide, http://docbook.org/tdg/html/docbook.html Writing Documentation Using DocBook, http://public.lst.de/~eric/index.html Get Going With DocBook, http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html A Practical Introduction to DocBook, http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html FreeBSD Documentation Project Primer for New Contributors, http://www.freebsd.org/tutorials/docproj-primer/ The XML version of this document serves as a pretty comprehensive template for HOWTOs. However, that's a lot of deleting to do to get started on your own writing. You might find it easier to use the Darwin HOWTO Template, which you can get here: http://www.opensource.apple.com/projects/documentation/howto/xml/Darwin_HOWTO_Template.xml. Creating an XML document is one thing, but processing it into HTML or PDF is another. There are multiple tools used in the process, and many alternatives to choose from, most of which are in various states of development. The Darwin Documentation project is still setting up the build system, and the tools used are subject to change at any time. Right now, we use the following: Norm Walsh's XSL stylesheets, http://www.nwalsh.com/docbook/xsl/index.html James Clark's Java-based XSLT engine, XT, http://www.jclark.com/xml/xt.html James Clark's XML parser, XP, http://www.jclark.com/xml/xp/index.html With these tools installed, your CLASSPATH needs to include pointers to xt.jar, xp.jar, and sax.jar, similar to this: CLASSPATH=xt.jar:xp.jar:sax.jar The Java command to transform the XML into HTML looks like this, where the docbook_xsl directory is the location of the xsl stylesheets: java com.jclark.xsl.sax.Driver myfile.xml docbook_xsl/html/docbook.xsl > myfile.html Given that this solution is Java-based, it cannot currently be run on the Darwin release. We're looking into some Perl-based solutions and other alternatives to change that in the near future. Copyright © 2001 by Apple Computer, Inc. This material has been released under and is subject to the terms of the Common Documentation License, v.1.0, the terms of which are hereby incorporated by reference. Please obtain a copy of the License at http://www.opensource.apple.com/cdl/w and read it before using this material. Your use of this material signifies your agreement to the terms of the License.