Skip to content

Commit

Permalink
[Doc] fix the documentation.
Browse files Browse the repository at this point in the history 
- add the description of the 'create' option
- add the description of the descriptionId and object options for the
diagram tag.
  • Loading branch information
Romain Guider committed Dec 7, 2016
1 parent b310dd7 commit b815eae
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 30 deletions.
41 changes: 22 additions & 19 deletions plugins/org.obeonetwork.m2doc.doc/doc/user/M2Doc User Guide.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,57 +73,60 @@ <h3 id="M2Docstaticgenerationtags">M2Doc static generation tags</h3>
<h3 id="M2Docdynamicgenerationtags">M2Doc dynamic generation tags</h3>
<p>M2Doc provides a way to extend its information retrieval for a tag by registering a provider by an extension point. Each provider uses its own options in addition of the one generically provided par M2Doc core. Many providers can be associated to a same kind of tag and any one of those can be choose to retrieve information in a tag. </p>
<h4 id="Siriusdiagramprovider">Sirius diagram provider</h4>
<p>M2doc gives a way to insert Sirius diagrams: you have to install the Sirius provider feature coming with M2Doc installation.</p>
<p>The diagram tag has the following syntax:
<code>{m:diagram}</code>, with the following options:
<p>M2doc provides the
<code>m:diagram</code> tag to insert Sirius diagrams into documents. There are two ways to insert a diagram:
</p>
<ul>
<li>
<i>title</i> : AQL expression, mandatory if you want to get a diagram by its name. Be careful, as it is an AQL expression, if you just want to put a string, you have to add some'' around the string: title:&#171;'diagram name'&#187;,
<li>by the diagram title : the
<i>title</i> option can be used to specify the title of the representation that must be inserted.
</li>
<li>by the description Id and the representation&#8217;s semantic object : the
<i>descriptionId</i> option must be used to specify which representation must be inserted and the
<i>object</i> option must be used to provide the semantic object of the selected representation.
</li>
</ul>
<p>In the second case , the
<i>create</i> option can be used to specify whether the representation must be created if absent on the specified object. In case the create option is set to the &#171;true&#187; string and the representation is absent, it is created, inserted into the generated document and cleaned.
<br/>gives a way to insert Sirius diagrams: you have to install the Sirius provider feature coming with M2Doc installation.
</p>
<p>With both diagram providers, when several representations fit the selection criteria, all the fitting representations are inserted in the generated documentation.
<br/>The diagram tag admits the following complementary and non mandatory options:
</p>
<ul>
<li>
<i>width</i> : integer, optional, by default the diagram export real width,
</li>
</ul>
<ul>
<li>
<i>height</i> : integer, optional, by default the diagram export real height,
</li>
</ul>
<ul>
<li>
<i>layers</i> : string list, optional, to define the layers to display (the default layer is always displayed),
</li>
</ul>
<ul>
<li>
<i>provider</i> : Java class qualified name, optional. Use to define your own way to get a Sirius diagram.
</li>
</ul>
<p>The default way to get a diagram is by its name. If several diagrams have the same name, it will get the first.</p>
<p>However, if the behavior is not enough, you can define your own diagram provider and refers it in &#8249;provider&#8250; option tag. See the developer guide to add one.</p>
<p>In case these two diagrams providers (by title and by descriptionId and object) are not what you are looking for, you can contribute you&#8217;re own diagram provider. See the developer guide to learn how.</p>
<p>Some examples:</p>
<ul>
<li>
<code>m:diagram title:"'Diagram name'"</code>: get the first diagram named &#8249;Diagram name&#8250; in the modeling project. The diagram size is the export image size.
</li>
</ul>
<ul>
<li>
<code>m:diagram title:"self.name"</code>: if &#8249;self.name&#8250; is &#8249;My Diagram&#8250;, get the first diagram named &#8249;My Diagram&#8250; in the modeling project.
</li>
</ul>
<ul>
<li>
<code>m:diagram title:"'Diagram name'" width:"200" height:"200"</code>: get the first diagram named &#8249;Diagram name&#8250; in the modeling project. The diagram picture will be resize to 200x200.
</li>
</ul>
<ul>
<li>
<code>m:diagram title:"'Diagram name'" layers:"layer1, layer2"</code>: get the first diagram named &#8249;Diagram name&#8250; in the modeling project and apply the two layers layer1 and layer2. The current diagram is not modified.
</li>
<li>
<code>m:diagram descriptionId:"class diagram" object:"self" layers:"layer1, layer2"</code>: get the first diagram named &#8249;Diagram name&#8250; in the modeling project and apply the two layers layer1 and layer2. The current diagram is not modified.
</li>
<li>
<code>m:diagram descriptionId:"class diagram" object:"self" create:"true" layers:"layer1, layer2"</code>: get the first diagram named &#8249;Diagram name&#8250; in the modeling project and apply the two layers layer1 and layer2. The current diagram is not modified.
</li>
</ul>
<p>
<b>Warning</b>: do not forget the ' around the string in an AQL Expression:
Expand Down
21 changes: 10 additions & 11 deletions plugins/org.obeonetwork.m2doc.doc/doc/user/M2Doc User Guide.textile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,33 +57,32 @@ M2Doc provides a way to extend its information retrieval for a tag by registerin

