<!DOCTYPE HTML>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <meta name="description" content="M2Doc - Generate MS Word Documents from Your Models" />
  <meta name="author" content="Obeo" />

  <title>Reference Documentation - M2Doc</title>
  <link href="../../images/favicon.ico" rel="shortcut icon" />
  <!-- Bootstrap core CSS -->
  <link href="../../css/bootstrap.css" rel="stylesheet" />

  <!-- Pygments CSS -->
  <link href="../../css/pygments.css" rel="stylesheet" />

  <!-- Add custom CSS here -->
  <link href="../../css/style.css" rel="stylesheet" />
  <link href="../../font-awesome/css/font-awesome.min.css" rel="stylesheet" />

  <!-- Bootstrap CDN to add Font Awesom -->
  <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css" />

  <link href="../../css/main.css" rel="stylesheet" />

  <!-- Google Fonts -->
  <link href="https://fonts.googleapis.com/css?family=Open+Sans+Condensed:300,300italic,700" rel="stylesheet" type="text/css"
  />
  <link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800"
    rel="stylesheet" type="text/css" />

</head>


<body>
  <nav class="navbar navbar-inverse navbar-fixed-top" role="navigation">
  <div class="container">
    <div class="navbar-header">
      <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-ex1-collapse">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>

      <!-- You'll want to use a responsive image option so this logo looks good on devices - I recommend using something like retina.js (do a quick Google search for it and you'll find it) -->
      <a class="navbar-brand" href="../.."><img src="../../images/logo_M2Doc.png" alt="" height="54"/></a>
    </div>

    <!-- Collect the nav links, forms, and other content for toggling -->
    <div class="collapse navbar-collapse navbar-ex1-collapse">
      <ul class="nav navbar-nav navbar-right">
      
        
        <li><a href="../../ref-doc/nightly/index#overview">OVERVIEW</a></li>
        
      
        
        <li><a href="../../download">DOWNLOAD</a></li>
        
      
        
        <li class="dropdown">
          <a href="#" class="dropdown-toggle" data-toggle="dropdown">GET STARTED <b class="caret"></b></a>
          <ul class="dropdown-menu">
            
            	
            	<li><a href="../../ref-doc/nightly/index.html#generating-a-document">Generate a document</a></li>
            	
            
            	
            	<li><a href="../../ref-doc/nightly/index.html#template-authoring">Write a template</a></li>
            	
            
            	
      	    	<li><a href="../../capella/index.html">Use with Capella</a></li>
      	    	
            
          </ul>
        </li>
        
      
        
        <li class="dropdown">
          <a href="#" class="dropdown-toggle" data-toggle="dropdown">GET INVOLVED <b class="caret"></b></a>
          <ul class="dropdown-menu">
            
            	
            	<li><a href="../../developer-guide/contribute.html#report">Report issues</a></li>
            	
            
            	
            	<li><a href="../../developer-guide/contribute.html#ask">Ask questions</a></li>
            	
            
            	
            	<li><a href="../../developer-guide/contribute.html#contribute">Contribute</a></li>
            	
            
          </ul>
        </li>
        
      
        
        <li class="dropdown">
          <a href="#" class="dropdown-toggle" data-toggle="dropdown">DOCUMENTATION <b class="caret"></b></a>
          <ul class="dropdown-menu">
            
            	
      	    	<li><a href="../../ref-doc/nightly/index.html">Nightly</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/4.0.0/index.html">4.0.0</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/3.3.4/index.html">3.3.4</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/3.3.3/index.html">3.3.3</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/3.3.2/index.html">3.3.2</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/3.3.1/index.html">3.3.1</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/3.3.0/index.html">3.3.0</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/3.2.2/index.html">3.2.2</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/3.2.1/index.html">3.2.1</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/3.2.0/index.html">3.2.0</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/3.1.1/index.html">3.1.1</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/3.1.0/index.html">3.1.0</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/3.0.0/index.html">3.0.0</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/2.0.3/index.html">2.0.3</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/2.0.2/index.html">2.0.2</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/2.0.1/index.html">2.0.1</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/2.0.0/index.html">2.0.0</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/1.1.0/index.html">1.1.0</a></li>
      	    	
            
            	
      	    	<li><a href="../../ref-doc/1.0.0/index.html">1.0.0</a></li>
      	    	
            
          </ul>
        </li>
        
      
        
        <li><a href="../../support">SUPPORT</a></li>
        
      
        
        <li><a href="../../faq">FAQ</a></li>
        
      

      </ul>
    </div><!-- /.navbar-header -->
  </div><!-- /.container -->
</nav>

<div id="mainbody">
  <div class="page-masthead bg_green2">
<div class="container">
  <div class="row">
    <div class="col-lg-12">
      <h1 class="page-header">Reference Documentation <small class="green1">Nightly</small></h1>
    </div>
  </div>
  </div><!-- /.container -->
</div><!-- /.page-masthead -->
 
<div class="container">
  <div class="row">
    <div class="col-lg-12">
      <h1 id="table-of-content">Table of Content</h1>

<p>Following you will find the reference documentation corresponding to the <strong>Nightly</strong> version.
If you need an other version use one of our <a href="../../download/#all-versions">released versions</a>.</p>

<ul id="markdown-toc">
  <li><a href="#table-of-content" id="markdown-toc-table-of-content">Table of Content</a>    <ul>
      <li><a href="#overview" id="markdown-toc-overview">Overview</a>        <ul>
          <li><a href="#principles" id="markdown-toc-principles">Principles</a></li>
          <li><a href="#main-steps" id="markdown-toc-main-steps">Main steps</a></li>
          <li><a href="#m2doc-roles" id="markdown-toc-m2doc-roles">M2Doc roles</a>            <ul>
              <li><a href="#template-user" id="markdown-toc-template-user">Template user</a></li>
              <li><a href="#template-developer" id="markdown-toc-template-developer">Template developer</a></li>
              <li><a href="#integrator" id="markdown-toc-integrator">Integrator</a></li>
            </ul>
          </li>
        </ul>
      </li>
      <li><a href="#architecture" id="markdown-toc-architecture">Architecture</a></li>
      <li><a href="#generating-a-document" id="markdown-toc-generating-a-document">Generating a document</a>        <ul>
          <li><a href="#launching-a-generation" id="markdown-toc-launching-a-generation">Launching a generation</a></li>
          <li><a href="#initializing-a-generation-configuration" id="markdown-toc-initializing-a-generation-configuration">Initializing a generation configuration</a></li>
          <li><a href="#validating-a-generation-setup" id="markdown-toc-validating-a-generation-setup">Validating a generation setup</a></li>
          <li><a href="#generation-configuration-wizard" id="markdown-toc-generation-configuration-wizard">Generation configuration wizard</a></li>
        </ul>
      </li>
      <li><a href="#template-authoring" id="markdown-toc-template-authoring">Template authoring</a>        <ul>
          <li><a href="#new-project-wizard" id="markdown-toc-new-project-wizard">New project wizard</a></li>
          <li><a href="#new-template-wizard" id="markdown-toc-new-template-wizard">New template wizard</a></li>
          <li><a href="#m2doc-interpreter-view" id="markdown-toc-m2doc-interpreter-view">M2Doc interpreter view</a></li>
          <li><a href="#syntax" id="markdown-toc-syntax">Syntax</a>            <ul>
              <li><a href="#comment-example" id="markdown-toc-comment-example">Comment (example)</a></li>
              <li><a href="#comment-block-example" id="markdown-toc-comment-block-example">Comment block (example)</a></li>
              <li><a href="#static-statement" id="markdown-toc-static-statement">Static statement</a></li>
              <li><a href="#query-example" id="markdown-toc-query-example">Query (example)</a></li>
              <li><a href="#conditional-example" id="markdown-toc-conditional-example">Conditional (example)</a></li>
              <li><a href="#repetition-example" id="markdown-toc-repetition-example">Repetition (example)</a></li>
              <li><a href="#let-example" id="markdown-toc-let-example">Let (example)</a></li>
              <li><a href="#bookmark-example" id="markdown-toc-bookmark-example">Bookmark (example)</a></li>
              <li><a href="#link-example" id="markdown-toc-link-example">Link (example)</a></li>
              <li><a href="#user-documentation-example" id="markdown-toc-user-documentation-example">User Documentation (example)</a></li>
              <li><a href="#template-construct-example" id="markdown-toc-template-construct-example">Template construct (example)</a></li>
            </ul>
          </li>
          <li><a href="#template-construct-reuse" id="markdown-toc-template-construct-reuse">Template construct reuse</a>            <ul>
              <li><a href="#extend" id="markdown-toc-extend">Extend</a></li>
              <li><a href="#import" id="markdown-toc-import">Import</a></li>
            </ul>
          </li>
          <li><a href="#services" id="markdown-toc-services">Services</a></li>
          <li><a href="#template-properties-wizard" id="markdown-toc-template-properties-wizard">Template properties wizard</a></li>
          <li><a href="#template-custom-properties" id="markdown-toc-template-custom-properties">Template custom properties</a>            <ul>
              <li><a href="#m2doc-version-custom-properties" id="markdown-toc-m2doc-version-custom-properties">M2Doc version custom properties</a></li>
              <li><a href="#variable-custom-properties" id="markdown-toc-variable-custom-properties">Variable custom properties</a></li>
              <li><a href="#package-custom-properties" id="markdown-toc-package-custom-properties">Package custom properties</a></li>
              <li><a href="#extend-custom-properties" id="markdown-toc-extend-custom-properties">Extend custom properties</a></li>
              <li><a href="#import-custom-properties" id="markdown-toc-import-custom-properties">Import custom properties</a></li>
            </ul>
          </li>
          <li><a href="#template-libraries" id="markdown-toc-template-libraries">Template Libraries</a></li>
        </ul>
      </li>
      <li><a href="#providing-new-services" id="markdown-toc-providing-new-services">Providing new services</a>        <ul>
          <li><a href="#service-class" id="markdown-toc-service-class">Service class</a>            <ul>
              <li><a href="#default-constructor" id="markdown-toc-default-constructor">Default constructor</a></li>
              <li><a href="#custom-constructor" id="markdown-toc-custom-constructor">Custom constructor</a></li>
              <li><a href="#special-return-types" id="markdown-toc-special-return-types">Special return types</a></li>
            </ul>
          </li>
          <li><a href="#template" id="markdown-toc-template">Template</a></li>
        </ul>
      </li>
      <li><a href="#template-migration" id="markdown-toc-template-migration">Template migration</a></li>
      <li><a href="#extension-points" id="markdown-toc-extension-points">Extension points</a>        <ul>
          <li><a href="#services-and-packages-token" id="markdown-toc-services-and-packages-token">Services and packages token</a></li>
          <li><a href="#template-registry" id="markdown-toc-template-registry">Template registry</a>            <ul>
              <li><a href="#import-registered-template" id="markdown-toc-import-registered-template">Import registered template</a></li>
            </ul>
          </li>
        </ul>
      </li>
      <li><a href="#template-testing" id="markdown-toc-template-testing">Template testing</a></li>
      <li><a href="#maventycho" id="markdown-toc-maventycho">Maven/Tycho</a></li>
      <li><a href="#using-m2doc-programmatically" id="markdown-toc-using-m2doc-programmatically">Using M2Doc programmatically</a>        <ul>
          <li><a href="#parsing" id="markdown-toc-parsing">Parsing</a></li>
          <li><a href="#validation" id="markdown-toc-validation">Validation</a>            <ul>
              <li><a href="#core-validation-api" id="markdown-toc-core-validation-api">Core validation API</a></li>
              <li><a href="#generation-configuration-api" id="markdown-toc-generation-configuration-api">Generation configuration API</a></li>
            </ul>
          </li>
          <li><a href="#generation" id="markdown-toc-generation">Generation</a>            <ul>
              <li><a href="#core-generation-api" id="markdown-toc-core-generation-api">Core generation API</a></li>
              <li><a href="#generation-configuration-api-1" id="markdown-toc-generation-configuration-api-1">Generation configuration API</a></li>
            </ul>
          </li>
        </ul>
      </li>
      <li><a href="#maven" id="markdown-toc-maven">Maven</a></li>
    </ul>
  </li>
