[468465] Add minimal documentation on AQL

Bug: 468465
Change-Id: Ida5e670b36aca2b9859c8301da065c074943dc82
Signed-off-by: Pierre-Charles David <pierre-charles.david@obeo.fr>

4 files changed, 50 insertions, 2 deletions

diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
index edc75ad264..410e0c9205 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
@@ -77,7 +77,8 @@
 			<li><span class="label label-success">Added</span> <span class="label label-info">Experimental</span> Optional support for the experimental 
 				<em>Acceleo Query Language</em> (AQL) has been added to write interpreted expressions.  It is provided by the 
 				<code>org.eclipse.sirius.common.acceleo.aql</code> (required for evaluating the expressions) and 
-				<code>org.eclipse.sirius.common.acceleo.aql.ide</code>  (optional, only needed to provide specification-time features like expression completion). AQL is similar to Acceleo 3/MTL, but simpler and provides much better performance in the Sirius context.  If you make use of this feature, be aware that some details may still change in future releases, including 3.0.x maintenance releases.
+				<code>org.eclipse.sirius.common.acceleo.aql.ide</code>  (optional, only needed to provide specification-time features like expression completion) plug-ins. AQL is similar to Acceleo 3/MTL, but simpler and provides much better performance in the Sirius context. If you make use of this feature, be aware that some details may still change in future releases, including 3.0.x maintenance releases. See 
+				<a href="https://www.eclipse.org/acceleo/documentation/aql.html">the AQL documentation</a> for more details on the language itself.
 			</li>
 			<li><span class="label label-success">Added</span> <span class="label label-info">Experimental</span> New, experimental support for containers with vertical or horizontal 
 				<em>compartments</em> on diagrams: the 
diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
index 38239a4978..1bbe45fdc1 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
@@ -20,7 +20,7 @@ h3. User-Visible Changes
 
 h3. Specifier-Visible Changes
 
-* <span class="label label-success">Added</span> <span class="label label-info">Experimental</span> Optional support for the experimental _Acceleo Query Language_ (AQL) has been added to write interpreted expressions.  It is provided by the @org.eclipse.sirius.common.acceleo.aql@ (required for evaluating the expressions) and @org.eclipse.sirius.common.acceleo.aql.ide@  (optional, only needed to provide specification-time features like expression completion). AQL is similar to Acceleo 3/MTL, but simpler and provides much better performance in the Sirius context.  If you make use of this feature, be aware that some details may still change in future releases, including 3.0.x maintenance releases.
+* <span class="label label-success">Added</span> <span class="label label-info">Experimental</span> Optional support for the experimental _Acceleo Query Language_ (AQL) has been added to write interpreted expressions.  It is provided by the @org.eclipse.sirius.common.acceleo.aql@ (required for evaluating the expressions) and @org.eclipse.sirius.common.acceleo.aql.ide@  (optional, only needed to provide specification-time features like expression completion) plug-ins. AQL is similar to Acceleo 3/MTL, but simpler and provides much better performance in the Sirius context. If you make use of this feature, be aware that some details may still change in future releases, including 3.0.x maintenance releases. See "the AQL documentation":https://www.eclipse.org/acceleo/documentation/aql.html for more details on the language itself.
 * <span class="label label-success">Added</span> <span class="label label-info">Experimental</span> New, experimental support for containers with vertical or horizontal _compartments_ on diagrams: the _children presentation_ property of a _Container Mapping_ has two new values: _Vertical Stack_ and _Horizontal Stack_. They indicate that a container will present its children containers as a vertical/horizontal stack of compartments. While working reliably, this support is marked experimental in Sirius 3.0.0 as there are still some combinations of mappings, styles and behaviors which do not behave as expected. If you make use of this feature, be aware that some details may still change in future releases, including 3.0.x maintenance releases.
 * <span class="label label-success">Added</span> Everywhere an image path can be configured in the VSM, a new button is present on the right of the text field. It opens a dialog to select an image, either from the workspace or from an installed plug-in.
 * <span class="label label-success">Added</span> Everywhere an interpreted expression can be configured in the VSM, a new button is present on the right of the text field. It opens a multi-line dialog to edit long expression more easily. Auto-completion is supported inside the multi-line dialog.
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.html b/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.html
index 0531dd3899..8f31b5efb4 100644
--- a/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.html
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.html
@@ -28,6 +28,9 @@
 						<a href="#ocl">Using Raw OCL</a>
 					</li>
 					<li>
+						<a href="#aql">Using AQL</a>
+					</li>
+					<li>
 						<a href="#custom">Providing a Custom Language</a>
 					</li>
 					<li>
@@ -218,6 +221,38 @@
 			<code>org.eclipse.sirius.common.ocl</code> plug-in to ensure OCL support will be available wherever your modelers are used.
 		</p>
 		<p>It is highly recommended that you use Acceleo, which implemented the MTL standard and is a super-set of the OCL language, instead of raw OCL.</p>
