Copyright © 2001, 2002 SMB GmbH
Ozone Documentation License, Version 1
This document is free software; you can redistribute it and/or modify it provided that the terms of the GNU Library General Public License as published by the Free Software Foundation version 2 of the License; and the following terms are met.
The Ozone Database Project <ozone@ozone-db.org>
Included in the ozone distribution is code and documentation made available by other copyright holders and under different licenses. All these licenses allow worldwide, royalty free distribution, whether alone or as part of a larger product. License, copyright and disclaimer of this software is included in this directory.
The document is Copyright (C) 1997-2001 by SMB GmbH, Rohrteichstr. 18, 04347 Leipzig, Germany, All rights reserved.
You must give prominent notice with each copy of the work that the document is used in it and that its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License.
The name ozone must not be used to endorse or promote software products derived from this software without prior written permission of SMB.
Software products derived from this document may not be called ozone nor may ozone appear in their names without prior written permission of SMB.
This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.
Abstract
This document describes how to get started with writing documentation for Ozone as well as some guidelines to make your documentation easy to integrate with the other docs part of the Ozone Documentation Project. The target audience is for developers and experienced users wanting to help out writing docs.
Table of Contents
The Ozone Documentation consists mainly of three main parts:
If you like to help out with writing documentation a good first step (after reading through this howto and set up the tools required) is to go through the part you'd like to work on (user, admin or dev) and find a section you feel like working on then post a message to the Ozone dev list stating your intentions.
When you have something ready to show others post the diff on the dev list or contact the maintainer for that section directly who will integrate and put your stuff in CVS. The maintainer is listed as the author in the bookinfo section of each document but currently the maintainers for each section is as follows: User - Eric Richardson, Admin/Config - Rob Lapense, Development - Yanick Duchesne Howtos - varies for different ones, FAQ - Per Nyfelt.
A diff is created by executing "cvs diff -u filename.xml"
Another situation would be if you have experience in something that was tricky to do or useful for others but does not fit into the general docs. In this case a howto on the subject might be more appropriate. Send the howto to the dev list and one of the committers will add it to CVS as it is or incorporate it into the general docs.
The documents are in the src directory and HTML files are built by running build.bat or build.sh depending on shell and platform used. If you create a new document the ANT build.xml scripts currently needs to be updated.
We use DocBook for all our documentation. A package of the tools needed to use DocBook as well as the documentation files and build scripts is in our CVS repository (if you do not have CVS or have it but do not know how to use take a look at cvshome) Check out /ozone/ozoneDoc at SourceForge using the setup described there. In short: the cvs commands to use for anonymous access is:
cvs -d :pserver:anoncvs@cvs.ozone.sourceforge.net:/cvsroot/ozone co ozoneFor developer access the settings and commands are as follows:
CVS_RSH=ssh CVSROOT=:ext:yourSourceforgeId@cvs.ozone.sourceforge.net:/cvsroot/ozone cvs co ozoneDocumentation can be found under ozone/ozoneDoc in the newly created project.
After getting all sources you need to run the install target to set up docBook properly:
build.sh installor
build installon Windows
You are now ready to build the documentation. The default target is just a test target that build the example doc so you need to specify what target yoy want to run. To produce all html documents type
build.sh allhtmlThe resulting html files can be found under ozoneDoc/build/doc/html. To build a certain html file e.g. user documentation type
build.sh user-guide.htmlIt has been tested successfully with Linux and Windows 2000 and works to produce HTML docs. PDF doc generation is still a little shaky. If you have any problems with getting it to work please direct questions to the Ozone Development mailing list.
You need a text editor, preferably one that support xml in order to edit the docBook files. Examples of useful editors are:
The general documentation is divided into chapters but howtos' are not since they are meant to be brief and concise and thus confined to sections in an article tag.
Format for readability and content, not for a formatted document. We use a common style sheet for all documentation to get a consistent look so focus only on content, not looks.
Make sure you turn in a valid DocBook file. I.e. the file needs to be a well-formed XML document (parsable) and valid according to the DocBook DTD. One way to test this is to make sure you can run the build script and get the HTML document produced.
All chapter and section tags must have an id attribute. The id must be all lower case, with dashes separating words e.g. <section id="documentation-guidelines">. You can optionally add a prefix with a colon separation to guarantee the uniqueness of the id e.g. <section id="basics:about">
Specify the copyright and the licence in the bookinfo tag in the format:
<copyright> <year>2000</year> <year>2001</year> <holder>SMB GmbH</holder> </copyright> <legalnotice>&ozonelicence;</legalnotice>where ozonelicence is defined as
<!ENTITY ozonelicense SYSTEM "ozone-documentation-licence.xml">For every year in which a change is made, the copyright should be updated (i.e. expanded with another year (and author if necessary)).
Specify date and application's version in the format YYYY-MMM-DD e.g.: <date>2001-Jun-04</date>