TOPCASED 4.

2
Gendoc2 v1.2.0 tutorial

2010/11/30
 What’s new (since 1.1.0) ?

• Pre registered parameters (slide 9)

• Additional services available outside TOPCASED (slide 35-39)

2 Topcased GenDoc2 Tutorial

 General mechanism

Inputs GenDoc2

Acceleo
Extract
scripts M2T

Acceleo
Template document Template Generated document

EMF models

3 Topcased GenDoc2 Tutorial

 Install

• Gendoc2 v1.2.0 is provided with TOPCASED 4.2.0

• Gendoc2 is also available from Gendoc2 update site :

http://topcased-mm.gforge.enseeiht.fr/release/market-place/gendoc2/update-site/

• Or on Eclipse MarketPlace :
http://marketplace.eclipse.org/content/gendoc2

4 Topcased GenDoc2 Tutorial

 Documentation Generation – Main Steps

• Step1 : Create the template document using a text editor (Word or Open Office)
 Create a document and add all non generated information

• Step2 : Insert script part

 Variable parts that will be replaced by generated documentation

• Step3 : Launch the Generation

5 Topcased GenDoc2 Tutorial

 Step 1 : Create the template document

• The first step is to create the template document

• Create a new docx or odt document
• Or get an existing document (with the company charter for example)
• If you start from a Doc file, save it into Docx format
- Possibility to use the Microsoft Office Compatibility Pack for Word, Excel, and PowerPoint 2007 File Formats
http://www.microsoft.com/downloads/details.aspx?FamilyID=941b3470-3ae9-4aee-8f43-c6bb74cd1466&displaylang=en

• Write in the document all information that will not be generated from the models
 Cover page
 Header, footer
 Chapter title
 …

6 Topcased GenDoc2 Tutorial

 Step 2 : Insert script part

• Once the template document is created, insert script instructions at the location you want to
generate documentation
• The generation will execute these instructions.
 They will extract information from the input models and will generate the documentation

• In Gendoc2, script parts are written between the tags <gendoc> and </ gendoc >
• The script language is Acceleo: http://wiki.eclipse.org/Acceleo
• The syntax of Gendoc2 scripts is exactly the same as the Acceleo syntax
 In the Acceleo syntax, variable parts are defined between special characters [ and ]
 Example

Acceleo Gendoc2
[ for(e:Element|self.ownedElement) ] <gendoc> [for(e : Element|self.ownedElement)]
[e.name/] • [e.name/]
[ /for ] [ /for ] </gendoc>

• Styles are taken into account

 Example : <gendoc>[self.name/]</gendoc> will generate: MyName

7 Topcased GenDoc2 Tutorial

 Step 2 : Insert script part – configuration tag

1. Configure the script execution with the optional <config> tag

 It can own an optional <output> tag with a path attribute that targets the output file of the generation
If not present, the file is generated in template file location, with suffix ‘_generated’.

 It can own many <param> tags with (key, value) attributes to define global variables for the script parts

These variables can be used inside other <param> definition or inside context, by using: ${paramKey}

 Example : <config>
<output path='D:/myFile.docx' />
<param key='modelFolder' value=‘C:/GenDocTutorial/Models' />
<param key='model' value='${modelFolder}/EquipmentMonitoring.uml'/>
</config>

 Detailed schema for <config> tag :

Gendoc version (default = ‘v2’) File output absolute path

(default: templatePath + suffix
« _generated »)
Script language (default=‘acceleo’)

Parameter key (must be unique

inside a document)

Parameter value
8 Topcased GenDoc2 Tutorial
 Step 2 : Insert script part – pre defined parameters

• Pre defined parameters

 Some <param> are pre defined in Gendoc2 and can be used directly in the template
- ${workspace_loc} is the location of the workspace used for the
transformation
• Example : value='${workspace_loc}/GenDocTutorial/Models/EquipementMonitoring.uml'
- ${input} is the name of the input template document
• Example : <output path='${project}/Generated/${input}-generated.docx' />
 If the input document is template.docx, the result is
 .../template-generated.docx
- ${date} is the date of the generation
• Example : <output path='${project}/Generated/${input}-generated-${date}.docx' />
• The format of the date is 'yyyy-MM-dd-HHmmss'
 Result for example : 2010-10-18-093707

9 Topcased GenDoc2 Tutorial

 Step 2 : Insert script part – context tag

1. Define a global context to specify the model and the base element:

 The context tag can contain an optional attribute : importedBundles, used to give access to specific external classes
