Products         News         Downloads         Licensing         Shop         Support    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
WSDLDoc
Integrations
Bundles
 DocFlex/Javadoc
Overview
Documentation
Basic Templates
JavadocPro
Examples
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Use
Licensing
Shop
Support
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

DocFlex/Together - Documentation

  1. Installation
  2. Launching DocFlex from Together IDE
  3. Generator Dialog
  4. Launching DocFlex from Together command line
  5. Running stand-alone Template Designer
  6. Tips

1.  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, at 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, at 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, at 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.

2.  Launching DocFlex from Together IDE

DocFlex installs itself in the 'Project | Documentation' menu in Together 6.x or Together Architect 1.x (or 'Tools | Documentation' menu in Together 5.x):

DocFlex in Together menu

Launching DocFlex Template Designer from the Together IDE:

DocFlex Template Designer launched from Together IDE

Invoking DocFlex Generator:

Invoking DocFlex Generator

3.  Generator Dialog

The generator dialog provides a convenient GUI for specifying all necessary settings to run the DocFlex Generator:

Selecting generation scope

Scope

What it selects

All

The whole project

Current package

The package containing the current diagram selected in Together

Current package with subpackages

The package containing the current diagram plus all its subpackages

Current diagram

This will document only the current diagram selected in Together

Selected elements on current diagram

The generation scope will include the selected elements on the current diagram. The selected elements may be the following:

  • Class/Interface nodes
  • Shortcuts to other diagrams

Using this option, you can generate documentation for only specific classes (e.g. you may document just a single class if you need) and/or specific diagrams.

If you plan to design your own templates, please note that selecting the generation scope by itself actually specifies only two internal variables:

  1. The root element passed to the template
  2. The value of the predefined template parameter 'scope'

Further, it is up to a particular template to interpret them. The following table shows which values are assigned to those two variables in each case:

Scope

root element

scope-parameter

All

RwiModel instance representing the project model

"all"

Current package

RwiPackage instance representing the current package

"current-package"

Current package with subpackages

RwiPackage instance representing the current package

"current-package-recursive"

Current diagram

RwiDiagram instance representing the current diagram

"current-diagram"

Selected elements on current diagram

java.util.Vector object containing RwiNode- and RwiDiagram-instances of all selected elements

"selected_elements"

Where RwiModel, RwiPackage, RwiDiagram and RwiNode are interfaces from com.togethersoft.openapi.rwi package of Together OpenAPI.

Setting template parameters

The “Params” button invokes the Template Parameter Inspector, like the one shown on this screenshot:

Template Parameter Inspector

The inspector contents is constructed dynamically from the parameter descriptions obtained from the specified template. The parameter values are displayed and edited according to their types.

The bottom panel displays the description of the selected parameter (which is also obtained from the template). The first line of the description (the white text) shows the internal parameter name. Use this name in the -P option to specify the parameter value on the Together command line.

Changing output format options

Similar to the template parameters, the “Options” button near the “Output format” combo-box invokes invokes the Option Inspector for the selected output format. The precise option list depends on a particular output format.

The following screenshot shows the option inspector for the RTF output format:

RTF Option Inspector

And this is the HTML Option Inspector:

HTML Option Inspector

The bottom panel displays the description of a selected option. The first line of the description (the white text) shows the internal option name. This name should be used in the -O option to specify the format option value on the Together command line.

Specifying output location

Output folder
Use this field to specify the destination directory for the generated documentation. See -d option for more details.
Output file
Use this field to specify the documentation main output file name. See -f option for more details.

Include diagram images

The “Include Diagrams” check-box is intended to switch whether the diagram images should be included in the generated documentation.

However, like in the case of generation scope, the selection of this check-box by itself does nothing but specifies the value of the predefined boolean template parameter 'diagram.images'. Further, it is up to a template to interpret this.

The basic templates do process this parameter as intended. To allow/suppress generation of diagram images when DocFlex is started from command line, you will need to specify a -P option like the following: -p:diagram.images=true.

4.  Launching DocFlex from Together command line

To start DocFlex Generator from the command line without launching Together IDE, use the following command:

<launcher> <docflex_module> <project> [options] [packagenames]

where

  • <launcher> is TogetherCon.exe or Together.bat
  • <docflex_module> should be -script=com.togethersoft.modules.docflex.Generator
  • <project> is the absolute path to your Together project
  • [options] are the DocFlex command line options you need
  • [packagenames] specify packages in your project to document. If absent, the entire model will be documented. See also Generation Scope Options.