</ul>

<h2 id="overview">Overview</h2>

<p>The M2Doc project provides Word document (.docx files) generation based on a document template and <a href="https://www.eclipse.dev/modeling/emf/">EMF</a> models.</p>

<p>The overall approach consists in creating templates in the <a href="https://en.wikipedia.org/wiki/Office_Open_XML">OOXML</a> format where static text authoring benefits from the WYSIWYG capabilities of Microsoft Word. Dynamic parts are inserted using a dedicated vocabulary of <a href="https://en.wikipedia.org/wiki/Office_Open_XML">OOXML</a> fields code. Fields are mainly used to insert page numbers, references, etc. M2Doc makes use of them to describe documentation generation directives. This allows a total separation between the document and the M2Doc directives.</p>

<p><img src="../../ref-doc/nightly/images/m2doc-overview.png" alt="Overview" /></p>

<p>As an example, here is a fragment of a M2Doc template used to generate the documentation of a database model:</p>

<p><img src="../../ref-doc/nightly/images/DBTemplate.png" alt="DB Template" /></p>

<p>The generation looks like this:</p>

<p><img src="../../ref-doc/nightly/images/DBResult.png" alt="DB Result" /></p>

<p>The template language makes an extensive use of the <a href="https://www.eclipse.dev/acceleo/documentation/aql.html">Acceleo Query Language</a> which provides a full-fledged, extensible model query language and engine. 
The M2Doc templates can be <a href="index.html#validating-a-generation-setup">validated</a>. If errors are found, an annotated templates is produced describing the problems found.</p>

<h3 id="principles">Principles</h3>

<ul>
  <li>Definition of model entry points
    <ul>
      <li>Declaration of variables (see the <a href="index.html#template-properties-wizard">Template properties wizard</a> section)</li>
      <li>Mapping with model elements (see the <a href="index.html#generation-configuration-wizard">Generation configuration wizard</a> section)</li>
    </ul>
  </li>
</ul>

<p><img src="../../ref-doc/nightly/images/Variable%20definition.png" alt="Variable definition" title="Variable definition." /></p>

<ul>
  <li>Extraction of information by navigating the model (see the <a href="index.html#template-authoring">Template authoring</a> section)
    <ul>
      <li>From the entry points</li>
      <li>Using model relations</li>
    </ul>
  </li>
</ul>

<p><img src="../../ref-doc/nightly/images/Extracting%20information.png" alt="Extracting information" title="Extracting information." /></p>

<ul>
  <li>Formatting of the output information
    <ul>
      <li>Using Microsoft Word functionalities</li>
    </ul>
  </li>
</ul>

<p><img src="../../ref-doc/nightly/images/Formatting%20template.png" alt="Formatting template" title="Formatting template." /></p>

<h3 id="main-steps">Main steps</h3>

<ul>
  <li>Definition of content, navigation, and format (see the <a href="index.html#template-authoring">Template authoring</a> section)</li>
  <li>Declaration of variables (see the <a href="index.html#template-properties-wizard">Template properties wizard</a> section)</li>
  <li>Mapping of variables with model elements, definition of input model and output file (see the <a href="index.html#generation-configuration-wizard">Generation configuration wizard</a> section)</li>
  <li>Generation of output document (see the <a href="index.html#generating-a-document">Generate a document</a> section)</li>
</ul>

<p><img src="../../ref-doc/nightly/images/Main%20steps.png" alt="Main steps" title="Main steps." /></p>

<h3 id="m2doc-roles">M2Doc roles</h3>

<p>Ready to try M2Doc! You might have one of the following roles:</p>

<h4 id="template-user">Template user</h4>

<p>You already have the template and want to generate the document:</p>

<ul>
  <li>see <a href="index.html#generating-a-document">Generate a document</a></li>
  <li>see <a href="index.html#maven">Maven</a> (optional)</li>
</ul>

<h4 id="template-developer">Template developer</h4>

<p>You want to create your own template:</p>

<ul>
  <li>see <a href="index.html#template-authoring">Template authoring</a></li>
  <li>see <a href="index.html#providing-new-services">Provide new services</a> (optional)</li>
  <li>see <a href="index.html#validating-a-generation-setup">Validating a generation</a> (optional)</li>
  <li>see <a href="index.html#template-testing">Template testing</a> (optional)</li>
</ul>

<h4 id="integrator">Integrator</h4>

<p>You want to provide document generation in your own project using M2Doc:</p>

<ul>
  <li>see <a href="index.html#using-m2doc-programmatically">Using M2Doc programmatically</a></li>
  <li>see <a href="https://www.eclipse.dev/acceleo/documentation/aql.html#UsingAQLprogrammatically">Using AQL programmatically</a> (optional)</li>
</ul>

<h2 id="architecture">Architecture</h2>

<p>The main workflow:</p>

<p><img src="../../ref-doc/nightly/images/M2DocWorkflow.png" alt="M2Doc Workflow" /></p>

<p>The template is parsed in an internal representation (the AST). From here you can bind the variables to their values, using elements from a model for instance and evaluate the template to generate the output document. An added benefit of using M2Doc is the hability to <a href="index.html#validating-a-generation-setup">validate</a> a template to produce an annotated template containing informations, warnings and errors the template might contain.</p>

<p>The architecture of M2Doc is organized around three building blocks:</p>
<ul>
  <li><a href="https://poi.apache.org/">Apache POI</a> for the parsing and generation of <a href="https://en.wikipedia.org/wiki/Office_Open_XML">OOXML</a> documents</li>
  <li><a href="https://www.eclipse.dev/acceleo/documentation/aql.html">AQL</a> for querying the models</li>
  <li><a href="https://www.eclipse.dev/modeling/emf/">EMF</a> as a general platform</li>
</ul>

<p><img src="../../ref-doc/nightly/images/TechnicalArchitecture.png" alt="Technical architecture" /></p>

<p><a name="generate-a-document"></a></p>
<h2 id="generating-a-document">Generating a document</h2>

<p>To generate a document you will need at least a template file (.docx file) and a generation configuration model (.genconf file). If you don’t have the template you can read the <a href="index.html#template-authoring">template authoring</a> section. To create a generation model file you can read the <a href="index.html#initializing-a-generation-configuration">initialize generation</a> section.</p>

<h3 id="launching-a-generation">Launching a generation</h3>

<p>To launch a generation you can right click on the generation configuration model (.genconf file) or the Generation object and select the «Generate Documentation menu» as shown here:</p>

<p><img src="../../ref-doc/nightly/images/Generate%20Documentation%20menu.png" alt="The Generate Documentation menu." title="The Generate Documentation menu." /></p>

<p>You can also use the «M2Doc Generate Template» menu on the template that is referenced by one or more generation configuration models (.genconf file):</p>

<p><img src="../../ref-doc/nightly/images/M2Doc%20Generate%20Template%20menu.png" alt="The M2Doc Generate Template menu." title="The M2Doc Generate Template menu." /></p>

<p>Or the «M2Doc Update Document» menu on the generated document that is referenced by one or more generation configuration models (.genconf file):</p>

