License

=======

Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved.

This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html".

Introduction

============

This document explains how to convert cxx specialised DITA xml to DITA reference xml

Orb is used to create xml output using Doxygen on c++ source files.

This XML conforms to the cxx DITA dtd specialisation.

A batch file is included with orb that runs scripts to converts this cxx specialised xml to

xml that conforms to standard DITA reference xml.

Prerequisites

=============

* %EPOCROOT% environment variable is set to the parent of the epoc32 directory

  including a last \. If the directory is c:\foo\bar\epoc32 then this must be c:\foo\bar\

  if this is c:\epoc32 this must be just \.

* %SBS_HOME% environment variable must be set to the Symbian Build System install directory.

  (usually c:\apps\sbs)

* %EPOCROOT%\epoc32\release must contain Doxygen cxx xml output. For more information about how to

  generate this please refer to install_orb.txt.

* Java is installed (to run ant)

* python 2.5 is installed.

* A version 3 system definition file and all of the package definition files it links to with relative paths.

* An EPOC source directory (containing all packages prior to export) contains all required

  system_definition.xml and package_definition.xml files

What the batch script does

==========================

The batch script runs several scripts on the output to Doxygen.

This includes:

-A script that creates a DITA map from a Symbian build system compatible 

system definition version 3 xml file.

-A script that replaces all id attribute values and all links to ids (e.g in xrefs) 

to global unique ids (GUIDS)

-A script which runs an ant task which converts the DITA cxx specialised xml 

to standard DITA reference xml.

The output DITA maps go into %EPOCROOT%epoc32\release\doxygen\maps. This directory will contain the main 

table of contents named toc.ditamap. This directory will also contain component level maps. The main table 

of contents links to the component level maps and they in turn link to each target's ditamap generated by doxygen 

in %EPOCROOT%epoc32\release\doxygen\ditareference\transformed.

The DITA cxx xml is expected in: %EPOCROOT%epoc32\release\doxygen\DITA

The DITA reference xml output to : %EPOCROOT%epoc32\release\doxygen\ditareference\transformed

Log files are to be found in %EPOCROOT%epoc32\release\doxygen\ditareference\log

Running the batch script

========================

The batch file is in %SBS_HOME%\bin\orb_process_cxx.bat

If the symbian build system version 2 has been installed using an installer the %SBS_HOME% environment 

variable will be set and be on the system path which means it can be invoked from anywhere.

If it is not set then please set it.

The usage is as follows:

orb_process_cxx.bat [System definition path]

Example:

orb_process_cxx.bat C:\EPOC\master\sf\os\deviceplatformrelease\foundation_system\system_model\system_definition.xml