Command Line Options

The following command line options are specifically processed by the DocFlex Generator:

      -classes

      -errlog

      -launchviewer

      -subpackages

      -config

      -exclude

      -O

      -template

      -d

      -f

      -P

      -diagrams

      -format

      -quiet

Please note, all options not specified directly on the command line, first, will be searched in the generator config file (see -config option) and only when not found their default values will be used.

Here are option details grouped by category:

Template Options

-template <file>
Specifies the main template file to be executed by the generator. All documentation generation is controlled by this template. The main template may call from itself another templates (subtemplates) producing either a single output file or multiple files (framed documentation).

The template file may be specified both with absolute or relative pathname. The relative pathname will be treated against the default template directory (specified in docflex.config file).

Examples:
-template C:\Together\myprojects\mytemplates\MyDoc.tpl
-template ProjectDoc.tpl
-P<parameter>=<value>  or  -p:<parameter>=<value>
Specifies the value of a template parameter.
Notes:
  • You can find the necessary parameter names in the Template Parameter Inspector invoked from the Generator Dialog.
  • The boolean values should be specified as "true" and "false" strings (for example, -p:diagram.images=true).
  • When the value contains spaces, enclose it in double quotes (for example, -p:title="My Docs").

Output Options

-format <HTML | RTF | TXT>
Specifies the output format. By default, HTML.
-O<option>=<value>  or  -o:<option>=<value>
Specifies the output format option.
Notes:
  • You can find the necessary option names in the Format Option Inspector invoked from the Generator Dialog.
  • The values of the boolean options should be specified as "true" and "false" strings (for example, -o:rtf.storeGraphicsInRTF=false).
-d <directory>
Specifies the destination directory for the generated documentation. This option works in conjunction with the -f option.

The documentation files are distributed in the following way:

  • In the case of a single-file documentation
    1. The output document is placed in the destination directory under default file name 'templatename.formatextention' (for example, in the RTF output format, template ProjectDoc.tpl will produce document 'ProjectDoc.rtf'). The -f option may override this name.
    2. All associated files (such as images, if not included in the document) are placed in the 'docname_files' subdirectory near the main document.
  • In the case of a framed multiple-file documentation
    1. By default, all generated files and subdirectories are placed in the specified destination directory. The frameset file produced by the main template is saved under the name 'index.html'.
    2. If a different name 'docname' is specified with the -f option, the frameset file is saved under this name. All other files and the subdirectory tree are moved into 'docname_files' subdirectory near the frameset file.

      This makes the whole documentation to look as to consist of only two file entities, which may be easier to distribute yet during the generation, especially when different types of documentation are produced from the same project.

Examples:
-template ProjectDoc.tpl -format RTF -d c:\out
generate the document file c:\out\ProjectDoc.rtf with the associated files subdirectory c:\out\ProjectDoc_files\ (if any)
-template ProjectDoc.tpl -format HTML -d c:\out -f MyAPI
generate the document file c:\out\MyAPI.html with the associated files subdirectory c:\out\MyAPI_files\ (if any)
-template ProjectDocFrames.tpl -format HTML -d c:\out
generate the framed documentation located in the directory c:\out\ with the main file index.html
-template ProjectDocFrames.tpl -format HTML -d c:\out -f MyAPI
generate the framed documentation with the main file c:\out\MyAPI.html and all other files located in the directory c:\out\MyAPI_files\
-f <file>
Specifies the documentation output file name. This option works in conjunction with the -d option and specifies the name of the main output file (the one associated with the main template).

Typically, it should be used to specify a pure name associated with the generated documentation (for example, 'MyAPI'). However, the pathname may also be used. In that case, it is interpreted against the initial destination directory (specified with the -d option) and may override it. If the pathname is the absolute one, the -d option is effectively ignored.

-launchviewer[=<true | false>]
Tells the generator to launch a viewer for the generated documentation. Precisely, this request is passed to Together and handled by it.
Examples:
-launchviewer
Do launch viewer
-launchviewer=false
Do not launch viewer, no matter what's specified in the generator.config

Generation Scope Options

Note:  Everything specified with the following options will be treated as "selected elements" (see Selected elements generation scope). That is, the root element passed to the template will be a java.util.Vector object containing RwiPackage-, RwiNode- and RwiDiagram-instances of all specified packages (including those specified recursively), classes and diagrams. The value of the predefined template parameter 'scope' will be "selected_elements".

