DocFlex/Together, Version 1.1

Table Of Contents

• Package Contents
• Technical Requirements
• Limitations of Trial Edition
• Installation
  • Together 6.2 and Architect 1.x
  • Together 6.1 and 6.0
  • Together 5.x
• Running Stand-alone Template Designer
• DocFlex Configuration Files
• Basic Template Set Overview
• Getting Help

Package Contents

Technical Requirements

• Borland® Together® Architect version 1.x
• Borland® Together® ControlCenter™ version 6.x or 5.x
• Borland® Together® Solo version 6.x or 5.x

To run the DocFlex Template Designer as a separate application, you will need Java^TM 2 JRE 1.4.x or JRE 1.3.x.

Limitations of Trial Edition

1. You can use the trial copy only during the limited period of time (30 days) provided by your evaluation license.

2. The output files generated by the trial copy (except those produced with the ClassDoc.tpl or ClassDocFrames.tpl templates) will contain special markers indicating the evaluation mode.

3. The templates created with the trial copy will not work with the shareware edition “DocFlex/Together (Lite)”, which is a version of DocFlex/Together without the Template Designer.

   If you acquire a commercial/academic license, after installing it, you will need to resave your templates created with the trial copy to free them of any limitations.

Installation

Installation on Together 6.2 and Architect 1.x

The following applies to Together® ControlCenter™ 6.2, Together® Solo 6.2 and Together® Architect 1.x.

Let's the Together is installed at 'C:\Borland\Together6.2' directory on your system. Then, please follow these steps:

1. Create a folder:

   C:\Borland\Together6.2\modules\com\togethersoft\modules\docflex

   That is, 'docflex' folder within 'C:\Borland\Together6.2\modules\com\togethersoft\modules' which already exists and where most of the Together's stuff is located.

2. From the archive you've downloaded, please copy into that folder:

   lib/docflex-together-1_4.jar
   [templates]                   - copy entire folder

   As a result, in the 'C:\Borland\Together6.2\modules\com\togethersoft\modules\docflex' you should see two items:

   docflex-together-1_4.jar
   [templates]

   No other docflex-together-xxx.jar should be left after any previous testings!

3. Place in this folder the 'docflex.license' file you received by e-mail (so, after that, there will be 3 items there)

