The Carbon Java Framework  

Carbon Development

Documentation System

Author: Greg Hinkle (ghinkle at sapient.com)
Version: $Revision: 1.2 $($Author: araman $ / $Date: 2003/05/05 07:42:36 $)
Created: March 2003

Introduction

The documentation system is designed to construct a set of locally or remotely browsable HTML pages from a set of XML documents through an XSL transformation. In this system each document is a well structure XML document with sections and subsections that contain text and html that will be worked into full HTML pages.

The documentation sytem for Carbon is designed to be a fully automated system that is run primarily through the ANT build tool. The Carbon build file has a target named "build-docs" that will execute the necessary transformation on all of the documentation files. It will also move any image files as necessary.

Structure

The documentation system for Carbon closely matches with the moduler nature of the build system. There are three levels to documentation, a root level, a module level and a sub-module level. The root level documents resides within the {build-home}/doc-build directory. The module level documents lie withing a "docs" directory within a module directory ({build-home}/modules/{module-name}/docs). The sub-module documents lie within a directory inside the module level directories.

Documentation Structure

+ {build-home}
|-+ doc-build
|-+ modules
  |-+ core
  | |-+ docs
  |   |-+ component
  |   |-+ config
  |   |-+ exception
  |-+ cache
    |-+ docs
        

Files

Module.xml

Each directory that contains documention must contain a module.xml file that contains the basic structure information for the directory in which it is located. This file contains the header information for the documents in the diretory as well as the menu items to be found in the navigation menu for those documents.

Module.xml template


<?xml version="1.0" encoding="ISO-8859-1"?>
<module name="Carbon Core Module"
        href="http://scratchy.sapient.com/projects/ejfw4/core">
    <title>Core Config Module</title>
    <crumbs>
        <crumb name="Core" href="../index.html"/>
        <crumb name="Config" href="index.html"/>
    </crumbs>
    <body>
        <menu name="Configuration">
            <item name="Usage Guide"            href="Usage.html"/>
            <item name="Design"                 href="Design.html"/>
            <item name="Extension"              href="Extension.html"/>
        </menu>
        <menu name="Validation">
            <item name="Schemas"                href="schemas.html"/>
        </menu>
    </body>
</module>

        

Document structure

All documents must be well formed XML documents with a file ending of ".xml". These files will be translated into HTML documents as part of the documentation build.

Documentation Template


<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document [
  <!ENTITY CarbonModule SYSTEM "module.xml">
  <!ENTITY nbsp "&#x00A0;">
]>

<document url="modules/core/docs/config/Design.html">
 &CarbonModule;
  <properties>
    <author email="email@home.com">Author Name</author>
    <created>January 2002</created>
    <title>Configuration Service Design</title>
    <version>$Revision: 1.2 $($Author: araman $ / $Date: 2003/05/05 07:42:36 $)</version>
  </properties>
<body>
  <section name="Introduction">
      <subsection name="Subsection name">
        <p>Hello World!</p>
      </subsection>
  </section>
</body>
</document>

        

Copyright © 2001-2003, Sapient Corporation