-subpackages <package1>:<package2>: ...
Includes in the generation scope the specified packages and recursively their subpackages. Each <package> should be fully-qualified package name.
Example:
-subpackages user_interface:Requirements.analysis
-exclude <package1>:<package2>: ...
Unconditionally excludes the specified packages and their subpackages from the list formed by -subpackages. It excludes those packages even if they would otherwise be included by some previous or later -subpackages option.
-classes <class1>:<class2>: ...
Includes the specified classes in the generation scope. Each <class> should be a fully-qualified class name.
Example:
-classes problem_domain.CashSale:Requirements.analysis.Sale
-diagrams[:<diagramType>] <diagram1>:<diagram2>: ...
Includes the specified diagrams in the generation scope. Each <diagram> should be specified as the diagram's package fully-qualified name with "." converted to "/" followed by the diagram name separated from the package specification with "/".

The option modifier <diagramType> allows to identify the required diagram shape type (e.g. "UseCaseDiagram", "StateDiagram"). If the shape type specified, all following diagram specifications are assumed to refer to only diagrams of this type. This setting may be necessary, when in a package, some diagrams of different types share the same name.

Examples:
-diagrams "Architecture View":Requirements/"Product Scanning Details"
-diagrams:SequenceDiagram user_interface/"Product Scan"

Other Options

-config <file>
Specify the generator config file, which may contain options written manually or using the Generator Dialog. All options not provided directly on the command line are searched in this file.

By default, the location of the generator config file is specified in the docflex.config (i.e. %TGH%/modules/com/togethersoft/modules/docflex/docflex.config). If no generator config provided, it is loaded automatically from that location (if exists).

-errlog <file>
Specifies the error log file used when the DocFlex Generator is executed without Together IDE (i.e. started from the command line).

By default, when an unexpected error/exception occurs during the generation and no GUI is enabled, all details about the error are printed to the standard console.

Using this option, you can assign a separate error log file, into which the detailed ERROR REPORT is dumped each time an error happens. Only brief messages will get on the console in that case. (See also Error Reporting for more details.)

The error log file should be specified as an absolute or relative file pathname. When the pathname points to a directory, it will be extended with the default “docflex_error.log” name (for example, setting "-errlog ." will be interpreted as 'docflex_error.log' file located in the current directory).

If the error log file does not exist, it is created in the event of error. Otherwise, the ERROR REPORT is appended to the existing file. In the case of any I/O error related to the error log file itself, everything will be printed to the console (along with additional the log file error message).

-quiet[=<true | false>]
Suppresses displaying most of the status messages to screen.

Command Line Argument Files

To shorten/simplify list of arguments on the command line, you can specify one or more files containing all those arguments you need. Any such file should contain space- or newline-separated arguments or options written the same way as on the command line.

When DocFlex parses the command line arguments and encounters an argument beginning with the character '@', it treats the characters following it as a file name and expands the contents of that file into the argument list.

Example:

This will run the DocFlex Generator from Together command line:
TogetherCon.exe <docflex_module> <project> @argfile
The argfile may contain the following lines:
-diagrams "Architecture View":Requirements/"Product Scanning Details"
-template ProjectDoc.tpl
-p:diagram.images=true
-format RTF
-launchviewer

5.  Running stand-alone Template Designer

The Template Designer can be started immediately as you unpack the downloaded archive. Just do the following:

  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-together-1_4.jar' with 'docflex-together-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

The tg_openapi_stub.jar you can see in the designer.bat class path is a substitute for the Together OpenAPI Java libraries. Actually, the Template Designer does not use any Together OpenAPI by itself, but since it uses the DSM drivers which, in turn, contain references to the Together OpenAPI classes, the JVM cannot start the designer without at least the stub representations for some of them.

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-together.jar com.togethersoft.modules.docflex.Designer

6.  Tips

Here are some tips on various topics of using DocFlex/Together and the documentation produced with it.

Generation Phases

DocFlex generates the whole documentation in two phases: estimation phase and generation phase.

In the estimation phase, the generator quickly passes over all the source data and partially interprets the involved templates. During that, it collects the names and location of all documentation files to be created and all possible hypertarget locations within them. It also makes an estimation of the total generation time in order to graduate the progress bar.

During the estimation phase, only the message "Scanning data source, please wait..." is displayed on the Together progress bar. Please note, the estimation phase may take some time! On a very big project (and a slow computer), it may last several minutes. This does not mean, the generator hangs. Please wait!