defined in a bundle.
 Example: <context model='${MODEL}' element='ModelRoot/MyPackage/MyClass'
importedBundles='topcased;myBundle' />

 Detailed schema for <context> tag:

(MANDATORY) Model file absolute path

(OPTIONAL) Model element path (default : model root/ If defined, must start with model root element)=

(OPTIONAL) Label of the element property used to identify an element in the

element path (default: property « name » of the element)
(OPTIONAL) Set to ‘true’ if your model uses multiple metamodels (ex: SysML models)
(default : false)
 WARNINGS :
(OPTIONAL) List of external bundles to import (bundle names, separated by « ; » )
- The context tag must be defined at least once in the document.

- When executing a script, the last defined context is used.

- Values of the attributes that are not updated are kept from previous context (ex: importedBundles can be defined only
once in the document)

10 Topcased GenDoc2 Tutorial

 Step 2 : Insert script part – context tag

There are several ways to define an element path inside <context> tag :

A. Using qualified name (all elements must have the property ‘name’)
 Property ‘name’ is used for all elements in path
 Ex : <context … element=‘modelRoot/package2/subPackage1’/>

B. Using another property of the elements for all path

 Ex : <context … element=‘id1/id2/id3’ labelFeature=‘id’/>
Property ‘id’ is used for all elements in path
 Note : Case A is equivalent to <context … element=‘modelRoot/package1/subPackage1’
labelFeature=‘name’/>

C. Use another property only for some elements in path

 Ex : <context … element=‘modelRoot/id=“id2”/subPackage1’/>
Property ‘id’ is used only for the package part of the element path
D. Using indexes of the position inside model tree (starting at 0 and not 1)
 Ex: <context … element=‘modelRoot/{1}/subPackage1’/>
If package2 is at the second place inside the model.

11 Topcased GenDoc2 Tutorial

 Step 2 : Insert script part - Acceleo

1. Add <gendoc> tags containing Acceleo script

Examples of content :
- Acceleo script or static string
including :
- loops
- conditional statements
- images
- tables
- Acceleo services
an Acceleo service can either be called on the first parameter or with all
parameters :
[param1.myMethod(param2)/] is equivalent to : [myMethod(param1,param2)/]

12 Topcased GenDoc2 Tutorial

 Syntax Elements (1)

• Loop
 Loop is handled using the for expression. It is used to iterate on list objects
 Example:
<gendoc>
…
[for ( c:Class | self.ownedElement->filter(Class)) ]
The class name is : [c.name/]
…
[for (p:Property | c.ownedAttribute->filter(Property))]
- property [p.name/] : [p.type/]
[/for]
[/for]
…
</gendoc>

 Result for the model on the right :

The class name is : Class1
…
- property Property1 : String
- property Property2 : Boolean
The class name is : Class2
…
- property PropertyA : String
- property PropertyB : Integer
- property PropertyC : String

13 Topcased GenDoc2 Tutorial

 Syntax Elements (2)

• Conditional Statement
 Conditional expression is handled using the if – else expression
<gendoc>
…
[if ( self.oclIsKindOf(Class) ) ]
Current element is a Class
[else]
Current element is not a Class
[/if]
…
</gendoc>

• Variable declaration
 Local variables can be declared using the let instruction
 Example:
<gendoc>
…
[let myVariable : Class = c]
class name: [myVariable.name/]
[/let]
…
</gendoc>

14 Topcased GenDoc2 Tutorial

 Syntax Elements: Image Tags (1)

• Image:
 The import of existing images is done using the <image> tag and
- either the filePath attribute : for an image full path
- or the object attribute : for an image from a diagram

 The <image> tag shall contain a drawing area that will be used to contain the image
 Example:
With an image file: <gendoc><image filePath=‘D:/myImage.jpg’ keepW=‘true’ keepH=‘false’>

An empty drawing area

</image></gendoc>

With an image object: <gendoc><image object=‘[self.getDiagram()/]’ keepW=‘true’>

An empty drawing area

</image></gendoc>

Note : Insertion of an empty drawing area :

For OpenOffice, use menu : Insert -> Frame.
For Office 2007, use menu : Insert -> Shapes -> New drawing canvas.
For Office 2003 (with compatibility pack), use menu : Insert -> Image -> New drawing

15 Topcased GenDoc2 Tutorial

 Syntax Elements: Image Tags (2)

• Image:
 Attributes ‘keepW’ and ‘keepH’ can be used to keep the width or height of the frame. Default values :
keepW=‘false’ and keepH=‘false’.

 Attributes ‘maxW’ and ‘maxH’ can be used to set the width or height of the frame as the maximum.