<p><img src="../../ref-doc/nightly/images/M2Doc%20Update%20Document%20menu.png" alt="The M2Doc Update Document menu." title="The M2Doc Generate Document menu." /></p>

<p>If you don’t have the the generation model configuration file you can create it using the <a href="index.html#initializing-a-generation-configuration">initialize generation</a> section.</p>

<h3 id="initializing-a-generation-configuration">Initializing a generation configuration</h3>

<p>To initialize a generation configuration you will need a template file (.docx file). If you don’t have the template you can read the <a href="index.html#template-authoring">template authoring</a> section.</p>

<p>Right click on the template file and select the «Initialize Documentation Configuration» menu:</p>

<p><img src="../../ref-doc/nightly/images/Initialize%20Documentation%20Configuration%20menu.png" alt="The Initialize Documentation Configuration menu." title="The Initialize Documentation Configuration menu." /></p>

<p>To edit the created generation model file you can use the <a href="index.html#generation-configuration-wizard">Generation configuration wizard</a>.</p>

<h3 id="validating-a-generation-setup">Validating a generation setup</h3>

<p>To validate a generation setup (template plus generation configuration) you can right click on the generation configuration model (.genconf file) or the Generation object and select the «Validate Documentation menu» as shown here:</p>

<p><img src="../../ref-doc/nightly/images/Validate%20Documentation%20menu.png" alt="The Validate Documentation menu." title="The Validate Documentation menu." /></p>

<p>If you don’t have the the generation configuration model file you can create it using the <a href="index.html#initializing-a-generation-configuration">initialize generation</a> section. If the validation succeeds with no informations, warnings, or errors you will be prompted. If something went wrong a .docx file with the name of the template and suffixed with «info», «warning», or «error» will be created. This new file contains details of the validation issues. The template is <em>not</em> modified.</p>

<h3 id="generation-configuration-wizard">Generation configuration wizard</h3>

<p>You can access the generation configuration wizard in two different ways, one for creating it and one for further edition when the .genconf file already exists.</p>

<p>To create and initialize the generation configuration, select the template .docx file to use for generation and right click on it:</p>

<p><img src="../../ref-doc/nightly/images/Initialize%20Documentation%20Configuration%20menu.png" alt="The Initialize Documentation Configuration menu." title="The Initialize Documentation Configuration menu." /></p>

<p>To edit an existing generation configuration .genconf file you can select the .genconf file and right click on it:</p>

<p><img src="../../ref-doc/nightly/images/Edit%20Documentation%20Configuration%20menu.png" alt="The Edit Documentation Configuration menu." title="The Edit Documentation Configuration menu." /></p>

<p>At this point you should be on the first page of the generation configuration wizard:</p>

<p><img src="../../ref-doc/nightly/images/Generation%20Configuration%20Wizard1.png" alt="The Generation Configuration Wizard." title="The Generation Configuration Wizard." /></p>

<p>On this page you can select the path of the generation configuration .genconf file. It can be changed to create a copy of an existing file for instance. Other file paths are relative to the generation configuration file. This allow to move a folder containing all the files needed for a generation without breaking the generation configuration. The template can be selected from the workspace, the <a href="index.html#template-registry">Template registry</a>, or <a href="index.html#template-libraries">Template libraries</a> (in the two last cases the path will be absolute):</p>

<ul>
  <li>workspace: allows to browse templates in the workspace.</li>
  <li><a href="index.html#template-registry">Template registry</a>: allows to browse templates in deployed plug-ins.</li>
  <li><a href="index.html#template-libraries">Template libraries</a>: allows to browse templates in template libraries.</li>
</ul>

<p>The next page of the wizard is dedicated to variables and binding values to them:</p>

<p><img src="../../ref-doc/nightly/images/Generation%20Configuration%20Wizard2.png" alt="The Generation Configuration Wizard." title="The Generation Configuration Wizard." /></p>

<p>To reference new values you can load new resources using the <code class="language-plaintext highlighter-rouge">Load resource</code> button. Note the <code class="language-plaintext highlighter-rouge">Options (expert)</code> tab that allow to set advanced options to find values from a Sirius session for instance.</p>

<p>If you are using M2Doc with <a href="https://www.eclipse.dev/sirius/">Sirius</a>, <a href="https://www.obeodesigner.com/en/">Obeo Designer</a>, <a href="https://www.obeodesigner.com/en/collaborative-features">Obeo Designer Team</a>, <a href="https://mbse-capella.org/">Capella</a>, or <a href="https://www.obeosoft.com/en/capella-professional-offer">Team for Capella</a>, you need to set the SiriusSession option. This will allow you to use <a href="index.html#services">Sirius services</a> like exporting diagrams as images:</p>

<p><img src="../../capella/images/SiriusSession%20Option.png" alt="SiriusSession Option." title="SiriusSession Option." /></p>

<p>Setting this option should allow you to select model elements for each model variable you have in your template. By default the first element matching the declared type of the variable will be selected, but you can edit the value by selecting the variable and using the edit button:</p>

<p><img src="../../capella/images/Edit%20Variable.png" alt="Edit Variable." title="Edit Variable." /></p>

<p>When the <code class="language-plaintext highlighter-rouge">Finish</code> button is pushed the generation configuration file is created or edited.</p>

<p>You can also use M2Doc with <a href="https://www.obeosoft.com/en/capella-professional-offer">Team for Capella</a> or <a href="https://www.obeodesigner.com/en/collaborative-features">Obeo Designer Team</a>. If you had existing .genconf files before you shared your project to Team for Capella or Obeo Designer Team, you will need to edit them.</p>

<p>First you need to change the SiriusSession since the .aird file has been renamed. You should need to add “team” like this:</p>

<ul>
  <li>In-Flight Entertainment System.aird</li>
</ul>

<p>becomes:</p>

<ul>
  <li>In-Flight Entertainment System.team.aird</li>
</ul>

<p>Secondly you will need to set the value of your model variables since the model has been moved to the Team server. By default the first element matching the declared type of the variable will be selected, but you can edit the value by selecting the variable and using the edit button:</p>

<p><img src="../../capella/images/Edit%20Variable.png" alt="Edit Variable." title="Edit Variable." /></p>

<p>You will see your model to select the value from:</p>

<p><img src="../../capella/images/Select%20Variable%20Value.png" alt="Select Variable Value." title="Select Variable Value." /></p>

<h2 id="template-authoring">Template authoring</h2>

<p>You need to have a model already to be able to generate a document with M2Doc. Then you can <a href="index.html#new-project-wizard">create a project</a> or if you already have a project, you can <a href="index.html#new-template-wizard">create a template</a>.</p>

<h3 id="new-project-wizard">New project wizard</h3>

<p>This wizard is the fastest and easiest way to get you started with M2Doc. But it wont allow you to use <a href="index.html#providing-new-services">custom services</a>. To do so, you need to create a Java project and make sure your service Class is accessible in the classpath of the project.</p>

<p>This wizard allows to create all needed artifacts:</p>

<ul>
  <li>an Eclipse project</li>
  <li>a default template</li>
  <li>the genconf file</li>
</ul>

<p>You only need your model as input.</p>

<p>To launch the wizard right click in the project exporer and select new project:</p>

<p><img src="../../ref-doc/nightly/images/New%20Project%20Wizard1.png" alt="The New project Wizard." title="The New project Wizard." /></p>

<p>Then select M2Doc project in the M2Doc category:</p>

<p><img src="../../ref-doc/nightly/images/New%20Project%20Wizard2.png" alt="The New project Wizard." title="The New project Wizard." /></p>

<p>Enter your project name and click next:</p>

<p><img src="../../ref-doc/nightly/images/New%20Project%20Wizard3.png" alt="The New project Wizard." title="The New project Wizard." /></p>

<p>Enter your template name and click next:</p>

<p><img src="../../ref-doc/nightly/images/New%20Project%20Wizard4.png" alt="The New project Wizard." title="The New project Wizard." /></p>

<p>Select the main variable value and name then click next:</p>

<p><img src="../../ref-doc/nightly/images/New%20Project%20Wizard5.png" alt="The New project Wizard." title="The New project Wizard." /></p>

<p><img src="../../ref-doc/nightly/images/New%20Project%20Wizard6.png" alt="The New project Wizard." title="The New project Wizard." /></p>

<p>The last page of the wizard is dedicated to file pathes:</p>

<p><img src="../../ref-doc/nightly/images/New%20Project%20Wizard7.png" alt="The New project Wizard." title="The New project Wizard." /></p>

<p>NOTE: you can also start the generation on finish.</p>

<h3 id="new-template-wizard">New template wizard</h3>

<p>This wizard creates a simple template from a model.</p>

<p>To launch the wizard right click in the project exporer and select new other:</p>

<p><img src="../../ref-doc/nightly/images/New%20Template%20Wizard1.png" alt="The New template Wizard." title="The New template Wizard." /></p>

<p>Then select new template in the M2Doc category and click next:</p>

<p><img src="../../ref-doc/nightly/images/New%20Template%20Wizard2.png" alt="The New template Wizard." title="The New template Wizard." /></p>

<p>Enter your template name:</p>

<p><img src="../../ref-doc/nightly/images/New%20Template%20Wizard3.png" alt="The New template Wizard." title="The New template Wizard." /></p>

<p>Select the main variable value and name then click next:</p>

<p><img src="../../ref-doc/nightly/images/New%20Template%20Wizard4.png" alt="The New template Wizard." title="The New template Wizard." /></p>

<p><img src="../../ref-doc/nightly/images/New%20Template%20Wizard5.png" alt="The New template Wizard." title="The New template Wizard." /></p>

<p>The template is created after clicking finish:</p>

