Ozone Documentation Howto

Per Nyfelt

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-2003 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

Getting started
Structure
Contributing
Getting started
Tools
Documentation Guidelines

Getting started


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 ozone
      
For developer access the settings and commands are as follows:
      CVS_RSH=ssh
      CVSROOT=:ext:yourSourceforgeId@cvs.ozone.sourceforge.net:/cvsroot/ozone
      cvs co ozone
      
Documentation 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 install
      
or
build install
on 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 allhtml
      
The 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.html
      
It 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.