4. Find file:

   C:\Borland\Together6.2\config\action.config

   (This is a native Together's file!)

   Add to this file the following lines:

   action.group._docflexGroup = generic
   action.group._projectDocumentationPopup.child.30 = _docflexGroup

   Save it.

That's all. Now, Together can be started as usual.

DocFlex will install itself in the “Project | Documentation” submenu. The following menu items should appear:

• “DocFlex Generator...” to invoke the Generator Dialog
• “DocFlex Template Designer...” to start the Template Designer

All necessary configuration files will be created automatically.

Installation on Together 6.1 and 6.0

The following applies to Together® ControlCenter™ or Solo version 6.1 or 6.0.

Let's the Together is installed at 'C:\Borland\Together6.1' directory on your system. Then, please follow these steps:

1. Create a folder:

   C:\Borland\Together6.1\modules\com\togethersoft\modules\docflex

   That is, 'docflex' folder within 'C:\Borland\Together6.1\modules\com\togethersoft\modules' which already exists and where most of the Together's stuff is located.

2. From the archive you've downloaded, please copy into that folder:

   lib/docflex-together-1_3.jar
   [templates]                   - copy entire folder

   As a result, in the 'C:\Borland\Together6.1\modules\com\togethersoft\modules\docflex' you should see two items:

   docflex-together-1_3.jar
   [templates]

   No other docflex-together-xxx.jar should be left after any previous testings!

3. Place in this folder the 'docflex.license' file you received by e-mail (so, after that, there will be 3 items there)

4. Find file:

   C:\Borland\Together6.1\config\action.config

   (This is a native Together's file!)

   Add to this file the following lines:

   action.group._docflexGroup = generic
   action.group._projectDocumentationPopup.child.30 = _docflexGroup

   Save it.

That's all. Now, Together can be started as usual.

DocFlex will install itself in the “Project | Documentation” submenu. The following menu items should appear:

• “DocFlex Generator...” to invoke the Generator Dialog
• “DocFlex Template Designer...” to start the Template Designer

All necessary configuration files will be created automatically.

Installation on Together 5.x

The following applies to Together® ControlCenter™ or Solo version 5.x.

Let's the Together is installed at 'C:\Together5.5' directory on your system. Then, please follow these steps:

1. Create a folder:

   C:\Together5.5\modules\com\togethersoft\modules\docflex

   That is, 'docflex' folder within 'C:\Together5.5\modules\com\togethersoft\modules' which already exists and where most of the Together's stuff is located.

2. From the archive you've downloaded, please copy into that folder:

   lib/docflex-together-1_3.jar
   [templates]                   - copy entire folder

   As a result, in the 'C:\Together5.5\modules\com\togethersoft\modules\docflex' you should see two items:

   docflex-together-1_3.jar
   [templates]

   No other docflex-together-xxx.jar should be left after any previous testings!

3. Place in this folder the 'docflex.license' file you received by e-mail (so, after that, there will be 3 items there)

4. Find file:

   C:\Together5.5\config\action.config

   (This is a native Together's file!)

   Add to this file the following lines:

   action.group._docflexGroup = generic
   action.group._documentationGroup.child.10 = _docflexGroup

   Save it.

That's all. Now, Together can be started as usual.

DocFlex will install itself in the “Tools | Documentation” submenu. The following menu items should appear:

• “DocFlex Generator...” to invoke the Generator Dialog
• “DocFlex Template Designer...” to start the Template Designer

All necessary configuration files will be created automatically.

Running Stand-alone Template Designer

1. Find designer.bat and specify 'JRE' variable in it according to JDK/JRE 1.4.x installed on your system.

   Note:

   You may equally use Java 1.3.x -- simply replace 'docflex-todether-1_4.jar' with 'docflex-todether-1_3.jar' in the class path.

2. Place in the lib/ directory the docflex.license file you received by e-mail

3. Run designer.bat

You may equally replace this stub jar-file with the original Together libraries. The following .bat commands will launch the stand-alone template designer directly from the DocFlex installation on Together:

  set CLASSPATH=%TGH%\lib\openapi.jar
  rem under Together 6.x or Together Architect 1.x only:
  set CLASSPATH=%CLASSPATH%;%TGH%\modules\com\togethersoft\modules\guiBuilderModel\guiBuilderModel.jar

  %TGH%\jdk\bin\java -cp %CLASSPATH%;docflex-todether.jar com.togethersoft.modules.docflex.Designer

DocFlex Configuration Files

docflex.config

This is the DocFlex main configuration file. It specifies:

• The locations of other configuration files used by DocFlex. Normally, they all are located in the same 'config' directory.

• The default templates directory

• The default output directory

• An external system command to open a URL. (In DocFlex/Together this command mostly not used, since when invoked from Together, DocFlex calls the Together's URL handler to launch a viewer for the generated documentation.)

When DocFlex starts, it searches the main config file in the same directory where the DocFlex Java library file 'docflex-xxx.jar' is located. If not found, docflex.config is created automatically with the default settings.

RWIModel.mtd

The configuration file used by the RWI Model Driver, which is the DSM driver responsible for obtaining data from Together models using Together RWI interface (see com.togethersoft.openapi.rwi and subpackages).

This file plays the similar role as XML DTD. It describes the data structure information on the level of UML diagrams, classes and so on, together with the specifying of how those data should be obtained using RWI. (The RWI, in fact, is a low-level interface which mostly does not "know" about such things by itself.) That information is used by the Template Designer during designing templates as well as when interpreting them by the Documentation Generator.

You may edit the RWIModel.mtd file to add new data structures which you can use in your templates. In this file, you can also quickly modify some text names appearing in the generated documentation as well as to suppress printing of some undesirable properties.

By default, the RWIModel.mtd file is searched in the DocFlex configuration directory (specified in docflex.config). If not found, it is loaded from the resource contained in docflex-todether.jar.

UIBuilderModel.mtd

The configuration file for UIBuilder Model Driver -- the second DSM driver provided within DocFlex/Together.

Rather than RWI, this driver uses a completely different interface called Model (or RWI2) also available in Together OpenAPI (see com.togethersoft.openapi.model package). The driver provides access to the Together UI Builder information, which is used by the templates/lib/UI.tpl template to generate the User Interface Documentation.

The UIBuilderModel.mtd file is organized and handled similarly to RWIModel.mtd.

designer.config

The Template Designer configuration file. It stores the designer configuration for the recently edited templates. This file is created and maintained automatically.

generator.config

This file is created automatically by the Documentation Generator (when started from Together). It contains all the settings specified when the generator dialog was invoked the last time. This includes:

• The last used template file
• The template parameters
• The last used output directory
• The output format options

When the generator dialog is invoked next time, those settings are restored from the generator.config, so you don't need to re-enter them again. The values of template parameters previously specified for one template will also be loaded into the equally named parameters of other templates.

You can also use generator.config file as a parameter when starting the Documentation Generator from the command line (or in a batch mode).

Basic Template Set Overview

This is a batch template (it calls from itself many other templates) which allows to generate a single-file documentation for almost everything contained in your project. It is supported by all available output formats and may be especially useful when the generated documentation is intended for printing (RTF output).

A lot of parameters provided by this template allow to adjust the documentation generation within a wide range of included details (from the most detailed project documentation to just overview with summaries of the contained packages and diagrams).

Currently, the following kinds of documentation can be generated with this template:

• The detailed Class Documentation (similar to that produced by Javadoc)
• The Diagram Documentation for the following diagram types:
  • Class Diagram
  • Use-Case Diagram
  • Component Diagram
  • Deployment Diagram
  • Sequence Diagram
  • Collaboration Diagram
  • State Diagram
  • Activity Diagram
  • Entity Relationship Diagram
  • Business Process Diagram
  • Robustness Diagram
  • (Other specific diagram types available in Together will be supported for free immediately as soon as you request any of them.)
• The User Interface Documentation (Together 6.x or Together Architect 1.x only)

  Note:  To allow generation of UI Documentation:

  1. The Together UI Builder module should be activated (see 'Tools | Activate/Deactivate Feature')
  2. The template parameter 'Generate UI Documentation' should be selected

The ProjectDoc.tpl template supports the following generation scopes:

All	the whole project
Current package	relatively to the current diagram
Current package with subpackages	relatively to the current diagram
Current diagram
Selected elements on current diagram	The selected elements may be Class nodes or shortcuts to other diagrams. This allows to generate documentation only for specific classes or diagrams (for instance, you may document just a single class if you need).

This is a version of ProjectDoc.tpl template which allows to generates a framed interactive documentation for your project. This template is supported only by HTML output format.

These templates are reduced versions of ProjectDoc.tpl/ProjectDocFrames.tpl. They allow to generate only Class Documentation (Class Diagrams included).

The difference is that both templates are for free. That means, the documentation generated with those templates will not contain any evaluation markers. You may download the shareware version called DocFlex/Together (Lite), which includes the same templates as the full version, and generate with it the full featured Class Documentation free of charge.

(The ProjectDoc.tpl/ProjectDocFrames.tpl templates will produce documentation with the evaluation insets unless you purchase a commercial/academic license.)

This directory contains the auxiliary subtemplates used in both ProjectDoc.tpl/ProjectDocFrames.tpl main templates.

This directory contains the auxiliary subtemplates used in both ClassDoc.tpl/ClassDocFrames.tpl main templates.

This directory contains generic subtemplates which generate logically finished pieces of documentation (such as the documentation for a particular class or a diagram) as well as the auxiliary subtemplates called from them.

Getting Help

Check the latest releases and documentation updates at: www.filigris.com.