<p><img src="../../ref-doc/nightly/images/New%20Template%20Wizard6.png" alt="The New template Wizard." title="The New template Wizard." /></p>

<h3 id="m2doc-interpreter-view">M2Doc interpreter view</h3>

<p>The M2Doc interpreter view provides completion for <a href="https://www.eclipse.dev/acceleo/documentation/aql.html">AQL</a> expressions in the context of a generation model (.genconf file). To create a generation model file you can read the <a href="index.html#initializing-a-generation-configuration">initialize generation</a> section.</p>

<p>To open the M2Doc interpreter view, select the Windows / Show View / Other… :</p>

<p><img src="../../ref-doc/nightly/images/Interpreter%20view1.png" alt="M2Doc Interpreter View." title="M2Doc Interpreter View." /></p>

<p>Then select the M2Doc interpreter in the M2Doc category:</p>

<p><img src="../../ref-doc/nightly/images/Interpreter%20view2.png" alt="M2Doc Interpreter View." title="M2Doc Interpreter View." /></p>

<p>To start using the view, you need to select a generation model (.genconf file):</p>

<p><img src="../../ref-doc/nightly/images/Interpreter%20view3.png" alt="M2Doc Interpreter View." title="M2Doc Interpreter View." /></p>

<p>Select your generation model (.genconf file) in the following dialog:</p>

<p><img src="../../ref-doc/nightly/images/Interpreter%20view4.png" alt="M2Doc Interpreter View." title="M2Doc Interpreter View." /></p>

<p>You can then start typing <a href="https://www.eclipse.dev/acceleo/documentation/aql.html">AQL</a> expressions and use CTRL+SPACE for completion:</p>

<p><img src="../../ref-doc/nightly/images/Interpreter%20view5.png" alt="M2Doc Interpreter View." title="M2Doc Interpreter View." /></p>

<p>Note that you have access to variables declared in your template and also to a variable named «selection» that contains the current selected element.</p>

<p>You can also use the reload command to refresh the generation context, for instance when the template is modified or the source code of your services is modified:</p>

<p><img src="../../ref-doc/nightly/images/Interpreter%20view6.png" alt="M2Doc Interpreter View." title="M2Doc Interpreter View." /></p>

<p>When an error/warning/info is detected, you can over the message to highlight the corresponding part of the expression:</p>

<p><img src="../../ref-doc/nightly/images/Interpreter%20view7.png" alt="M2Doc Interpreter View." title="M2Doc Interpreter View." /></p>

<h3 id="syntax">Syntax</h3>

<p>The template should be edited using your Microsoft Word document editor. Older versions of M2Doc used Word fields to declare dynamic elements. Since version 4.0.0 M2Doc statements are in plain text:</p>

<p><code class="language-plaintext highlighter-rouge">{m:...}</code></p>