+		<h2 id="aql">Using AQL</h2>
+		<p>Sirius 3.0 introduces experimental (and optional) support for 
+			<em>AQL</em> (Acceleo Query Language) to write queries/interpreted expressions. AQL is similar to Acceleo 3/MTL, but simpler and provides much better performance in the Sirius context. AQL expressions start with the 
+			<code>aql:</code> prefix and have a syntax similar to Acceleo (without the enclosing 
+			<code>[../]</code> brackets). The main differences between the two languages are:
+		</p>
+		<ul>
+			<li>Feature access must 
+				<strong>always</strong> explicitly specify the target object, even if the target is 
+				<code>self</code>. This means an Acceleo expression like <code>[name/]</code> which accesses the 
+				<code>name</code> attribute of the current element translates in AQL as 
+				<code>aql:self.name</code>. The expression 
+				<code>aql:name</code> with no explicit reciever will always be interpreted as an access to the 
+				<code>name</code> variable, and may result in an error if the variable in question is not defined. 
+			</li>
+			<li>&#171;Lamba&#187; expressions must always declare their parameters and use them explicitly. Again, there is no implicit 
+				<code>self</code> in such a context. For example: <code>[self.eContents()->select(name.startsWith('A'))/]</code> becomes <code>aql:self.eContents()->select(i | i.name.startsWith('A')]</code> with an explicit declaration and usage of 
+				<code>i</code> in AQL.
+			</li>
+			<li>AQL is more persmissive in terms of missing/empty intermediate results in complex expressions: 
+				<code>aql:self.anEmptyReference.somethingElse</code> will not result in an error as the equivalent Acceleo (or OCL) expression would, but simply return an empty result.
+			</li>
+			<li>AQL provides different services/methods by default compared to Acceleo. In general the set of default services in AQL is better suited to the typicaly use cases encountered in Sirius.</li>
+		</ul>
+		<p>See 
+			<a href="https://www.eclipse.org/acceleo/documentation/aql.html">the AQL documentation</a> for more details about the language itself.
+		</p>
+		<p>
+			<em>Note:</em> AQL support is provided by the 
+			<code>org.eclipse.sirius.common.acceleo.aql</code> (required for evaluating the expressions) and 
+			<code>org.eclipse.sirius.common.acceleo.aql.ide</code>  (optional, only needed to provide specification-time features like expression completion) plug-ins. In Sirius 3.0, AQL support is new and experimental and is thus optional. Depending on the context in which you are using Sirius, you may need to explicitly install some additional features to get these plug-ins.
+		</p>
 		<h2 id="custom">Providing a Custom Language</h2>
 		<p>Sirius allows you to provide your own language implementations, if you have very specific needs or want to reuse an existing custom language. Note that Sirius must be able to syntactically and unambiguously determine from an expression which language it is written in (to send it to the appropriate interpreter). The simplest way to achieve this is to define a prefix (like 
 			<code>ocl:</code> for OCL) so that expressions written in your language can be distinguished from expressions written in any of the others.
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.textile b/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.textile
index daf98ffc30..142349b786 100644
--- a/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.textile
@@ -82,6 +82,18 @@ Sirius also supports raw OCL expressions, but this support is deprecated and wil
 
 It is highly recommended that you use Acceleo, which implemented the MTL standard and is a super-set of the OCL language, instead of raw OCL.
 
+h2(#aql). Using AQL
+
+Sirius 3.0 introduces experimental (and optional) support for _AQL_ (Acceleo Query Language) to write queries/interpreted expressions. AQL is similar to Acceleo 3/MTL, but simpler and provides much better performance in the Sirius context. AQL expressions start with the @aql:@ prefix and have a syntax similar to Acceleo (without the enclosing @[../]@ brackets). The main differences between the two languages are:
+* Feature access must *always* explicitly specify the target object, even if the target is @self@. This means an Acceleo expression like <code>[name/]</code> which accesses the @name@ attribute of the current element translates in AQL as @aql:self.name@. The expression @aql:name@ with no explicit reciever will always be interpreted as an access to the @name@ variable, and may result in an error if the variable in question is not defined. 
+* "Lamba" expressions must always declare their parameters and use them explicitly. Again, there is no implicit @self@ in such a context. For example: ==<code>[self.eContents()->select(name.startsWith('A'))/]</code>== becomes ==<code>aql:self.eContents()->select(i | i.name.startsWith('A')]</code>== with an explicit declaration and usage of @i@ in AQL.
+* AQL is more persmissive in terms of missing/empty intermediate results in complex expressions: @aql:self.anEmptyReference.somethingElse@ will not result in an error as the equivalent Acceleo (or OCL) expression would, but simply return an empty result.
+* AQL provides different services/methods by default compared to Acceleo. In general the set of default services in AQL is better suited to the typicaly use cases encountered in Sirius.
+
+See "the AQL documentation":https://www.eclipse.org/acceleo/documentation/aql.html for more details about the language itself.
+
+_Note:_ AQL support is provided by the @org.eclipse.sirius.common.acceleo.aql@ (required for evaluating the expressions) and @org.eclipse.sirius.common.acceleo.aql.ide@  (optional, only needed to provide specification-time features like expression completion) plug-ins. In Sirius 3.0, AQL support is new and experimental and is thus optional. Depending on the context in which you are using Sirius, you may need to explicitly install some additional features to get these plug-ins.
+
 h2(#custom). Providing a Custom Language
 
 Sirius allows you to provide your own language implementations, if you have very specific needs or want to reuse an existing custom language. Note that Sirius must be able to syntactically and unambiguously determine from an expression which language it is written in (to send it to the appropriate interpreter). The simplest way to achieve this is to define a prefix (like @ocl:@ for OCL) so that expressions written in your language can be distinguished from expressions written in any of the others.