Skip to main content
Jump to: navigation, search

Difference between revisions of "OAW Documentation"

(Writing oAW Documentation)
Line 10: Line 10:
 
** DocBook DocBook DTD
 
** DocBook DocBook DTD
 
** and an ANT build script to compile the documentation
 
** and an ANT build script to compile the documentation
 +
 +
=== Learning DocBook ===
 +
If you're new to DocBook, fear not. It's plain XML and you will learn the most important tags (about 15 or so) in no time. We suggest to take a look at the existing DocBook files in order to get an idea. Here are the most important tags:
 +
 +
* '''<chapter>''': starts a new chapter
 +
* '''<section>''': starts a new section. Sections can be nested infinitely (although we recomment not nesting too deeply)
 +
* '''<para>''': a paragraph
 +
* '''<itemizedlist>''': an itemized list
 +
* '''<orderedlist>''': an ordered list
 +
* lists contain '''<listitem>'''s
 +
 +
If you are in need of further information, please have a look at the manuals in '''documentation/lib/docbook/manuals'''
  
 
=== Writing ===
 
=== Writing ===

Revision as of 17:04, 4 April 2007

Writing oAW Documentation

Originally, oAW documentation has been written using OpenOffice and exported to PDF for end user convenience. Starting in March 2007, we're converting all documents to DocBook which gives us the tremendous benefit of creating both PDF documentation for printing purposes and Eclipse online help from one source (single-source publishing).

Prerequisites

Here's what you need to create DocBook documentation:

  • Your favourite XML editor. You might want to try Eclipse WTP.
  • The documentation subproject of oAW. Get it from our developer CVS.
    • This projects contains all source files,
    • DocBook XSL transformation and stylesheets,
    • DocBook DocBook DTD
    • and an ANT build script to compile the documentation

Learning DocBook

If you're new to DocBook, fear not. It's plain XML and you will learn the most important tags (about 15 or so) in no time. We suggest to take a look at the existing DocBook files in order to get an idea. Here are the most important tags:

  • <chapter>: starts a new chapter
  • <section>: starts a new section. Sections can be nested infinitely (although we recomment not nesting too deeply)
  • <para>: a paragraph
  • <itemizedlist>: an itemized list
  • <orderedlist>: an ordered list
  • lists contain <listitem>s

If you are in need of further information, please have a look at the manuals in documentation/lib/docbook/manuals

Writing

  1. After you have checked out the documentation project,
  2. navigate to the documentation/docbook-src/oaw4.1 folder

The index.xml file is the documentation root and contains includes for all subdocuments.

Adding a new cahpter to the documentation

If you want to add a new chapter,

  1. create a new XML document similar to gettingstarted-emf_tutorial.xml
  2. and add an Entity import to the index.xml file (<!ENTITY gettingstarted-emf_tutorial SYSTEM "gettingstarted-emf_tutorial.xml">)


Compiling

In order to convert your DocBook XML into a PDF and Eclipse Online Help:

  1. select build-docbook.xml
  2. run it as an ANT file

The PDF will be written to documentation/pdf/oaw4.1, the Eclipse Online Help will be created in a separate project (org.openarchitectureware.help.userguide, please make sure you've checked out this project from CVS before generating DocBook).

Back to the top