<p>The start <code class="language-plaintext highlighter-rouge">{m:</code> can’t contain spaces nor tabulation (for instance <code class="language-plaintext highlighter-rouge">{ m:</code> is not a M2Doc statement). Also each instruction should start and end in the same paragraph.</p>

<p>M2Doc is an imperative template language built on top of <a href="https://www.eclipse.dev/acceleo/documentation/aql.html">AQL</a> for querying. The language supports type inference and can be extended using <a href="index.html#providing-new-services">custom services</a>.</p>

<p>In order to create your <a href="https://www.eclipse.dev/acceleo/documentation/aql.html">AQL</a> expressions with completion and see the result for a selected object you can use the <a href="index.html#m2doc-interpreter-view">M2Doc interpreter</a>.</p>

<h4 id="comment-example">Comment (<a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/org.obeonetwork.m2doc.tests/resources/comment/nominal">example</a>)</h4>

<p>A simple comment, nothing is generated. It can be used to add specific text style to your document without having the text generated. The style can then be used later in the template.</p>

<p><code class="language-plaintext highlighter-rouge">{m:comment any text}</code></p>

<p>If you want to use a variable named ‘comment’ you can use an extra space after ‘m:’.</p>

<h4 id="comment-block-example">Comment block (<a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/org.obeonetwork.m2doc.tests/resources/comment/commentBlockNominal">example</a>)</h4>

<p>A comment block, the commented block is not generated. It can be used to add specific text or table style, or numbering to your document without having the text or table generated. The style or numbering can then be used later in the template.</p>

<p><code class="language-plaintext highlighter-rouge">{m:commentblock any text}</code></p>

<p><code class="language-plaintext highlighter-rouge">...commented block...</code></p>

<p><code class="language-plaintext highlighter-rouge">{m:endcommentblock}</code></p>

<p>If you want to use a variable named ‘commentblock’ or ‘endcommentblock’ you can use an extra space after ‘m:’.</p>

<h4 id="static-statement">Static statement</h4>

<p>Anything that is not a M2Doc field is generated as is.</p>

<h4 id="query-example">Query (<a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/org.obeonetwork.m2doc.tests/resources/query/nominal">example</a>)</h4>

<p>The <a href="https://www.eclipse.dev/acceleo/documentation/aql.html">AQL expression</a> is evaluated and its result is inserted in the generated document. <a href="index.html#services">M2Doc services</a> and <a href="index.html#providing-new-services">provided services</a> can be used. Some <a href="index.html#special-return-types">specific return types</a> will be interpreted by M2Doc.</p>

<p><code class="language-plaintext highlighter-rouge">{m:AQL expression}</code></p>

<h4 id="conditional-example">Conditional (<a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/org.obeonetwork.m2doc.tests/resources/conditional/nominal">example</a>)</h4>

<p>If the condition is true the «then block» is inserted in the generated document. if it’s false and the «else if» condition is true the «else if block» is inserted. if all condition are false the «else block» is inserted. You can have zero or more «elseif blocks», zero or one «else block». All <a href="https://www.eclipse.dev/acceleo/documentation/aql.html">AQL expressions</a> should evaluate to a Boolean.</p>

<p><code class="language-plaintext highlighter-rouge">{m:if AQL expression}</code></p>

<p><code class="language-plaintext highlighter-rouge">...then block...</code></p>

<p><code class="language-plaintext highlighter-rouge">{m:elseif AQL expression}</code></p>

<p><code class="language-plaintext highlighter-rouge">...else if block...</code></p>

<p><code class="language-plaintext highlighter-rouge">{m:else}</code></p>

<p><code class="language-plaintext highlighter-rouge">...else block...</code></p>

<p>` {m:endif}`</p>

<p>If you want to use a variable named ‘elseif’, ‘else’, ‘endif’ you can use an extra space after ‘m:’. You can also use the AQL if exression if you add a space after ‘m:’.</p>

<h4 id="repetition-example">Repetition (<a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/org.obeonetwork.m2doc.tests/resources/repetition/nominal">example</a>)</h4>

<p>Generates the «repetition block» for each value of the <a href="https://www.eclipse.dev/acceleo/documentation/aql.html">AQL expression</a>.</p>

<p><code class="language-plaintext highlighter-rouge">{m:for variable | AQL expression} ...repetition block... {m:endfor}</code></p>

<p>If you want to use a variable named ‘for’ or ‘endfor’ you can use an extra space after ‘m:’.</p>

<h4 id="let-example">Let (<a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/org.obeonetwork.m2doc.tests/resources/repetition/nominal">example</a>)</h4>

<p>Declares a variable named «variable» with the result of the <a href="https://www.eclipse.dev/acceleo/documentation/aql.html">AQL expression</a> as its value. The variable is accessible in the «let block».</p>

<p><code class="language-plaintext highlighter-rouge">{m:let variable = AQL expression} ...let block... {m:endlet}</code></p>

<p>If you want to use a variable named ‘endlet’ you can use an extra space after ‘m:’. You can also use the AQL let exression if you add a space after ‘m:’.</p>

<h4 id="bookmark-example">Bookmark (<a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/org.obeonetwork.m2doc.tests/resources/bookmark/nominal">example</a>)</h4>

<p>Generates a bookmark with the result of the <a href="https://www.eclipse.dev/acceleo/documentation/aql.html">AQL expression</a> as identifier and the «bookmark block» as content.</p>

<p><code class="language-plaintext highlighter-rouge">{m:bookmark AQL expression} ...bookmark block... {m:endbookmark}</code></p>

<p>If you want to use a variable named ‘bookmark’ or ‘endbookmark’ you can use an extra space after ‘m:’.</p>

<h4 id="link-example">Link (<a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/org.obeonetwork.m2doc.tests/resources/bookmark/nominal">example</a>)</h4>

<p>Generates a link to the <a href="index.html#bookmark-examplehttpsgithubcomobeonetworkm2doctreemastertestsorgobeonetworkm2doctestsresourcesbookmarknominal">bookmark</a> with the given identifier and text.</p>

<p><code class="language-plaintext highlighter-rouge">{m:link AQL expression AQL expression}</code></p>

<p>The first <a href="https://www.eclipse.dev/acceleo/documentation/aql.html">AQL expression</a> id the identifier and the second one is the text to display.
If you want to use a variable named ‘link’ you can use an extra space after ‘m:’.</p>

<h4 id="user-documentation-example">User Documentation (<a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/org.obeonetwork.m2doc.tests/resources/userDoc/nominal">example</a>)</h4>

<p>Generates a user content block in the resulting document. If the generated document exists and already has a user content with the same id the previous user content is preserved, otherwise the «userdoc block» is generated.</p>

<p><code class="language-plaintext highlighter-rouge">{m:userdoc AQL expression} ...user block... {m:enduserdoc}</code></p>

<p>If a user content exists in a previously generated document and the id is not re-generated, the user content will by removed from the generated document and saved in a «lost» file.
If you want to use a variable named ‘userdoc’ or ‘enduserdoc’ you can use an extra space after ‘m:’.</p>

<h4 id="template-construct-example">Template construct (<a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/org.obeonetwork.m2doc.tests/resources/template/nominal">example</a>)</h4>

<p>A template construct is basically a block of template with parameters that can be called like a service. When the template construct is called its contents is inserted after all dynamic parts have been interpreted by M2Doc.</p>

<p><code class="language-plaintext highlighter-rouge">{m:template public myTemplate(a : Integer, b : Integer)} ...template block... {m:endtemplate}</code></p>

<p>This template can be called as follow using a simple <a href="index.html#query-example">query</a>:</p>

<p><code class="language-plaintext highlighter-rouge">{m:1.myTemplate(3)}</code></p>

<p>The template contruct visibility can be one of:</p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">public</code>: the template construct is visible by any document</li>
  <li><code class="language-plaintext highlighter-rouge">protected</code>: the template construct is visible by the current document and any other document extending it directly or indirectly</li>
  <li><code class="language-plaintext highlighter-rouge">private</code>: the template construct is visible only in the current document</li>
</ul>

<p>If you want more examples of M2Doc syntax you can have a look at the nominal cases in <a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/org.obeonetwork.m2doc.tests/resources">unit tests</a>.
If you want to use a variable named ‘template’ or ‘endtemplate’ you can use an extra space after ‘m:’.</p>

<h3 id="template-construct-reuse">Template construct reuse</h3>

<p>You can import and extend template to reuse and override <a href="index.html#template-construct-example">template constructs</a>. In both cases all templates needs to be in a Java project. Imported and extended template needs to be accessible by the classpath of the project.</p>

<h4 id="extend">Extend</h4>

<p>When you import a template, you can override public and protected <a href="index.html#template-construct-example">template constructs</a> from the extended template. To override a template construct, you need to write a template construct with the same signature (name and template parameter types).
When generating the top most template in the extend hierarchy will be used as the entry of the generation and all call to overridden template construct will be delegated to the bottom most override template construct in the extend hierarchy.</p>

<p>To extend the template you need to use the <a href="index.html#template-properties-wizard">Template properties wizard</a>.</p>

<h4 id="import">Import</h4>

<p>A template can be imported like any Java class. Once imported each public <a href="index.html#template-construct-example">template construct</a> can be called like any other service in AQL expressions. To import the template you need to use the <a href="index.html#template-properties-wizard">Template properties wizard</a>.</p>

<h3 id="services">Services</h3>

<p>All <a href="https://www.eclipse.dev/acceleo/documentation/aql.html#LanguageReference">AQL services</a> are available. On top of that, specific services are provided by M2Doc. See the following reference documentation. If you don’t find your needs in this list, you can <a href="index.html#providing-new-services">provide custom services</a>.</p>

<ul>
  <li><a href="../../ref-doc/nightly/m2doc_service_booleanservices.html">Boolean services</a></li>
  <li><a href="../../ref-doc/nightly/m2doc_service_documentservices.html">Document services</a></li>
  <li><a href="../../ref-doc/nightly/m2doc_service_m2doceobjectservices.html">EObject services</a></li>
  <li><a href="../../ref-doc/nightly/m2doc_service_excelservices.html">Excel services</a></li>
  <li><a href="../../ref-doc/nightly/m2doc_service_m2dochtmlservices.html">HTML services</a></li>
  <li><a href="../../ref-doc/nightly/m2doc_service_imageservices.html">Image services</a></li>
  <li><a href="../../ref-doc/nightly/m2doc_service_linkservices.html">Link services</a></li>
  <li><a href="../../ref-doc/nightly/m2doc_service_promptservices.html">Prompt services</a></li>
  <li><a href="../../ref-doc/nightly/m2doc_service_swtpromptservices.html">Prompt services (SWT)</a></li>
  <li><a href="../../ref-doc/nightly/m2doc_service_paginationservices.html">Pagination services</a></li>
  <li><a href="../../ref-doc/nightly/m2doc_service_m2docsiriusservices.html">Sirius services</a> (Note: M2Doc versions 1.1.0 and above are compatible with <a href="https://www.obeodesigner.com/en/collaborative-features">Obeo Designer Team Edition</a>.)
    <ul>
      <li>you will have to add the following packages nsURI (see <a href="index.html#template-properties-wizard">Template properties wizard</a> section): http://www.eclipse.org/sirius/1.1.0, http://www.eclipse.org/sirius/diagram/1.1.0, and/or http://www.eclipse.org/sirius/diagram/sequence/2.0.0.</li>
    </ul>
  </li>
  <li><a href="../../ref-doc/nightly/m2doc_service_m2docwikitextservices.html">Wikitext services</a> (exprerimental)</li>
</ul>

<p>Services specific to the <a href="../../capella/">M2Doc Capella extensions</a>:</p>

<ul>
  <li><a href="../../ref-doc/nightly/m2doc_service_m2docgenservices.html">Capella extensions</a></li>
  <li><a href="../../ref-doc/nightly/m2doc_service_semanticbrowserservices.html">Capella semantic browser</a></li>
</ul>

<p>NOTE: you will have to manually import the two services classes or select the “Capella” package in the <a href="index.html#template-properties-wizard">Template properties wizard</a>:</p>

<ul>
  <li>org.obeonetwork.capella.m2doc.aql.queries.M2DocGenServices</li>
  <li>org.obeonetwork.capella.m2doc.aql.queries.SemanticBrowserServices</li>
</ul>

<h3 id="template-properties-wizard">Template properties wizard</h3>

<p>The template propeties wizard allows to configure the template. You will be able to add or remove used metamodels (nsURI), service classes, you will also be able to specify the type of the variable used as input of your template.</p>

<p>To open the template properties wizard, you can select a template .docx file and right click on it:</p>

<p><img src="../../ref-doc/nightly/images/Edit%20Template%20Properties%20menu.png" alt="The Edit Template properties menu." title="The Edit Template properties menu." /></p>

<p>The first page of the wizard let you select template metamodels and services packages.</p>

<p><img src="../../ref-doc/nightly/images/Template%20Properties%20Wizard1.png" alt="The Edit Template properties wizard." title="The Edit Template properties wizard." /></p>

<p>When a service package is included in one or more other service packages you can have the following page:</p>

<p><img src="../../ref-doc/nightly/images/Template%20Properties%20Wizard1%20with%20included%20tokens.png" alt="The Edit Template properties wizard." title="The Edit Template properties wizard." /></p>

<p>In this example, the “other test token” is included in the “test token”. “other test token” can’t be deselected without deselecting “test token”.</p>

<p>Note you can also use the <code class="language-plaintext highlighter-rouge">nsURI (expert)</code> and <code class="language-plaintext highlighter-rouge">Services (expert)</code> to select metamodels and services manually. The service tab can be used to import Java service classes and select a template to extend.</p>

<p>The second page is dedicated to variable declarations. The list of declarations is initialized from the variable used in the template.</p>

<p><img src="../../ref-doc/nightly/images/Template%20Properties%20Wizard2.png" alt="The Edit Template properties wizard." title="The Edit Template properties wizard." /></p>

<p>The M2Doc version to use with this template can be changed on this page. Not having this property set will trigger a warning while <a href="index.html#validating-a-generation-setup">validating</a> with M2Doc 2.0.0 or above.</p>

<h3 id="template-custom-properties">Template custom properties</h3>

<p>You can use the <a href="index.html#template-properties-wizard">Template properties wizard</a>. But you can also edit them using your Microsoft Word document editor (see <a href="https://support.office.com/en-us/article/View-or-change-the-properties-for-an-Office-file-21d604c2-481e-4379-8e54-1dd4622c6b75?CorrelationId=866914c3-b0b5-42e8-aeb2-e9f7bcc216e2&amp;ui=en-US&amp;rs=en-US&amp;ad=US&amp;ocmsassetID=HA010047524">this page</a>). This section will describe possible properties name and value used by M2Doc.</p>

<h4 id="m2doc-version-custom-properties">M2Doc version custom properties</h4>

<p>To define the version of M2Doc to use with this template you can set a custom property as follow</p>

<ul>
  <li>Name: <code class="language-plaintext highlighter-rouge">m:M2DocVersion</code></li>
  <li>Value: <strong>M2Doc version</strong></li>
</ul>

<p>For example:</p>

<ul>
  <li>Name: <code class="language-plaintext highlighter-rouge">m:M2DocVersion</code></li>
  <li>Value: <code class="language-plaintext highlighter-rouge">2.0.0</code></li>
</ul>

<p>Not having this property set will trigger a warning while <a href="index.html#validating-a-generation-setup">validating</a> with M2Doc 2.0.0 or above.</p>

<h4 id="variable-custom-properties">Variable custom properties</h4>

<p>To define variables you can set a custom property as follow</p>

<ul>
  <li>Name: <code class="language-plaintext highlighter-rouge">m:var:</code><strong>variable name</strong></li>
  <li>Value: <strong>variable type</strong></li>
</ul>

<p>For example:</p>

<ul>
  <li>Name: <code class="language-plaintext highlighter-rouge">m:var:self</code></li>
  <li>Value: <code class="language-plaintext highlighter-rouge">ecore::EPackage</code></li>
</ul>

<h4 id="package-custom-properties">Package custom properties</h4>

<p>To use new EMF packages for typing you can add the following custom property:</p>

<ul>
  <li>Name: <code class="language-plaintext highlighter-rouge">m:uri:</code><strong>EPackage nsURI</strong></li>
  <li>Value:</li>
</ul>

<p>For example:</p>

<ul>
  <li>Name: <code class="language-plaintext highlighter-rouge">m:uri:https://www.eclipse.org/uml2/5.0.0/UML</code></li>
  <li>Value:</li>
</ul>

<h4 id="extend-custom-properties">Extend custom properties</h4>

<p>To extend an other template and override its <a href="index.html#template-construct-example">template constructs</a> you can add the following custom property:</p>

<ul>
  <li>Name: <code class="language-plaintext highlighter-rouge">m:extend:</code><strong>qualified name</strong></li>
  <li>Value:</li>
</ul>

<p>For example:</p>

<ul>
  <li>Name: <code class="language-plaintext highlighter-rouge">m:extend:org.obeonetwork.m2doc.rcptt.a.otherTemplate</code></li>
  <li>Value:</li>
</ul>

<h4 id="import-custom-properties">Import custom properties</h4>

<p>To import a service class with a <a href="index.html#default-constructor">default constructor</a>. To use a service class with a custom constructor you can read the <a href="index.html#custom-constructor">custom constructor</a> section.</p>

<ul>
  <li>Name: <code class="language-plaintext highlighter-rouge">m:import:</code><strong>qualified name</strong></li>
  <li>Value:</li>
</ul>

<p>For example:</p>

<ul>
  <li>Name: <code class="language-plaintext highlighter-rouge">m:import:org.obeonetwork.m2doc.rcptt.a.ServiceClassA</code></li>
  <li>Value:</li>
</ul>

<h3 id="template-libraries">Template Libraries</h3>

<p>Template libraries are a list of paths from the file system. They can be used to share M2Doc templates across environment via a network file system for instance. M2Doc will scan provided library paths for template with one model element parameter and provides menu to launch the generation when a compatible element is selected.</p>

<p>First you will need to add path to your libraries using the M2Doc/libraries preference page. Select the Window Preferences menu:</p>

<p><img src="../../ref-doc/nightly/images/Preferences%20menu.png" alt="The preferences menu." title="The preferences menu." /></p>

<p>Then select the M2Doc/Libraries page:</p>

<p><img src="../../ref-doc/nightly/images/Libraries%20preferences.png" alt="The libraries preferences page." title="The libraries preferences page." /></p>

<p>You can use this page to add/remove library paths. Once you are done, you can click the apply and close button to validate your changes or the cancel button to cancel them.</p>

<p>In this example the selected path contains a template with one parameter of type EPackage. So we will demonstrate menus by selecting an EPackage object. But in your case it can be any model element type.</p>

<p>You can now select a model element that has at least one compatible template in one of the provided libraries and launch a generation using the “M2Doc Generate with Template Library” menu. You can select your element and right click on it:</p>

<p><img src="../../ref-doc/nightly/images/M2Doc%20Generate%20with%20Template%20Library menu.png" alt="The M2Doc Generate with Template Library menu." title="The M2Doc Generate with Template Library menu." /></p>

<p>Selecting this menu will open the following dialog:</p>

<p><img src="../../ref-doc/nightly/images/Generate%20with%20Template%20Library%20dialog.png" alt="The Generate with Template Library dialog." title="The Generate with Template Library dialog." /></p>

<p>In this dialog, you can select the template you want to generate with from the libraries and the output folder. The selected element will be used as the parameter of the generation. You can then click the finish button to launch the generation or the cancel button to cancel your action.</p>

<h2 id="providing-new-services">Providing new services</h2>

<p>You can extends M2Doc by adding services to your templates using the <a href="index.html#template-properties-wizard">Template properties wizard</a>. A service is a simple Java method with at least one parameter and a return value or a <a href="index.html#template-construct-example">template construct</a> from an other template.</p>

<p>To be able to access the service Class you template needs to be in a Java project and the Class needs to be accessible in the project classpath. When deployed the service Class needs to be in the current classpath.</p>

<p>You can create different types of Java projects:</p>

<ul>
  <li><a href="https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2FgettingStarted%2Fqs-3.htm">simple Java project</a></li>
  <li><a href="https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Fguide%2Ftools%2Fproject_wizards%2Fnew_plugin_project.htm&amp;cp%3D4_3_9_0_0">Eclipse plug-in project</a></li>
  <li><a href="https://www.vogella.com/tutorials/EclipseMaven/article.html">Maven project</a></li>
</ul>

<h3 id="service-class">Service class</h3>

<p>There are two cases for the class containing the service: either it has a <a href="index.html#default-constructor">default constructor</a>, or it has a <a href="index.html#custom-constructor">constructor with a parameter</a>.</p>

<h4 id="default-constructor">Default constructor</h4>

<p>When the class has no explicit constructor or the constructor doesn’t have any parameters. In this case you don’t need any specific development except for your service method. You can have a look at <a href="index.html#special-return-types">specific return types</a> if you want to insert images, table, etc… To use your services in your template simply add them through the <a href="index.html#template-properties-wizard">Template properties wizard</a>.</p>

<h4 id="custom-constructor">Custom constructor</h4>

<p>When there is an explicit constructor with at least a parameter M2Doc can’t instantiate your class since there is no default constructor. You need to implement the <a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc/src/org/obeonetwork/m2doc/services/configurator/IServicesConfigurator.java">IServicesConfigurator</a> interface. This interface link one or more options in the generation configuration to the service class in order to instantiate it. You need to use the org.obeonetwork.m2doc.ide.servicesConfigurator extension point to declare your implementation of <a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc/src/org/obeonetwork/m2doc/services/configurator/IServicesConfigurator.java">IServicesConfigurator</a>. If you want to use your implementation in standalone you can register it programmatically using M2DocUtils.registerServicesConfigurator().</p>

<p>An example of implementation can be found in the <a href="https://www.eclipse.dev/sirius/">Sirius</a> integration plug-in see the class <a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc.sirius/src/org/obeonetwork/m2doc/sirius/services/configurator/SiriusServiceConfigurator.java">SiriusServiceConfigurator</a> and the extension in the <a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc.sirius/plugin.xml">plugin.xml</a>.</p>

<h4 id="special-return-types">Special return types</h4>

<p>The M2Doc evaluation engine converts any object to a string in order to insert it in the generated document. To add flexibility in the produced document we chose to expose some special types to service creators. Those types are <a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc/src/org/obeonetwork/m2doc/element/MElement.java">MElement</a> and allow directly inserting document artifacts:</p>

<ul>
  <li><a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc/src/org/obeonetwork/m2doc/element/MPagination.java">MPagination</a> to insert a table of contents, a new page, a new paragraph, a new column, or a new text wrapping.</li>
  <li><a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc/src/org/obeonetwork/m2doc/element/MBookmark.java">MBookmark</a> to insert a new bookmark or a reference to a bookmark.</li>
  <li><a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc/src/org/obeonetwork/m2doc/element/MHyperLink.java">MHyperLink</a> to insert a new link to an <a href="https://en.wikipedia.org/wiki/URL">URL</a>.</li>
  <li><a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc/src/org/obeonetwork/m2doc/element/MImage.java">MImage</a> to insert a new image.</li>
  <li><a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc/src/org/obeonetwork/m2doc/element/MTable.java">MTable</a> to insert a new table.</li>
  <li><a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc/src/org/obeonetwork/m2doc/element/MText.java">MText</a> to insert styled text.</li>
  <li><a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc/src/org/obeonetwork/m2doc/element/MList.java">MList</a> to insert a list of <a href="https://github.com/ObeoNetwork/M2Doc/blob/master/plugins/org.obeonetwork.m2doc/src/org/obeonetwork/m2doc/element/MElement.java">MElement</a>.</li>
</ul>

<p>Default implementations are also provided by M2Doc in <a href="https://github.com/ObeoNetwork/M2Doc/tree/master/plugins/org.obeonetwork.m2doc/src/org/obeonetwork/m2doc/element/impl">this package</a>.</p>

<h3 id="template">Template</h3>

<p>You can import a template with public <a href="index.html#template-construct-example">template construct</a> to reuse them. You just need to specify the qualified name of the template (.docx file) and once imported public template construct can be called the same way as local template construct.</p>

<p>One important thing about styling. Styles are indexed using their ID. If a style is used in the imported template but not present in the calling template, it will be copied. If the style ID is already used in the calling template, then the calling template style is used. This allows the caller to override the styling when calling a template construct.</p>

<p>One example where this is useful is when you need to provide some document to several entities. For instance several suppliers or customers that have different style guides, You can create a template construct in a template that you will later import in the template for supplier A and an other template for customer B. And by reusing the same style IDs apply the needed style for supplier A and customer B without changing the content nor styling of the imported template construct.</p>

<h2 id="template-migration">Template migration</h2>

<p>The template format has changed between version 3.x and 4.x. In version 3.x M2Doc statements were stored in MS Word fields that could be visualized with <code class="language-plaintext highlighter-rouge">ALT+F9</code> and inserted with <code class="language-plaintext highlighter-rouge">CTRL+F9</code>. Since version 4.x the fields has been replaced by plain text (<code class="language-plaintext highlighter-rouge">{m:...}</code>).</p>

<p>You can migrate your template toward the current version of M2Doc by right clicking on the template an selecting the <code class="language-plaintext highlighter-rouge">Migrate template</code> menu.</p>

<p><img src="../../ref-doc/nightly/images/Migrate%20template%20menu.png" alt="The migrate template menu." title="The migrate template menu." /></p>

<p>This menu is only available if the template needs to be migrated according to its version number (see the <a href="index.html#template-properties-wizard">Template properties wizard</a> section).</p>

<h2 id="extension-points">Extension points</h2>

<h3 id="services-and-packages-token">Services and packages token</h3>

<p>The services and packages token extension point org.obeonetwork.m2doc.ide.services.register can be used to reference a set of <a href="index.html#default-constructor">service classes</a> and packages using a token name. This token can be selected using «Select tokens» menu in the <a href="index.html#template-properties-wizard">Template properties wizard</a>. You can find an example of this extension point <a href="https://github.com/ObeoNetwork/M2Doc/blob/master/tests/org.obeonetwork.m2doc.ide.tests/plugin.xml">here</a>.</p>

<h3 id="template-registry">Template registry</h3>

<p>It’s possible to package your templates and deploy them in Eclipse plugins. To register them you can use the extension point org.obeonetwork.m2doc.ide.templates.register, ther is an example <a href="https://github.com/ObeoNetwork/M2Doc/blob/master/tests/org.obeonetwork.m2doc.ide.tests/plugin.xml">here</a>.</p>

<h4 id="import-registered-template">Import registered template</h4>

<p>Once a template is registered (see the <a href="index.html#template-registry">Template registry</a> section), you can import it in the workspace for further modifications for instance:</p>

<p>Select the template import wizard:</p>

<p><img src="../../ref-doc/nightly/images/Import%20menu.png" alt="The import menu." title="The import menu." /></p>

<p><img src="../../ref-doc/nightly/images/Import%20Wizard%20Selection.png" alt="Import Wizard Selection." title="Import Wizard Selection." /></p>

<p><img src="../../ref-doc/nightly/images/Template%20Import%20Wizard1.png" alt="Select a template." title="Select a template." /></p>

<p><img src="../../ref-doc/nightly/images/Template%20Import%20Wizard2.png" alt="Select the target folder." title="Select the target folder." /></p>

<h2 id="template-testing">Template testing</h2>

<p>To simplify unit testing while developing M2Doc, a <a href="https://junit.org/junit4/">JUnit</a> test suite has been implemented. It uses a given folder as input and lists each sub directory following a naming pattern as a test case. You can use the same test suite for your own tests. An example of the test suite implementation <a href="https://github.com/ObeoNetwork/M2Doc/blob/master/tests/org.obeonetwork.m2doc.tests/src/org/obeonetwork/m2doc/tests/QueryTests.java">QueryTests</a> with the folder <a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/org.obeonetwork.m2doc.tests/resources/query">resources/query</a>.</p>

<h2 id="maventycho">Maven/Tycho</h2>

<p>You can launch your generation using <a href="https://maven.apache.org/">Maven</a> and <a href="https://eclipse.org/tycho/">Tycho</a>. An example is available <a href="https://github.com/ObeoNetwork/M2Doc/tree/master/releng/generate-with-maven-tycho">here</a>. You may probably need to have a look at the <a href="https://github.com/ObeoNetwork/M2Doc/blob/master/releng/generate-with-maven-tycho/myModelToDocx/pom.xml">pom.xml</a> file. To launch the build and the generation you can simply use the following command:</p>

<p><code class="language-plaintext highlighter-rouge">mvn clean verify</code></p>

<h2 id="using-m2doc-programmatically">Using M2Doc programmatically</h2>

<p>This section is for developers wanting to integrate M2Doc in their own project. It will show how to use the main features of M2Doc programmatically. Since M2Doc uses AQL for expressions it can be useful to have a look at <a href="https://www.eclipse.dev/acceleo/documentation/aql.html#UsingAQLprogrammatically">Using AQL programmatically</a>.</p>

<h3 id="parsing">Parsing</h3>

<p>The following sample code shows how to load a template .docx file using M2Doc:</p>

<figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kd">final</span> <span class="no">URI</span> <span class="n">templateURI</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// the URI of the template</span>
        
<span class="c1">// can be empty, if you are using a Generation use GenconfUtils.getOptions(generation)</span>
<span class="kd">final</span> <span class="nc">Map</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">,</span> <span class="nc">String</span><span class="o">&gt;</span> <span class="n">options</span> <span class="o">=</span> <span class="o">...;</span>
<span class="kd">final</span> <span class="nc">String</span> <span class="n">qualifiedName</span> <span class="o">=</span> <span class="o">...,</span>
<span class="nc">List</span><span class="o">&lt;</span><span class="nc">Exception</span><span class="o">&gt;</span> <span class="n">exceptions</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">ArrayList</span><span class="o">&lt;&gt;();</span>

<span class="nc">AQLUtils</span><span class="o">.</span><span class="na">registerServicesConfigurator</span><span class="o">(</span><span class="k">new</span> <span class="nc">ServicesConfiguratorDescriptor</span><span class="o">(</span><span class="nc">AQLUtils</span><span class="o">.</span><span class="na">AQL_LANGUAGE</span><span class="o">,</span>
		<span class="k">new</span> <span class="nf">AQLServiceConfigurator</span><span class="o">()));</span>

<span class="kd">final</span> <span class="nc">ResourceSet</span> <span class="n">resourceSetForModels</span> <span class="o">=</span> <span class="nc">AQLUtils</span><span class="o">.</span><span class="na">createResourceSetForModels</span><span class="o">(</span><span class="n">exceptions</span><span class="o">,</span> <span class="k">this</span><span class="o">,</span>
		<span class="k">new</span> <span class="nf">ResourceSetImpl</span><span class="o">(),</span> <span class="n">options</span><span class="o">);</span>
<span class="n">resourceSetForModels</span><span class="o">.</span><span class="na">getResourceFactoryRegistry</span><span class="o">().</span><span class="na">getExtensionToFactoryMap</span><span class="o">().</span><span class="na">put</span><span class="o">(</span><span class="s">"*"</span><span class="o">,</span>
		<span class="k">new</span> <span class="nf">XMIResourceFactoryImpl</span><span class="o">());</span>

<span class="kd">final</span> <span class="nc">Registry</span> <span class="n">ePackageRegistry</span> <span class="o">=</span> <span class="nc">EPackage</span><span class="o">.</span><span class="na">Registry</span><span class="o">.</span><span class="na">INSTANCE</span><span class="o">;</span>
<span class="kd">final</span> <span class="nc">IQualifiedNameResolver</span> <span class="n">resolver</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">ClassLoaderQualifiedNameResolver</span><span class="o">(</span><span class="k">this</span><span class="o">.</span><span class="na">getClass</span><span class="o">()</span>
		<span class="o">.</span><span class="na">getClassLoader</span><span class="o">(),</span> <span class="n">ePackageRegistry</span><span class="o">,</span> <span class="nc">M2DocUtils</span><span class="o">.</span><span class="na">QUALIFIER_SEPARATOR</span><span class="o">);</span>
<span class="kd">final</span> <span class="nc">IQualifiedNameQueryEnvironment</span> <span class="n">queryEnvironment</span> <span class="o">=</span> <span class="nc">M2DocUtils</span><span class="o">.</span><span class="na">getQueryEnvironment</span><span class="o">(</span><span class="n">resolver</span><span class="o">,</span>
		<span class="n">resourceSetForModels</span><span class="o">,</span> <span class="n">templateURI</span><span class="o">,</span> <span class="n">options</span><span class="o">,</span> <span class="kc">false</span><span class="o">);</span>
<span class="kd">final</span> <span class="nc">M2DocEvaluationEnvironment</span> <span class="n">m2docEnv</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">M2DocEvaluationEnvironment</span><span class="o">(</span><span class="n">resolver</span><span class="o">,</span>
		<span class="n">resourceSetForModels</span><span class="o">,</span> <span class="n">templateURI</span><span class="o">,</span> <span class="n">outputURI</span><span class="o">);</span>

<span class="n">resolver</span><span class="o">.</span><span class="na">addLoader</span><span class="o">(</span><span class="k">new</span> <span class="nc">M2DocDocumentTemplateLoader</span><span class="o">(</span><span class="n">m2docEnv</span><span class="o">,</span> <span class="k">new</span> <span class="nc">BasicMonitor</span><span class="o">(),</span>
		<span class="nc">M2DocUtils</span><span class="o">.</span><span class="na">QUALIFIER_SEPARATOR</span><span class="o">));</span>
<span class="kd">final</span> <span class="nc">ILoader</span> <span class="n">javaLoader</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">JavaLoader</span><span class="o">(</span><span class="nc">M2DocUtils</span><span class="o">.</span><span class="na">QUALIFIER_SEPARATOR</span><span class="o">,</span> <span class="kc">false</span><span class="o">);</span>
<span class="n">resolver</span><span class="o">.</span><span class="na">addLoader</span><span class="o">(</span><span class="n">javaLoader</span><span class="o">);</span>

<span class="k">try</span> <span class="o">(</span><span class="nc">DocumentTemplate</span> <span class="n">documentTemplate</span> <span class="o">=</span> <span class="o">(</span><span class="nc">DocumentTemplate</span><span class="o">)</span><span class="n">resolver</span><span class="o">.</span><span class="na">resolve</span><span class="o">(</span><span class="n">qualifiedName</span><span class="o">))</span> <span class="o">{</span>
	<span class="nc">M2DocUtils</span><span class="o">.</span><span class="na">prepareEnvironment</span><span class="o">(</span><span class="n">queryEnvironment</span><span class="o">,</span> <span class="n">ePackageRegistry</span><span class="o">,</span> <span class="n">documentTemplate</span><span class="o">);</span>
	<span class="c1">// use the template here</span>
<span class="o">}</span> <span class="k">finally</span> <span class="o">{</span>
	<span class="nc">AQLUtils</span><span class="o">.</span><span class="na">cleanResourceSetForModels</span><span class="o">(</span><span class="k">this</span><span class="o">,</span> <span class="n">resourceSetForModels</span><span class="o">);</span>
	<span class="nc">AQLUtils</span><span class="o">.</span><span class="na">cleanServices</span><span class="o">(</span><span class="nc">M2DocUtils</span><span class="o">.</span><span class="na">M2DOC_LANGUAGE</span><span class="o">,</span> <span class="n">queryEnvironment</span><span class="o">,</span> <span class="n">resourceSetForModels</span><span class="o">);</span>
<span class="o">}</span></code></pre></figure>

<h3 id="validation">Validation</h3>

<p>The validation is optional:</p>

<h4 id="core-validation-api">Core validation API</h4>

<figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kd">final</span> <span class="nc">ValidationMessageLevel</span> <span class="n">validationLevel</span> <span class="o">=</span> <span class="nc">M2DocUtils</span><span class="o">.</span><span class="na">validate</span><span class="o">(</span><span class="n">documentTemplate</span><span class="o">,</span> <span class="n">queryEnvironment</span><span class="o">,</span> <span class="n">monitor</span><span class="o">);</span>
<span class="k">if</span> <span class="o">(</span><span class="n">validationLevel</span> <span class="o">!=</span> <span class="nc">ValidationMessageLevel</span><span class="o">.</span><span class="na">OK</span><span class="o">)</span> <span class="o">{</span>
    <span class="kd">final</span> <span class="no">URI</span> <span class="n">validationResulURI</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// some place to serialize the result of the validation</span>
    <span class="nc">M2DocUtils</span><span class="o">.</span><span class="na">serializeValidatedDocumentTemplate</span><span class="o">(</span><span class="n">resourceSetForModels</span><span class="o">.</span><span class="na">getURIConverter</span><span class="o">(),</span> <span class="n">documentTemplate</span><span class="o">,</span> <span class="n">validationResulURI</span><span class="o">);</span>
<span class="o">}</span></code></pre></figure>

<h4 id="generation-configuration-api">Generation configuration API</h4>

<figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kd">final</span> <span class="kt">boolean</span> <span class="n">hasErrors</span> <span class="o">=</span> <span class="nc">GenconfUtils</span><span class="o">.</span><span class="na">validate</span><span class="o">(</span><span class="n">generation</span><span class="o">,</span> <span class="n">m2docEnv</span><span class="o">,</span> <span class="n">options</span><span class="o">,</span> <span class="n">exceptions</span><span class="o">,</span> <span class="n">monitor</span><span class="o">);</span></code></pre></figure>

<h3 id="generation">Generation</h3>

<p>The generation will produce the final document where M2Doc template is evaluated against the given variables. There are two levels of API for the generation: directly from the DocumentTemplate or from the Generation.</p>

<h4 id="core-generation-api">Core generation API</h4>

<figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kd">final</span> <span class="nc">Map</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">,</span> <span class="nc">Object</span><span class="o">&gt;</span> <span class="n">variables</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// your variables and values</span>
<span class="kd">final</span> <span class="nc">GenerationResult</span> <span class="n">generationResult</span> <span class="o">=</span> <span class="nc">M2DocUtils</span><span class="o">.</span><span class="na">generate</span><span class="o">(</span><span class="n">m2docEnv</span><span class="o">,</span> <span class="n">documentTemplate</span><span class="o">,</span> <span class="n">variables</span><span class="o">,</span> <span class="kc">false</span><span class="o">,</span> <span class="n">monitor</span><span class="o">);</span></code></pre></figure>

<h4 id="generation-configuration-api-1">Generation configuration API</h4>

<figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kd">final</span> <span class="nc">Generation</span> <span class="n">generation</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// load from a serialized EMF model or create in memory</span>
<span class="kd">final</span> <span class="nc">List</span><span class="o">&lt;</span><span class="no">URI</span><span class="o">&gt;</span> <span class="n">generatedURIs</span> <span class="o">=</span> <span class="nc">GenconfUtils</span><span class="o">.</span><span class="na">generate</span><span class="o">(</span><span class="n">generation</span><span class="o">,</span> <span class="n">m2docEnv</span><span class="o">,</span> <span class="n">options</span><span class="o">,</span> <span class="n">monitor</span><span class="o">);</span></code></pre></figure>

<h2 id="maven">Maven</h2>

<p>You can use M2Doc in your maven project with the following repository and dependency:</p>

<figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;repositories&gt;</span>
  <span class="nt">&lt;repository&gt;</span>
    <span class="nt">&lt;id&gt;</span>Acceleo Repository<span class="nt">&lt;/id&gt;</span>
    <span class="nt">&lt;url&gt;</span>https://download.eclipse.org/acceleo/updates/releases/4.1/...<span class="nt">&lt;/url&gt;</span>
  <span class="nt">&lt;/repository&gt;</span>
  <span class="nt">&lt;repository&gt;</span>
    <span class="nt">&lt;id&gt;</span>M2Doc Repository<span class="nt">&lt;/id&gt;</span>
    <span class="nt">&lt;url&gt;</span>https://s3-eu-west-1.amazonaws.com/obeo-m2doc-releases/.../repository<span class="nt">&lt;/url&gt;</span>
  <span class="nt">&lt;/repository&gt;</span>
<span class="nt">&lt;/repositories&gt;</span>
<span class="nt">&lt;dependencies&gt;</span>
  <span class="nt">&lt;dependency&gt;</span>
    <span class="nt">&lt;groupId&gt;</span>org.obeonetwork.m2doc<span class="nt">&lt;/groupId&gt;</span>
    <span class="nt">&lt;artifactId&gt;</span>m2doc<span class="nt">&lt;/artifactId&gt;</span>
    <span class="nt">&lt;version&gt;</span>4.1.0<span class="nt">&lt;/version&gt;</span>
  <span class="nt">&lt;/dependency&gt;</span>
<span class="nt">&lt;/dependencies&gt;</span></code></pre></figure>

<p>If you use the source folder for your template make sure you include them as resources:</p>

<figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;build&gt;</span>
  <span class="nt">&lt;resources&gt;</span>
    <span class="nt">&lt;resource&gt;</span>
      <span class="nt">&lt;directory&gt;</span>${project.basedir}/src/main/java<span class="nt">&lt;/directory&gt;</span>
        <span class="nt">&lt;includes&gt;</span>
          <span class="nt">&lt;include&gt;</span>**/*.docx<span class="nt">&lt;/include&gt;</span>
        <span class="nt">&lt;/includes&gt;</span>
      <span class="nt">&lt;/resource&gt;</span>
    <span class="nt">&lt;/resources&gt;</span>
  <span class="nt">&lt;/build&gt;</span>
<span class="nt">&lt;/project&gt;</span></code></pre></figure>

<p>You can check the <a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/maven/org.obeonetwork.m2doc.maven.tests">test project</a> for more details. You can also check the <a href="https://github.com/eclipse-acceleo/acceleo/blob/master/query/plugins/org.eclipse.acceleo.query.doc/pages/index.adoc#maven">AQL Maven documentation</a> for more details on the AQL dependency.</p>

<p>You can optionally add other M2Doc dependencies:</p>

<ul>
  <li>m2doc-genconf: to use the *.genconf file API (see the <a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/maven/org.obeonetwork.m2doc.genconf.maven.tests">test project</a> for more details).</li>
  <li>m2doc-html: to use the <a href="../../ref-doc/nightly/m2doc_service_m2dochtmlservices.html">HTML services</a> (see the <a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/maven/org.obeonetwork.m2doc.html.maven.tests">test project</a> for more details).</li>
  <li>m2doc-wikitext: to use <a href="../../ref-doc/nightly/m2doc_service_m2docwikitextservices.html">Wikitext services</a> (see the <a href="https://github.com/ObeoNetwork/M2Doc/tree/master/tests/maven/org.obeonetwork.m2doc.wikitext.maven.tests">test project</a> for more details).</li>
</ul>

    </div>
  </div>
</div><!-- /.container -->

</div><!-- /#mainbody -->

  <footer class="bg_green3 center">
	<div class="container">
	    <div class="row">
	      <div class="col-lg-12">
	        <p>Made with &#10084; Copyright  &copy; <span id="year">YEAR</span> <a href="https://www.obeosoft.com">Obeo</a> - All Rights Reserved</p>
	      </div>
	    </div>
	</div>
</footer>
<!-- JavaScript -->
<script src="../../js/jquery-3.7.1.min.js"></script>
<script src="../../js/bootstrap.js"></script>
<script src="../../js/modern-business.js"></script>
<script src="../../js/main.js"></script>

   
  <!-- Cookies Consent/RGPD -->
  <script type="text/javascript" src="https://www.obeosoft.com/templates/purity_iii/js/ihavecookies.min.js"></script>
  <script>
    jQuery(document).ready(function () {
      jQuery('body').ihavecookies({
        title: 'Accept Cookies & Privacy Policy',
        message: 'This website uses cookies to ensure you get the best experience on our website. By clicking "Accept" or by closing this pop-up, you consent to our cookies in accordance with our Cookies and Privacy Polyicy.',
        delay: 1000,
        expires: 30,
        link: 'https://www.obeosoft.com/en/legal-information',
        onAccept: function () {
          location.reload();
        },
        uncheckBoxes: true
      });
    });
  </script>
  <script>
    if (document.cookie.indexOf('cookieControl') > -1) {
      var sc = document.createElement('script');

      sc.src = "https://www.obeosoft.com/templates/purity_iii/js/js.cookie.js";
      sc.type = 'application/javascript';

      document.getElementsByTagName('head')[0].appendChild(sc);
    }
  </script>

  <!-- JavaScript -->
<script>
if (document.cookie.indexOf('cookieControl') > -1) {
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
}
  ga('create', 'UA-108717312-1', 'auto');
  ga('send', 'pageview');

</script> 

</body>
</html>