Default values : maxW=‘false’ and maxH=‘false’.

 If ‘keep’ dimensions set then image will always be scaled. If both values are set the image may not
retain the original aspect ratio.

 If ‘max’ dimensions set then image will only be scaled if native dimensions are too large. The image
will always retain the original aspect ratio.

 If both ‘keep’ and ‘max’ dimensions are set the ‘keep’ scaling is applied first with ‘max‘ applied to the
result.

keepH=‘true’ maxH=‘false’
keepW=‘false’ maxW=‘true’

Apply keep … then

first … max

16 Topcased GenDoc2 Tutorial

 Syntax Elements (5)

• Table: All table rows found inside <table> tag are merged in a unique table.
 Example :
<gendoc> …
<table>
[self.name/] Documentation
[for (u:UseCase|self.ownedElement)]
[u.name/] [u.getDocumentation()/]

[/for] </table>
…</gendoc>

 After generation :

realtimeMonitoring Documentation
monitor equipment The system analyses signals sent by equipments
regularly. The received signals are frames with
the equipment state. Frame format differs
according to the equipment category.
handle proven failure The system displays a procedure to handle the
failure. This procedure differs according to the
equipment type.
17 Topcased GenDoc2 Tutorial
 Syntax Elements: List Tags

• Lists: All list items inside a <list> tag are merged into a single list
 Example:

<gendoc> …
<list>
[for (u:UseCase|self.ownedElement)]
• [u.name/]
[/for]
</list> …
</gendoc>

 After generation:

• monitor equipment
• handle proven failure

18 Topcased GenDoc2 Tutorial

 Syntax Elements: Drop Tags

• Drop: Any paragraphs containing a <drop> tag are removed from the generated
document.
 Example:

<gendoc> …
[for (p:Element|self.ownedElement)] <drop/>
[if (p.oclIsKindOf(Package))] <drop/>
[p.name/]
[/if] <drop/>
[/for] <drop/>
</gendoc>

• This allows code to be written on separate lines (making it more readable) without
generating extra paragraphs in the final document.
• A multi-line comment can also be created inside a drop tag.

19 Topcased GenDoc2 Tutorial

 Syntax Elements: dropEmpty Tags

• <dropEmpty> will drop a paragraph if the tag content is empty.

 Example:

<gendoc> …
Description: <dropEmpty>[p.getDocumentation()/]</dropEmpty>
</gendoc>

 Will drop the entire paragraph if the element does not have any
documentation.

20 Topcased GenDoc2 Tutorial

 Syntax Elements: nobr Tags

• No Break: Removes the break between one paragraph and the next.
 Example:
<gendoc> …
Name: <nobr/>
[if ( … )]<drop/>
[p.name/]
[else]<drop/>
[p.id/]
[/if]<drop/>
</gendoc>

 Output:

Name: Use Case View

• <nobr> tags are processed after <drop> tags.

21 Topcased GenDoc2 Tutorial

 Syntax Elements: Nested Tags

• Nested Tags: Tags can be nested inside other tags.

 Example:
<gendoc> …
<list>
[for (p1:Package|self.ownedElement)]
• [p1.name/]
<list>
[for (p2:Package|self.ownedElement)]
 [p2.name/]
[/for]
</list> …
[/for]
</list> …
</gendoc>
 After generation:

• Use Case View

 Actors
 domains
• Deployment View
 Logical View
 Component View

22 Topcased GenDoc2 Tutorial

 Use of external bundles

• External bundles can be defined in order to provide a set of Acceleo services that
reference Java methods.

 Three bundles are already defined :

- commons
- topcased
- requirement

• The description of external bundles creation is detailed in a dedicated tutorial

