12 +---ant                 Ant scripts to transform cxxApiRef dtd xml to dita reference xml.

    12 +---bin                 Preexisisting symbian build system directory. doxygen.exe is copied here and the batch script to transform output to DITA reference and produce ditamaps.

    13 +---bin                 Preexisisting symbian build system directory. doxygen.exe is copied here and the batch script to transform output to dita reference and produce ditamaps.

    15 +---CxxApiRef2Dita      xslt and ant scripts to perform the cxxApiRef to dita reference conversion.

    14 +---doc_pub             Additional documentation about converting output to DITA reference dtd and how to generate and use a system definition file with Orb.

    16 +---documentation       Additional documentation about converting output to dita reference dtd and how to generate and use a system definition file with Orb.

    19     \---doxygen         Python scripts that are used by the map creation and transform scripts

    17     \---doxygen         Python scripts that are used by the map creation and transform scripts.

    18 +---utils				Contains the sysdefupgrade.xsl tool.

    25 Running Orb on my project

    24 Prerequisites

    26 =========================

    25 =============

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

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

    28   if this is C:\epoc32 then %EPOCROOT% must be just \.

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

    30   (usually C:\Apps\sbs)

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

    32   A version 2 system definition file upgraded to 3 using the provided xslt (see below)

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

    34   system_definition.xml and package_definition.xml files  

    35   

    36   

    37 How to create html output from C++ source code  

    38 ==============================================

    40 The documentation will conform to the cxx DITA dtd specialisation and will need to be converted to 

    63 If you need to run Orb on a complete OS see doc_pub\sysdefv3_guide.txt

    41 to xml that conforms to standard DITA reference xml to be processed by the Dita Open Toolkit.

    64 The above command builds all of the source. Build an SDK release with this command:

    42 For more information on performing this conversion please see documentation\converting_to_reference.txt.

    65 

    66 sbs -c doxygen-sdk

    47 The two locations are epoc32\builds and epoc32\release\dita. The builds directory contains the temporary output

    71 The two locations are epoc32\build and epoc32\release\doxygen\dita. The build directory contains the temporary 

    48 that doxygen produces as it runs on all the targets of the Symbian OS. There is one directory per component

    72 output that doxygen produces as it runs on all the targets of the Symbian OS. There is one directory per component

    52 The script that converts the cxx dita output from doxygen to dita reference requires the release\dita directory.

    76 The output directory epoc32\release\doxygen\dita is required by the script that converts the cxx DITA output from doxygen to DITA reference.

    53 Its outputs files to epoc32\release\ditareference and epoc32\release\maps.

    77 See doc_pub\converting_to_reference.txt for guidance.

    78 

    79 

    80 Running the postprocessor

    81 =========================

    82 Now you must run the postprocessing step to create top level maps and ready your output so that it can be built into html using DITA Open Toolkit.

    83 

    84 Introduction

    85 ============

    86 The postprocessing script runs several scripts on Doxygen output.

    87 This includes:

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

    89 system definition version 3 XML file.

    90 -A script that creates a map for each component.

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

    92 to a global unique id (GUID)

    93 -A script that renames each file to a GUID value.

    94 

    95 Creating a table of contents from a system definition version 2 file

    96 ====================================================================

    97 The map creator in this package is only compatible with system definition version 3 files

    98 If the symbian build system is run using a system definition version 2 file it must be converted to version 3

    99 before the convertion can be run.

   100 To do this please do the following:

   101 Set up the prerequisites as described in sysdefv3_guide.txt (this is to set up the Apache Xalan transformer for use on the command line)

   102 From the console run:

   103 

   104 java org.apache.xalan.xslt.Process -in C:\path_to_system_definition\canonical_system_definition_GT_tb92sf.xml -xsl %SBS_HOME%\utils\sysdefupgrade.xsl -out c:\output_path\new_system_definition.xml

   105 

   106 You can use one of the examples in the "Running the batch script" section below on this new system defintion version 3 file to produce correct maps for this documentation build.  

   107 

   108 Running the batch script

   109 ========================

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

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

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

   113 If it is not set then please set it.

   114 

   115 The usage is as follows:

   116 orb_proces_cxx.bat SYSTEM_DEFINITION_PATH [PUBLISHING_TARGET]

   117 

   118 SYSTEM_DEFINITION_PATH	EPOC source tree os the directory containing v3 system definition and package definitions

   119 PUBLISHING_TARGET	    [mode], ditaot

   120 

   121 PUBLISHING_TARGET is an optional argument that determines how the output of the tool is prepared for the intended publishing environment.

   122 "mode" is the default publishing target and will be used if no option is given.

   123 

   124 Examples:

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

   126 

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

   128 

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

   130 

   131 Output

   132 ======

   133 The output DITA maps go into %EPOCROOT%epoc32\release\doxygen\dita. 

   134 This directory now contains:

   135 * the main table of contents named GUID-445218BA-A6BF-334B-9337-5DCBD993AEB3.ditamap. 

   136 * the component level maps. 

   137 * all of the reference cxx XML files.

   138 

   139 All of these files are renamed with a GUID. The maps all end with .ditamap and all the reference documents end in .xml.

   140 

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

   142 There is no log capture automatically performed by this script. Capture the stdout if you wish to review this.

   143 

   144 

   145 Running DITA Open Toolkit to create html

   146 ========================================

   147 For smaller sets of documents it is possible to use DITA Open Toolkit version 1.5.1 with the cxxapiref plugin to build your documentation. 

   148 It is recommended that the supplied DITA Open Toolkit is used, as supplied with it is a utility that allows each component to be built 

   149 concurrently. This saves time and reduces the likelihood of java out of memory errors.

   150