FlexDoc/Together
- What is FlexDoc/Together?
- Key Features
- Technical Requirements
- Advantages over old Together DocGen
- The Lite Edition
1. What is FlexDoc/Together?
FlexDoc/Together was a revolutionary template-driven documentation generator for Borland® Together® based on FlexDoc.XYZ.Created by the former author of the template-driven DocGen module in Together (which was developed during 1998-2002 yet in TogetherSoft Corp.), this tool represented a a major breakthrough and the next logical step over what Together DocGen was and remains now.
The software includes:
- The FlexDoc Template Designer
- The documentation generator (which interprets the templates)
- The two DSM (Data Source Model) drivers based on RWI and UIBuilder interfaces (both provided by Together OpenAPI).
The whole packages is prepared as a normal Together component and can be invoked both from the Together IDE and from the command line in a batch mode. The template designer can also be started alone as a separate Java application without launching the whole Together IDE.
Please, see Examples to take a look on how all this works.
2. Key Features
- Represents Together models in the form similar to XML documents and allows to process information from them basing on universal concepts of XML and approaches developed around it (such as XPath).
- Provides advanced data querying and sorting capabilities comparable with those of XSL Transformations (and possibly even beyond).
-
The high quality graphic Template Designer
allows to visually design the sophisticated formatting
of the generated documentation basing on abstract layout concepts such as flow of text,
paragraphs, tables and lists and any combinations of them.
Since all such layouts in one or another form are supported by any modern output format (such as HTML, RTF, PDF, XSL-FO and so on), the formatting specified in the FlexDoc template can be rendered with the high precision in any of those formats. (Currently, the supported output formats include HTML and RTF. Other formats are planned in next versions, XSL-FO in the first place).
- The TXT output is supported as well and may be used for non-documentation tasks to employ sophisticated data query and processing capabilities presented in this technology (for instance, using templates and TXT output, you can easily program dumping the data from Together models into various XML files).
-
FlexDoc templates are full-blown programs. What is not visualized by the Template Designer in the form of
template components
can be specified in component properties using FlexQuery-expressions.
FlexQuery-expressions are small scripts with the Java-based syntax, which are widely used in FlexDoc templates to specify all kinds of dynamically computed settings (such as dynamic properties of template components, filter conditions and so on).
About 150 built-in general utility functions are available now within the expressions, plus 26 function specific for Together, which represent some functionality provided by Together OpenAPI.
A special utility function
callForName()
allows to invoke a method of any custom-written external Java-class (implementing a special interface from the FlexDoc API).Within FlexQuery-expressions, it is possible to access the template parameters as well as various generator variables organized in the form of hierarchy of objects and properties of the Generator Object Model (similar to Document Object Model in Dynamic HTML).
-
The basic set of templates
provided with FlexDoc/Together (both editions) allows to generate
the following kinds of documentation:
- The detailed Class Documentation (similar to that produced by Javadoc), see screenshot
-
The Diagram Documentation for the following diagram types:
- Class Diagram (screenshot)
- Use-Case Diagram (screenshot)
- Component Diagram
- Deployment Diagram (screenshot)
- Sequence Diagram (screenshot)
- Collaboration Diagram
- State Diagram (screenshot)
- Activity Diagram (screenshot)
- Entity Relationship Diagram (screenshot)
- Business Process Diagram
- Robustness Diagram (screenshot)
- (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), see screenshot
-
Provides comprehensive support for launching the documentation generator
from the Together command line.
This includes possibility to specify on the command line:
- Various generation scopes (e.g. the whole model, specified packages with subpackages, individual classes and diagrams)
- Any template parameters
- Any output format options
- Command line argument files
- Other settings
3. Technical Requirements
FlexDoc/Together works with:- Borland® Together® Architect version 1.x
- Borland® Together® ControlCenter™ version 6.x or 5.x
- Borland® Together® Solo version 6.x or 5.x
The FlexDoc/Together Java libraries are supplied in two variants (both included in the packages available in downloads):
- The one optimized for JRE 1.4.x
- The another one compiled for JRE 1.3.x.
4. Advantages over old Together DocGen
FlexDoc/Together offers the following major advantages over the old DocGen module in Together:-
A new data model concept. Now, it is not based anymore on the Together specific notions (namely,
things described by RWI interface of Together OpenAPI). Instead, FlexDoc, in any its incarnation, always "thinks"
it works with an XML document. This allows to organize all data querying basing on XPath as well as gives
other immense possibilities of data processing -- virtually to turn inside out any data fed to FlexDoc with
just a few settings specified in templates!
Also, this approach provides a single platform independent on any particular application. As you can see on this web-site, we offer now a similar tool for Javadoc called FlexDoc/Javadoc.
FlexDoc/XML is another our product based on this technology. This tool allows to construct templates using data type information obtained from DTD and XSD (XML Schema) files and process data directly from XML files.
The next step about it will be creating with the FlexDoc/XML a set of templates specifically designed for OMG XMI® data sources (that is XMI files). In effect, this will provide a universal template-based doc-generator for virtually any modern UML modeling tool with all included XMI-specific templates open for the users to change!
-
Another huge advancement over the old DocGen is absolutely new formatting concept.
In the old DocGen, all formatting within templates was specified in notions of coordinates.
This was difficult and sometimes simply impossible to render correctly in such layout-based formats as HTML and RTF.
In FlexDoc, on the contrary, all formatting is directly specified using layouts (such as flow of text, paragraphs, tables and lists). This smoothly fits into the container organization of Java Swing components as well as all known output formats (HTML, RTF, PDF and so on). The result is that what you see in the Template Designer, you'll get in output documents.
Also, this approach allows using the same abstract formatting once specified in the templates to generate the outstanding quality documentation simultaneously in all output formats supported by FlexDoc (see screenshots).
- There are lots of other advancements which could make life easier for developers using FlexDoc such as full support of template parameters, all generator variable organized in the form of the Generator Object Model (similar to Document Object Model in dynamic HTML), about 100 general utility functions available in FlexQuery-expressions, which are small scripts widely used in FlexDoc templates to specify all kinds of dynamically computed settings.
-
The open part of FlexDoc API will allow to smoothly integrate the calls to FlexDoc generator
into your own Java code. The open API will allow:
- To launch the FlexDoc generators to interpret the specified templates from any Java application.
- To pass any parameters to the templates programmatically as well as by invoking the parameter inspector dialog.
- To extend your templates with the custom-written Java classes (called from within templates via 'callForName' function).