Borland Together: Document Generation

One of the key ways of producing value from a UML modeling tool is being able to generate wide variety of documents and reports in differing formats from one or more models.

For example, it is much more productive to press a button to generate:

  1. a new version of a large specification document consisting substantially of information from a UML model than it is to cut and paste the modified diagrams and update supporting text manually.
  2. up to date internet/intranet pages showing the latest analysis, design and implementation diagrams and details than maintain the HTML and image files manually.
  3. reports summarizing key aspects of a model than to collate the information manually from one or more models

Borland Together 2007 can generate all sorts of external documentation from models held in one or more Together projects. In fact, Together 2007 includes three different document generation engines and two different model-to-text transformation engines.

The Past: GenHTML

Together 2007 still retains the genHTML engine, the first document generation feature provided by Together. This originally used the model diagrams and extra Javadoc tags provided by Together's LiveSource™ technology to generate a better version of the standard Javadoc output.  The format and content produced by genHTML was relatively fixed but did include a handy little applet that improved navigation. It also produced detailed image maps behind generated images of the diagrams so that a user could click on an item in a diagram and jump to the relevant detail for that item.

Output from Together 2007 GenHTML Engine
Figure 1: Output from Together 2007 GenHTML Engine

Today, the content and format of the output produced by the genHTML engine is driven by the same kinds of document templates as the more powerful gendoc engine. Indeed, with the one exception of the navigation applet, there is nothing that genHTML can produce that gendoc cannot. Hopefully, one day, this one exception will be removed so that the genHTML engine can be finally retired but until then it remains a very quick way of producing a read-only, HTML-based view of one or more UML, BPMN, and ERD models.

The Present: Gendoc

Together's document template-based, gendoc engine can generate simple HTML, RTF, plain text, PDF, XSL-FO, and multi-frame HTML documentation. Gendoc templates can 'call' other gendoc templates. This means libraries of useful templates can be constructed and combined in different ways to form new document templates quickly.

Gendoc Template Designer
Figure 2: Gendoc Template Designer

Once mastered, Together's gendoc template designer (figure 2)  has always been very powerful but did used to require extensions coded in Java to do some commonly needed things. These days with support for Object Constraint Language (OCL) expressions throughout a template, the need for Java coding has all but disappeared.

The gendoc engine can also extract linked data from Borland CaliberRM requirements management repositories and include it in generated documents.

The Future: BIRT?

The Eclipse Business Intelligence Reporting Tool (BIRT) is a powerful, open-source report definition and generation framework. Designed primarily to work on data in relational databases, it can be extended to use other kinds of data source and query language. Together 2007 includes early work done to present model data as BIRT data sources. While currently unable to do half the things that the Together gendoc engine can, the future of document generation in Together might owe more to BIRT than gendoc.

Model to Text Transformations

For documents, reports or model extracts that do not need to include images of the diagrams, there are two additional generation alternatives. Called transformations because they officially form part of the OMG Model Driven Architecture (MDA) features of Together 2007, XML Stylesheets or Eclipse Modeling Facility (EMF) API's can be used to extract information from a model in Together.

XSL-based transformations

This type of transformation uses the Extensible Stylesheet Language (XSL) but instead of the XPath patterns used to retrieve information from an XML document, OCL queries are used to retrieve information from a Together model.

EMF API-based transformations

Together 2007 is largely built on top of the Eclipse Modeling Facility (EMF). This provides a Java API that can be used to query and manipulate models. This means these transformations have the full power of the Java language and libraries available to them.