Not everyone uses modeling tools and the awesome work one can do with these tools must be conveyed to the outside world, for instance, in the form of documents. The M2Doc technology enables the generation of Office Open XML documents from Ecore models and Sirius representations. The overall approach M2Doc implements consists in creating templates in the OOX format where static text authoring benefit from the WYSIWYG capabilities of the usual tools (e.g. Microsoft Word). Dynamic parts are inserted using a dedicated vocabulary of OOX fields code. Fields are mainly used to insert page numbers, references, etc. M2Doc makes use them to describe documentation generation directives. This allows a total separation between the document and the M2Doc directives. The template language makes an extensive use of the Acceleo Query Language which provides a full fledged, extensible model query language and engine. In this talk, I will present the M2Doc technology and talk about the way it is integrated with Sirius.

1. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
1
Document Generation with
M2Doc
Laurent Delaigue

2. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
2
Why documents?
• Written Documents are still necessary
– Transmit information to people who will not use
the modeling workbench directly
– Fulfil certain obligations
• The Model should be the reference
– Up to date documentation

3. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
3
M2Doc Genesys
CASID/DGSIC
(French Department of Defense)
© Alexander W. Galbraith - This image is available from the City of Toronto Archives, listed under the archival citation Fonds 1568, Item 177.

4. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
4
Our Solution
M2Doc

5. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
5
Our Solution
Model to documentation

6. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
6
Basic Principles
M2Doc
Template
Model
Document

7. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
7
Document
Basic Principles
M2Doc
Template
ModelModel
Document
A380
Technical specifications –DDE-H35
Applicable Documents
Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet
Lorem ipsum
dolor sit amet
lorem ipsum
dolor sit amet
dolorem ipsu
m dolor sit am

8. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
8
Document
A380
Technical specifications –DDE-H35
Applicable Documents
Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet
Lorem ipsum
dolor sit amet
lorem ipsum
dolor sit amet
dolorem ipsu
m dolor sit am
Basic Principles
M2Doc
Template
Model
Template B
Template C
Document B
A380
General Overview –DDE-H35
Applicable Documents
Lorem ipsum dolor sit amet
Document C
A380
Structure Breakdown –DDE-H35
Applicable Documents
ipsum dolor sit amet meae quam

9. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
9
Roles Involved
Metamodel Expert
• Creates, tests and
debugs reusable AQL
services
• Registers services
Templatist
• Creates M2Doc
templates
• Uses AQL services
• Tests and debugs
templates
End-User
• Edit models
• Produces documents
by running M2Doc
templates
• Edit ‘userdoc’ in
generated documents
These are just roles
Can be 1, 2, or 3 persons
depending on complexity and organization

10. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
10
Writing Templates
• Plain MS Word™ document (.docx files)
• Use Alt+F9 to activate fields
• Use Ctrl+F9 to insert fields
• M2Doc syntax is very simple

11. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
11
{ m:xxx … }

12. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
12
Simple query
{ m:conf.name } is located in Paris
SiriusCon 2017 is located in Paris

13. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
13
Loop
{ m:for track | conf.tracks}
• Track: {m:track.name}
{ m:endfor }
• Track: Talks
• Track: Keynotes

14. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
14
Loop
{ m:for track | conf.tracks}
{ m:endfor }
{m:track.name} {m:track.description}
IoT Day Internet of Things
Eclipse Technologies Eclipse-related technologies and eclipse
community
OSGi Talks about OSGi

15. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
15
Conditional
{ m:if conf.name.contains('Eclipse') }
…
{ m:else if …}
…
{ m:else }
…
{ m:endif }
Optional

16. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
16
User Doc
{m:userdoc <queryID>}
…
{m:enduserdoc}
• Incremental generation

17. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
17
Bookmark and link
{m:bookmark <queryID>}
…
{m:endbookmark}
{m:link <queryID> <queryText>}

18. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
18
Let
{m:let cName = conf.name}
…
{ m:cName } is located in Paris
…
{m:endlet}

19. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
19
Using Services
{m:if
conf.tracks.talks
−>select(t|t.name.contains('Sirius'))
−>notEmpty()}

20. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
20
Using Services
{ m:if conf.hasTalkAbout('Sirius') }
public boolean hasTalkAbout(Conference, String)

21. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
21
Declaring Services
• Services are plain Java methods
• Can be tested, reused, …
• Can provide:
– model objects,
– images,
– tables,
– formatted text, …
• Registered via an extension point
• Must be imported explicitly in genconf

22. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
22
Validation
{ m:conf. } is located in Paris
{ m:conf. } <---Expression “conf." is invalid:
missing feature access or service call is located
in Paris

23. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
23
M2Doc + Sirius = ♥
• SiriusSession = <URI of representations.aird>
• Diagrams and Tables can be inserted
• The existence of a diagram/table can be
checked
– Dedicated services are provided
• isRepresentation(DescriptionName)
• asImageByRepresentation(DescriptionName)
• asTableByRepresentation(DescriptionName)
• …

24. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
24
M2DOC DEMO

25. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
25
Architecture Overview
AQL Apache POI EMF
M2Doc core
Sirius
M2Doc IDE
M2Doc UI
M2Doc Sirius Integration

26. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
26
Architecture Overview
AQL Apache POI EMF
M2Doc core
Your product
M2Doc IDE
M2Doc UI
M2Doc your product
Integration

27. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
27
Where do I start?
www.m2doc.org

28. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
28
M2Doc – Roadmap
• V1.0.0 has been released
– First maintained version
– Fully documented
• Next
– Gather feedback
– Keep improving + features from feedback
– Improve Apache POI integration

29. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
29
Keypoints
• Produces MS Word™ documents from
EMF-compliant Models
• Can include Sirius Diagrams & Tables
• Easy to use: simple syntax, tooling helps
• Has Useful Error Reporting
• Supports Incremental Generation

30. ©copyright2017Obeo
ThisdocumentisthepropertyofObeoandcannotbetransmittedwithoutpriorwrittenagreement
30