(available on http://gforge.enseeiht.fr/docman/?group_id=102# section “Gendoc2 > Tutorials)

23 Topcased GenDoc2 Tutorial

 Commons bundle

• Usage : nothing to add inside attribute “importedBundles” of the <context>.

Installed by default.
• Services provided :
 clean(String) : String
- Cleaning of special characters inside the given String
To use if a string is obtained from a model and can contain special characters such as: <, >, &,’,”
 splitNewLine(String) : Set(String)
- Split the specified String on the line separator and return a Set of each line to manage manually
new lines in a text.

24 Topcased GenDoc2 Tutorial

 Requirements bundle

• Usage : add “requirement” inside attribute “importedBundles” of the <context>

• Services provided :
 getRequirementList(EObject):Sequence(CurrentRequirement)
- Get the list of current requirements associated to an EObject
 getAllUpstreamRequirements(EObject):Sequence(ttm::Requirement)
- Get the list of all the upstream requirements link to an EObject
 getAllLinkTo(CurrentRequirement):Sequence(ttm::Requirement)
- Get the list of all the upstream requirements referenced by a linkTo from a CurrentRequirement

25 Topcased GenDoc2 Tutorial

 Topcased bundle

• Usage : add “topcased” inside attribute “importedBundles” of the <context>

• Services provided :
 getAuthor(EObject) : String
- Get the author annotation linked to the object
 getDiagram(EObject) : String
- Get the diagram ID of the first diagram associated to an object : to use in <image object=‘…’ … />
 getDiagramID(Diagram) : String
- Get the diagram ID of the diagram : to use in <image object=‘…’ … />
 getDiagramWithName(EObject, String) : Diagram
- Get the diagram with a specific name associated to the given object
 getDiagramIDWithName(EObject, String) : Diagram
- Get the diagram ID with a specific name associated to the given object
 getDocumentation(EObject) : String
- Get the documentation associated to an object
 getAllDiagrams(EObject) : Sequence(Diagram)
- Get all the diagrams associated to an element
 getFirstDiagram(EObject) : Diagram
- Get the first diagram associated to an object
 getElementsInDiagram(Diagram) : Sequence(EObject)
- Get all the elements of the model displayed in the diagram
 isDiagramEmpty(Diagram) : Boolean
- Indicates if the diagram passed as a parameter is empty or not.
Usage : [if(not(self.getFirstDiagram().isDiagramEmpty()))] DISPLAY DIAGRAM [/if]
 getSortedContent(EObject) : Sequence(EObject)
- Get the sorted list of element defined in TOPCASED or if there is no information store if an algoritm is available it
is performed otherwise eContents() is returned
 getStrictSortedContent(EObject) : Sequence(EObject)
- Get the order stored in the model using TOPCASED functionalities
 getSortedResolvedContent(EObject) : Sequence(EObject)
- Get the order using algorithm registered or eContents if no algorithms are available
26 Topcased GenDoc2 Tutorial
 Step 3 : Launch the Generation

• Right click on the ODT or DOCX file > Generate Document

• The document is generated :

 Either in the same location that the template file
(if no “outputPath” attribute is specified)
 Or in the value of “outputPath” location if any

27 Topcased GenDoc2 Tutorial

 Script errors management

• In case of errors during execution of a script part :

 Other script parts are executed
 The document is generated
 In place of the script execution result, the following message pattern is written :
- --- ERROR DURING GENERATION OF THIS PART (see log file) ---
- Message of the Acceleo error. Ex : « The invocation isn’t terminated » when a bracket is not
closed
- Content of the original script part
- --- END ERROR ---

28 Topcased GenDoc2 Tutorial

 Solutions to common errors

• Module XXX not found. : The external bundle specified is missing. Check that this bundle is present
in the environment (copied into « dropins » directory – see sl.6) , and that it is present in the attribute
« importedBundles » of tag « context ».
• The Acceleo script contains invalid blocks. Check that all tags are well
formed. : Some tags are not well closed. Ex : “[for (…)]” with missing “[/for]”, or “[if]” with
missing “[/if]”
• Cannot find operation XXX. : The external bundle referencing this operation is not referenced
inside “importedBundles” attribute of “context” tag.

29 Topcased GenDoc2 Tutorial

 Template example for a UML Class diagram
<config>
<param key=’project’ value=’D:\MyProject’/>
<param key='model' value=‘${project}/models/myModel.uml' />
WARNING:
<output path='${project}/generated/generated_file.docx' /> Values to replace by your own model path
</config>

[…]
<context model=’${model}’ importedBundles=’topcased’ searchMetamodels=’true’/>

•<gendoc>
Model Structure
[for (p:Package|self.ownedElement)]
1.1 [p.name/]
[if (p.getAllDiagrams()->size() > 0)]
<image object=’[self.getDiagram()/]’ keepW=‘true’>
WARNING : this frame is lost with copy/paste of this example. Create it again inside your document.

Figure 1 : [p.name/] diagram

</image>
[/if]
[for (p.ownedElement->filter(Package)->sortedBy(name)) ]
1. 1. 1 [self.name/]
[for (e:NamedElement|self.ownedElement)]
(i) [e.name.clean()/]
[if (e.oclIsKindOf(Class))]
[for (p:uml::Property | e.oclAsType(Class).ownedAttribute)]
- Property: [p.name/]
[/for]
[/if]
[/for]
[/for]
[/for]
</gendoc>

30 Topcased GenDoc2 Tutorial

 Example (result)

31 Topcased GenDoc2 Tutorial

 Usage with Microsoft Office 2003 and 2007

After document generation you can update fields of your document with F9 command.
You may need to update the index, table of figures, captions, etc.
• Office 2007
 You can select all your document (ctrl + A) et press F9 to update all the fields

• Office 2003 with compatibility pack

 Update all the document will remove the figures. You must update the index and table of
figures manually or use the macro provided on attachment of the feature request :
http://gforge.enseeiht.fr/tracker/?group_id=52&atid=133&func=detail&aid=3328

 If you need to update the captions manually:

- right click on a caption
- Choose menu action « Select text with the same form »
- Press F9 

32 Topcased GenDoc2 Tutorial

 Full Example

• The full example is available on gforge (http://gforge.enseeiht.fr/frs/?group_id=102)

 “Documents” section > Gendoc2/Tutorials/Gendoc2Tutorial

• Import the project into your workspace

• Open the template documents "gendoc2_tutorial.docx" and "gendoc2_tutorial.odt"
and enter you workspace location in the parameter 'workspace‘
• Generate the documents

33 Topcased GenDoc2 Tutorial

 Batch mode

• A dedicated tutorial is available on www.topcased.org.

• Example
java -cp "TOPCASED_PATH\plugins\org.eclipse.equinox.launcher_XXXX.jar"
org.eclipse.core.launcher.Main -application
org.topcased.gendoc2.batch.Gendoc2BatchMode -idt
dir="D:\LOCAL\Alexia\Topcased\Gendoc2\Gendoc2Tutorial\Templates\Gendoc2_
tutorial.docx"

34 Topcased GenDoc2 Tutorial

 Additional services
available outside TOPCASED

• Several additional services are available on Eclipse MarketPlace

http://marketplace.eclipse.org/content/gendoc2
• Those services are also available on gendoc2 update site :
http://topcased-mm.gforge.enseeiht.fr/release/market-place/gendoc2/update-site/

Available services :
• Rich text tag
• GMF bundle

• EPF model loader

35 Topcased GenDoc2 Tutorial

 Additional services : Rich Text

• Install Rich text feature from the update site

• A new <richText> tag is available and allows to include html content inside the
generated document
• Exemple : display of Topcased Rich text Documentation
<gendoc>
[for (p:Package|self.ownedElement->filter(Package))]
 [p.name/]
<richText>[p.getDocumentation()/]</richText>
[/for]
</gendoc> <drop/>

Result :

Documentation view – HTML Editor

36 Topcased GenDoc2 Tutorial

 Additional services : GMF bundle

If you want to use Gendoc2 with GMF models :

• Download GMF specific services feature from Gendoc2 update site

http://topcased-mm.gforge.enseeiht.fr/release/market-place/gendoc2/update-site/

• Usage :
add “gmf” inside attribute “importedBundles” of the <context> inside your template
document

37 Topcased GenDoc2 Tutorial

 Additional services : GMF bundle

• Services provided :
 getElementsInDiagram(Diagram):Sequence(EObject)
- Get all elements containing in the diagram
 isDiagramEmpty(Diagram) : boolean
- Indicates if the diagram passed as a parameter is empty or not.
 getDiagramsUsingRelativePath(EObject, String) : Sequence(Diagram)
- Get the diagrams from relative path for an object
 getDiagramsUsingAbsolutePath(EObject, String) : Sequence(Diagram)
- Get the diagrams from absolute path for an object
 getDiagramsUsingExtension(EObject, String) : Sequence(Diagram)
- Get the diagrams from resource with the arg1 extension for an object
 getDiagramsUsingNotation(EObject) : Sequence(Diagram)
- Get the diagrams from a .notation resource for an object
 getDiagramsInModel(EObject) : Sequence(Diagram)
- Get diagrams contained in the model file resource for an object
 getDiagram(Diagram) : String
- Get diagram id for a diagram

38 Topcased GenDoc2 Tutorial

 Additional services : EPF

• If you want to use Gendoc2 with EPF models :

http://www.eclipse.org/epf/

• Get EPF environment inside your Eclipse installation

• Download EPF specific services feature from Gendoc2 update site
• EPF models are very specific so you need to use a specific EPF Model Loader
Service , by using attribute « services » of <context> tag.

• Usage :
<context services=‘EPFLoader’ />

39 Topcased GenDoc2 Tutorial