h4. Sirius diagram provider

M2doc gives a way to insert Sirius diagrams: you have to install the Sirius provider feature coming with M2Doc installation.
M2doc provides the @m:diagram@ tag to insert Sirius diagrams into documents. There are two ways to insert a diagram:
* by the diagram title : the __title__ option can be used to specify the title of the representation that must be inserted.
* by the description Id and the representation's semantic object : the __descriptionId__ option must be used to specify which representation must be inserted and the __object__ option must be used to provide the semantic object of the selected representation.

The diagram tag has the following syntax: @{m:diagram}@, with the following options:
In the second case , the __create__ option can be used to specify whether the representation must be created if absent on the specified object. In case the create option is set to the "true" string and the representation is absent, it is created, inserted into the generated document and cleaned.
gives a way to insert Sirius diagrams: you have to install the Sirius provider feature coming with M2Doc installation.

* __title__ : AQL expression, mandatory if you want to get a diagram by its name. Be careful, as it is an AQL expression, if you just want to put a string, you have to add some'' around the string: title:"'diagram name'",
With both diagram providers, when several representations fit the selection criteria, all the fitting representations are inserted in the generated documentation.
The diagram tag admits the following complementary and non mandatory options:

* __width__ : integer, optional, by default the diagram export real width,

* __height__ : integer, optional, by default the diagram export real height,

* __layers__ : string list, optional, to define the layers to display (the default layer is always displayed),

* __provider__ : Java class qualified name, optional. Use to define your own way to get a Sirius diagram.

The default way to get a diagram is by its name. If several diagrams have the same name, it will get the first.

However, if the behavior is not enough, you can define your own diagram provider and refers it in 'provider' option tag. See the developer guide to add one.
In case these two diagrams providers (by title and by descriptionId and object) are not what you are looking for, you can contribute you're own diagram provider. See the developer guide to learn how.

Some examples:

* @m:diagram title:"'Diagram name'"@: get the first diagram named 'Diagram name' in the modeling project. The diagram size is the export image size.

* @m:diagram title:"self.name"@: if 'self.name' is 'My Diagram', get the first diagram named 'My Diagram' in the modeling project.

* @m:diagram title:"'Diagram name'" width:"200" height:"200"@: get the first diagram named 'Diagram name' in the modeling project. The diagram picture will be resize to 200x200.

* @m:diagram title:"'Diagram name'" layers:"layer1, layer2"@: get the first diagram named 'Diagram name' in the modeling project and apply the two layers layer1 and layer2. The current diagram is not modified.
* @m:diagram descriptionId:"class diagram" object:"self" layers:"layer1, layer2"@: get the first diagram named 'Diagram name' in the modeling project and apply the two layers layer1 and layer2. The current diagram is not modified.
* @m:diagram descriptionId:"class diagram" object:"self" create:"true" layers:"layer1, layer2"@: get the first diagram named 'Diagram name' in the modeling project and apply the two layers layer1 and layer2. The current diagram is not modified.

**Warning**: do not forget the ' around the string in an AQL Expression: @title:"'Diagram name'"@

Expand Down

0 comments on commit b815eae

Please sign in to comment.