During the generation phase, all template components are being fully interpreted and the real output generated. The progress bar is alive and shows what's being generated at the particular moment.

The version of JVM also considerable affects the whole processing time. Under JVM 1.3, the estimation phase lasts almost as long as the generation phase, whereas under JVM 1.4, it is a lot shorter. Apparently, that's because of the faster object allocation under 1.4 (although, other reasons may be in work). So, if it's possible for you, use Together 6.2 (or Architect 1.x) rather than the older Together versions!

Error Reporting

Both the DocFlex Generator and the Template Designer may encounter various unexpected error situations. During the generation, the unexpected errors and exceptions may arise because of the following reasons:
  1. I/O errors (e.g. invalid file pathnames, disk full, etc.)
  2. Template errors (when something is improperly specified in templates).
  3. Data source exceptions (in the case of DocFlex/Together, these may be exceptions thrown by the Together itself).
  4. DocFlex core exceptions (these may be caused by bugs not discovered and fixed yet).
DocFlex tries to catch all such errors/exceptions and report about them along with the full diagnostics possible (i.e. where exactly and how the error has happened).

When the Generator Dialog is enabled, any error is reported via the error message dialog, like the one shown on the screenshot:

Error Message Dialog
The error dialog shows brief information about the error. When more details are available, a full ERROR REPORT is created and dumped to the system clipboard. You can easily extract it (e.g. under MS Windows, just run Notepad and press Ctrl+V).

The detailed ERROR REPORT includes:

  • The general info about JVM, OS, command-line arguments, etc.
  • All available error messages.
  • The Template Location Trace that shows which precisely template component was being interpreted when the error happened.
  • The Java Exception Stack Trace (when the error was caused by some unexpected Java exception).
When the DocFlex Generator is executed without Together IDE (i.e started from the command line), by default, all exception/error details are printed to the standard console. However, using -errlog option, you can specify a separate error log file. In that case, the detailed ERROR REPORT will be dumped in that file; only brief messages will get on the console.

Updating RTF Fields

The RTF documentation generated by the provided templates heavily uses document fields (for such things like page number references, number of pages and so on).

When you load the generated RTF in MS Word, to have the fields display the correct values, you will need to update them. To do this, please type: Ctrl+A, then F9.

Rotating big diagrams in RTF

DocFlex allows to automatically rotate big diagram images placed in RTF to make them better fit in the specified paper size in order to minimize the image scaling. Rotated images appear in landscape orientation instead of portrait (without rotation).

This feature is currently supported only for images generated in GIF format and only when all graphics is stored within the RTF file. By default, it is enabled.

You may disable the diagram rotation by unselecting “Allow image rotation” check-box in the RTF Options dialog (or using '-O:rtf.allowImageRotation=false' formatting option on the Together command line).

Updating diagram frame in HTML documentation

The framed HTML documentation generated by the provided templates is displayed in several frame windows. One of them shows the diagram image, another -- the detailed documentation about a class or a diagram.

When you surf the documentation within the "details" frame, clicking by hyperlinks, you may need to update the displayed diagram according to the document you are currently viewing.

You may do this very quickly. Just find the big diagram icon at the top-left corner of the document and click on it.

Inserting "Mark of the Web" comment in HTML

When you run generated HTML documentation from a local drive using Internet Explorer with Windows XP SP2, the Information Bar may indicate that active content (the JavaScript in the HTML) has been blocked. To avoid this problem, according to Microsoft, a “Mark of the Web” (MOTW) comment should be inserted in all generated HTML documents.

Since version 1.1, DocFlex/Together is able insert the generic MOTW automatically (see code below). This is controlled by “Add Mark of the Web” option (see HTML Options dialog).

You may also program inserting MOTW by yourself using a special HTML pattern file. To do so, you should create a separate HTML file with the following content:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0014)about:internet -->
<HTML>
<HEAD>
<!-- docflex-html-head -->
</HEAD>
<BODY>
<!-- docflex-html-body -->
</BODY>
</HTML>

Then, specify location of this file in the “HTML pattern file” field within the HTML Options dialog (or using '-o:html.documentPatternFile' formatting option on the Together command line).

DocFlex will produce all HTML documents using the specified HTML pattern file with the lines <!-- docflex-html-head --> and <!-- docflex-html-body --> replaced with the actual generated output.

For more information about MOTW, please refer to Microsoft MSDN web-site: http://msdn.microsoft.com

Copyright© 2003-2014 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.