[doc] Provide documentation about the editor
Change-Id: Idcd4a286ed84933b2f07bd6d659778f7bc26396e
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/generate.adoc b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/generate.adoc
new file mode 100644
index 0000000..ccec73d
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/generate.adoc
@@ -0,0 +1,77 @@
+This section describe how to launch a generation from <<eclipse>> or <<_maventycho>>.
+Note that you can also use the <<_debugger>> to run a module or directly use Acceleo 4 programmatically, see <<_generation>>.
+
+=== Eclipse
+
+.Before you Start
+[IMPORTANT]
+====
+Use a *Java Project* and the classical *Java Perspective* for writing your Acceleo templates `.mtl` in the *src* folder.
+====
+
+In order to launch an Acceleo generator, you just have to right-click on your main module and use the *Run As* menu.
+
+image::images/RunAs.png[Run As]
+
+From there the *Launch Configuration* menu will open.
+If you already have created a launch configuration you can access the launch configuration menu from the *Run > Run Configurations...* menu.
+In this menu, you will have access to the Acceleo Launch configuration.
+You just have to select:
+
+* your main *module file*,
+* your input *model file*,
+* the *destination folder* of the generation.
+
+image::images/LaunchConfig.png[Launch Configuration]
+
+INFO: Check that your generation is finished by opening the *Console* view.
+You should see a message like this `<terminated> generate.mtl[Acceleo4]`.
+
+=== Maven/Tycho
+
+Acceleo provides a specific eclipse application that can be used from command line or tycho in order to start a generation.
+In order to use the launcher, you will need to first package all of your generator projects into an update site, then use this update site as input of the application.
+
+An example is available in the Acceleo repository and can be checked out at: https://git.eclipse.org/c/acceleo/org.eclipse.acceleo.git/tree/examples/MavenLauncher
+
+This example includes:
+
+* A generator project `org.eclipse.acceleo.aql.launcher.sample`,
+* A feature including this project `org.eclipse.acceleo.aql.launcher.sample-feature`,
+* An update site including this feature `org.eclipse.acceleo.aql.launcher.sample-site`,
+* A `pom.xml` file that can be used to both package the generator and start the generation.
+
+The packaging can be started through the command line `mvn clean verify`.
+Once packaged, generation can be started through the command line `mvn clean verify -Pgenerate`.
+
+The application takes a number of arguments that will have to be customized through the pom.xml file:
+
+----
+<applicationsArgs>
+ <args>-application</args>
+ <args>org.eclipse.acceleo.aql.launcher.AcceleoLauncher</args>
+ <args>-data</args>
+ <args>${project.build.directory}/wks</args>
+ <args>-bundle</args>
+ <args>org.eclipse.acceleo.aql.launcher.sample</args>
+ <args>-module</args>
+ <args>org::eclipse::acceleo::aql::launcher::sample::main</args>
+ <args>-models</args>
+ <args>platform:/plugin/org.eclipse.acceleo.aql.launcher.sample/model/sample.xmi</args>
+ <args>-target</args>
+ <args>file:/${project.build.directory}/generated/</args>
+</applicationsArgs>
+----
+
+application::
+Standard Eclipse argument, this tells Eclipse which application it needs to run. The specific launcher for Acceleo generations is `org.eclipse.acceleo.aql.launcher.AcceleoLauncher`.
+data::
+Standard Eclipse argument, this can be used to modify the workspace path.
+bundle::
+This needs to be the identifier of the bundle containing the main module for this generation.
+module::
+The starting point of the generation that is to be started. This needs to the qualified name of the module containing an "@main"-annotated template.
+models::
+The URI of the models that will be fed to the main module of the generation. This cannot be empty and needs to be an URI that eclipse is capable of resolving. In this example we're using a `platform:/plugin/...` URI since we've bundled the input model into our generator project.
+target::
+The destination URI for this generation. Generated files will use this folder as their root to resolve against. *Note* that this needs to end in a trailing `/`.
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/Breakpoint.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/Breakpoint.png
new file mode 100644
index 0000000..fee815b
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/Breakpoint.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ContentAssistMetamodel.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ContentAssistMetamodel.png
new file mode 100644
index 0000000..64153fd
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ContentAssistMetamodel.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/DebugAs.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/DebugAs.png
new file mode 100644
index 0000000..ae92adf
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/DebugAs.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/DebugSession.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/DebugSession.png
new file mode 100644
index 0000000..f4ddfec
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/DebugSession.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ErrorFile.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ErrorFile.png
new file mode 100644
index 0000000..013dabc
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ErrorFile.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ErrorInProblemsView.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ErrorInProblemsView.png
new file mode 100644
index 0000000..c9b10a6
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ErrorInProblemsView.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ErrorMarker.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ErrorMarker.png
new file mode 100644
index 0000000..c9b10a6
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ErrorMarker.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ErrorTooltip.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ErrorTooltip.png
new file mode 100644
index 0000000..d585d9e
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/ErrorTooltip.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/IndentationIssue.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/IndentationIssue.png
new file mode 100644
index 0000000..e60b23e
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/IndentationIssue.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/InstallDependencies.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/InstallDependencies.png
new file mode 100644
index 0000000..48ddc56
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/InstallDependencies.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/LaunchConfig.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/LaunchConfig.png
new file mode 100644
index 0000000..e5222ca
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/LaunchConfig.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/NewFile.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/NewFile.png
new file mode 100644
index 0000000..5ae2220
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/NewFile.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/NewProject.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/NewProject.png
new file mode 100644
index 0000000..fe8f0e0
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/NewProject.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/NewProjectWizard.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/NewProjectWizard.png
new file mode 100644
index 0000000..021be86
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/NewProjectWizard.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/NewTemplate.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/NewTemplate.png
new file mode 100644
index 0000000..c041b58
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/NewTemplate.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/OpenDeclaration.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/OpenDeclaration.png
new file mode 100644
index 0000000..6563240
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/OpenDeclaration.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/Outline.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/Outline.png
new file mode 100644
index 0000000..61410f2
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/Outline.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/QuickOutline.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/QuickOutline.png
new file mode 100644
index 0000000..f29aafb
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/QuickOutline.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/RunAs.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/RunAs.png
new file mode 100644
index 0000000..90af5fb
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/RunAs.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/SyntaxHighlighting.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/SyntaxHighlighting.png
new file mode 100644
index 0000000..1571522
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/SyntaxHighlighting.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/UnactivBreakpoint.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/UnactivBreakpoint.png
new file mode 100644
index 0000000..90ca1e7
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/UnactivBreakpoint.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/VariablesView.png b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/VariablesView.png
new file mode 100644
index 0000000..c5df91b
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/images/VariablesView.png
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/index.adoc b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/index.adoc
new file mode 100644
index 0000000..55d162b
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/index.adoc
@@ -0,0 +1,50 @@
+= Acceleo
+Acceleo 4 User Guide
+:toc:
+:toclevels: 3
+:toc-title: Table of Content
+:sectnums:
+:icons: font
+:source-highlighter: highlightjs
+:listing-caption: Listing
+
+<<<
+
+== Introduction
+
+Acceleo 4 is a a text generator based on templates.
+It can be used to generate any kind of text file: code, configuration, documentation,...
+
+The template consists of imperative statements like conditionals, loops, and navigation expression used to retrieve data from models.
+
+When generating, the engine use templates statements and also replace navigation expressions by their values in order to produce the output text.
+
+== Installation
+
+include::install.adoc[]
+
+== Getting Started
+
+include::start.adoc[]
+
+== The Acceleo Tooling
+
+include::tool.adoc[]
+
+== The Acceleo Language
+You can read to the link:language.html[language documentation] to understand Acceleo 4 language specificity. If you are looking for the syntax quick reference you can check the link:syntax.html[syntax page].
+
+include::language.adoc[]
+include::syntax.adoc[]
+
+== Launching an Acceleo generation
+
+include::generate.adoc[]
+
+== Using Acceleo 4 programmatically
+
+include::use.adoc[]
+
+== Migrate Acceleo 3 templates to Acceleo 4
+
+include::migration.adoc[]
\ No newline at end of file
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/index.asciidoc b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/index.asciidoc
deleted file mode 100644
index a6f78a4..0000000
--- a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/index.asciidoc
+++ /dev/null
@@ -1,138 +0,0 @@
-= Acceleo
-Acceleo 4 User Guide
-
-:source-highlighter: highlightjs
-:listing-caption: Listing
-:toc:
-:toclevels: 3
-:sectnums:
-:icons: image
-
-== Introduction
-
-Acceleo 4 is a a text generator based on templates. It can be used to generate any kind of text file: code, configuration, documentation, ... The template consists of imperative statements like conditionals, loops, and navigation expression used to retrieve data from models. When generating the engine use templates statements and also replace navigation expressions by their values in order to produce the output text.
-
-== Generating
-
-This section describe how to launch a generation from <<eclipse>> or <<_maventycho>>. Note that you can also use the <<_debugger>> to run a module or directly use Acceleo 4 programmatically, see <<_generation>>.
-
-=== Eclipse
-
-TODO
-
-=== Maven/Tycho
-
-Acceleo provides a specific eclipse application that can be used from command line or tycho in order to start a generation.
-In order to use the launcher, you will need to first package all of your generator projects into an update site, then use this update site as input of the application.
-
-An example is available in the Acceleo repository and can be checked out at https://git.eclipse.org/c/acceleo/org.eclipse.acceleo.git/tree/examples/MavenLauncher .
-
-This example includes:
-
-* A generator project `org.eclipse.acceleo.aql.launcher.sample`
-* A feature including this project `org.eclipse.acceleo.aql.launcher.sample-feature`
-* An update site including this feature `org.eclipse.acceleo.aql.launcher.sample-site`
-* A pom.xml file that can be used to both package the generator and start the generation
-
-The packaging can be started through the command line `mvn clean verify`.
-Once packaged, generation can be started through the command line `mvn clean verify -Pgenerate`.
-
-The application takes a number of arguments that will have to be customized through the pom.xml file:
-
-----
-<applicationsArgs>
- <args>-application</args>
- <args>org.eclipse.acceleo.aql.launcher.AcceleoLauncher</args>
- <args>-data</args>
- <args>${project.build.directory}/wks</args>
- <args>-bundle</args>
- <args>org.eclipse.acceleo.aql.launcher.sample</args>
- <args>-module</args>
- <args>org::eclipse::acceleo::aql::launcher::sample::main</args>
- <args>-models</args>
- <args>platform:/plugin/org.eclipse.acceleo.aql.launcher.sample/model/sample.xmi</args>
- <args>-target</args>
- <args>file:/${project.build.directory}/generated/</args>
-</applicationsArgs>
-----
-
-application::
-Standard Eclipse argument, this tells Eclipse which application it needs to run. The specific launcher for Acceleo generations is `org.eclipse.acceleo.aql.launcher.AcceleoLauncher`.
-data::
-Standard Eclipse argument, this can be used to modify the workspace path.
-bundle::
-This needs to be the identifier of the bundle containing the main module for this generation.
-module::
-The starting point of the generation that is to be started. This needs to the qualified name of the module containing an "@main"-annotated template.
-models::
-The URI of the models that will be fed to the main module of the generation. This cannot be empty and needs to be an URI that eclipse is capable of resolving. In this example we're using a `platform:/plugin/...` URI since we've bundled the input model into our generator project.
-target::
-The destination URI for this generation. Generated files will use this folder as their root to resolve against. *Note* that this needs to end in a trailing `/`.
-
-== Module authoring
-
-This section cover tools for template writing, debugging and testing. You can read to the link:language.html[language documentation] to understand Acceleo 4 language specificity. If you are looking for the syntax quick reference you can check the link:syntax.html[syntax page].
-
-=== White spaces
-
-When generating text, and especially code, white spaces and indentation is an important point. In order to keep template code indentation from interfering with the generated output, a few rules applies:
-
-- each block has a mandatory indentation of two characters than will not be generated in the output (in yellow below)
-- when generating a block if the last generated line is not empty, it is repeated at the beginning of each line generated by the block (in red below)
-
-image::images/Indentation.png[Indentation]
-
-=== Editor
-
-TODO
-
-=== Debugger
-
-TODO
-
-=== Unit test module
-
-You can unit test your modules using the same JUnit test suite we are using for the development of Acceleo 4. You will simply need to create a class extending the class org.eclipse.acceleo.tests.utils.AbstractEvaluationTestSuite and create a folder with you test folders. Those folders need to respect a naming convention. You can find a working example with the class https://git.eclipse.org/c/acceleo/org.eclipse.acceleo.git/tree/acceleo-aql/org.eclipse.acceleo.aql.tests/src/org/eclipse/acceleo/tests/evaluation/FileStatementTests.java?h=acceleo-aql[FileStatementTests] and the corresponding https://git.eclipse.org/c/acceleo/org.eclipse.acceleo.git/tree/acceleo-aql/org.eclipse.acceleo.aql.tests/resources/evaluation/fileStatement?h=acceleo-aql[folder].
-
-== Using Acceleo 4 programmatically
-
-Acceleo 4 can be used programmatically and for instance integrated in other products.
-
-=== Parsing
-
-[source,java]
----------
-URI destination = URI.createURI(...);
-environment = new AcceleoEnvironment(new DefaultGenerationStrategy(), destination);
-IQualifiedNameResolver moduleResolver = new ClassLoaderQualifiedNameResolver(getClass().getClassLoader(), environment.getQueryEnvironment());
-environment.setModuleResolver(moduleResolver);
-Module module = environment.getModule(qualifiedName);
----------
-
-
-=== Validation
-
-[source,java]
-----
-AcceleoValidator validator = new AcceleoValidator(environment);
-List<IValidationMessage> messages = validator.validate(astResult, qualifiedName).getValidationMessages();
-----
-
-=== Completion
-
-[source,java]
-----
-AcceleoCompletor completor = new AcceleoCompletor();
-String source = ...;
-List<ICompletionProposal> proposals = completor.getProposals(environment, source, position);
-----
-
-=== Generation
-
-[source,java]
-----
-AcceleoEvaluator evaluator = new AcceleoEvaluator(environment);
-ResourceSetImpl rs = new ResourceSetImpl();
-Resource model = rs.getResource(..., true);
-AcceleoUtil.generate(evaluator, environment, module, model);
-----
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/index.pdf b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/index.pdf
new file mode 100644
index 0000000..b40fd34
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/index.pdf
Binary files differ
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/install.adoc b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/install.adoc
new file mode 100644
index 0000000..db3c109
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/install.adoc
@@ -0,0 +1,7 @@
+If you have an existing Eclipse installation and simply wish to install Acceleo in it, you can install it from the *Update Site*, available here https://download.eclipse.org/acceleo/updates/nightly/.
+
+When installing the update site you must ensure that *"Contact all update sites during install to find required software"* is checked and that in the *"Manage..."* dialog, the *"Latest Eclipse Release"* update site is checked.
+
+image:images/InstallDependencies.png[Install Acceleo]
+
+For those of you who need to retrieve the source code of Acceleo, it is available on Git: https://git.eclipse.org/c/acceleo/org.eclipse.acceleo.git/.
\ No newline at end of file
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/language.adoc b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/language.adoc
index 551bfa1..9d23597 100644
--- a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/language.adoc
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/language.adoc
@@ -1,20 +1,8 @@
-= Acceleo
-Acceleo 4 Language
-
-:source-highlighter: highlightjs
-:listing-caption: Listing
-:toc:
-:toclevels: 3
-:sectnums:
-:icons: image
-
-== Preface
-
=== Intended Audience
This guide was written to describe the elements composing the Acceleo 4 templating language. This will not delve into the Acceleo Query Language (AQL) description.
-== Module
+=== Module
An Acceleo module is defined in its own file and is the main container for generation <<Template,templates>> (that will generate text) and <<Query,queries>> (which purpose is to extract information from the input models).
@@ -44,7 +32,7 @@
See also the <<syntax#_module,Module syntax documentation>>.
-=== Imports
+==== Imports
An Acceleo module can import any number of other modules or Java service class. All _public_ visibility templates and queries from the imported module(s) can be called by the importer, for Java class all public methods can be used a service.
@@ -58,11 +46,11 @@
See also the <<syntax#_import,Import>> as well as the <<syntax#_module_reference,Module Reference>> syntax documentation.
-=== Module Elements
+==== Module Elements
Following the imports declaration, any number of module element can now be written as the body of our Module. Please refer to <<Template>> and <<Query>> sections below for more information.
-== Template
+=== Template
A Template is a set of Acceleo statements used to generate text. It is delimited by `[template ...][/template]` tags.
@@ -94,7 +82,7 @@
See also the <<syntax#_template,Template syntax documentation>>.
-=== Main template
+==== Main template
Acceleo defines a special metadata tag on templates to specify the main entry point(s) of a generation, the template(s) that will be called first during the workflow. This metadata tag, `@main`, needs to be in the comments preceding the template, or within the template documentation
@@ -118,7 +106,142 @@
[/template]
----
-== Query
+==== File Block
+
+File blocks are used to tell the Acceleo engine it must generate the body of the `[file ...]` block in an actual file.
+
+----
+[file (<uri>, <open mode>, <charset>)][/file]
+----
+
+uri::
+An AQL expression denoting the output file name. Must evaluate to a String.
+open mode::
+The open mode for the file. This can be one of:
++
+* *(Not Supported Yet)* append : Append to the end of the file if it already exists, create it otherwise.
+* overwrite : Overwrite the whole file if it already exists, create it otherwise.
+* create : Do not change the file if it already exists, create it otherwise.
+charset::
+This can be used to tell Acceleo which charset to use for the generated file. This is optional and will default to UTF-8
+
+Example:
+
+----
+[template public generate(class : ecore::EClass)]
+[file (class.name + '.java', append, 'UTF-8')]
+[/file]
+[/template]
+----
+
+*Note* that the file will only be generated if the engine actually evaluates the file block. For example, if the template containing that block is never called, or if the file block is included in an `If` block which condition evalutes to `false`, then no file will be created.
+
+See also the <<syntax#_file_statement,File Statement syntax documentation>>.
+
+==== For loops
+
+For loops in Acceleo need to be expressed using the following syntax:
+
+----
+[for (<variable> | <iteration expression>) separator(<separator expression>)]...[/for]
+----
+
+variable::
+The variable follows the <<_variable,format for variables>>. The variable type must match the result of the iteration expression. If the expression returns a collection of Strings, then the variable will be of type String. Because of this, typing the variable is optional.
+iteration expression::
+An AQL expression returning a collection of elements on which to iterate. If the expression doesn't return a collection but a single element, it will be used to iterate only once.
+separator::
+The separator expression will be evaluated to insert content in-between the content generated for each iteration of the for body. It will not be generated if the for loop doesn't generate text or only generates one iteration worth of content.
+
+Example:
+
+----
+[template public generate(class : ecore::EClass)]
+[for (feature | class.eStructuralFeatures)]
+[/for]
+[/template]
+----
+
+See also the <<syntax#_for_statement,For Statement syntax documentation>>.
+
+==== If conditions
+
+The `If` statement in Acceleo uses the following syntax:
+
+----
+[if (condition)]
+[elseif (condition)]
+[else]
+[/if]
+----
+
+`elseif` and `else` are both optional. If one of the `condition` expressions does not evaluate to a boolean an error will be logged and nothing will be generated for that `if` block.
+
+See also the <<syntax#_if_statement,If Statement syntax documentation>>.
+
+==== Let block
+
+Acceleo `Let` blocks use the following syntax:
+
+----
+[let <variable1> = <init expression>, <variable2> = <init expression>]
+[/let]
+----
+
+`Let` blocks allow template writers to define temporary variables that will be visible within the scope of the block.
+
+The variables follow the <<_variable,format for variables>>. All of their typing is optional since they must match the return type of their initialization expression.
+
+*Note* that all variables are immutable. Nested `Let` blocks can override the value of a variable within their own scope, but the variable will go back to its former value once outside of the nested `Let`. This will produce a warning during validation.
+
+See also the <<syntax#_let_statemnet,Let Statement syntax documentation>>.
+
+==== Protected Area
+
+A protected area defines a set of statements that should only be generated if the file doesn't exist on disk or it does not contain an area with the specified protected area's identifier.
+
+Protected areas allow module writers to create a "safe" part of the generated file that can be modified directly in the generated file, without fear of these manual modifications to be lost during subsequent generations.
+
+----
+[comment @main/]
+[template public generate(class : ecore::EClass)]
+[file (class.name + '.java', overwrite, 'UTF-8')/]
+// [protected (class.name + ' imports')]
+imports java.util.List;
+// [/protected]
+
+public class [class.name.toUpperFirst()/] {
+
+}
+[/file]
+[/template]
+----
+
+The expression within the protected block's signature serves as the protected area's identifier and *must be unique* in the generated file's scope.
+
+*There must be nothing present on the line after the protected area's signature.* Otherwise, everything following said signature will be considered to be part of the area's identifier by the engine and the code will not be properly protected.
+
+Please also note that the protected area's first and last line are marked as comments in the generated code (by generating `//` at the start of their respective line, since this is Java code). This is to avoid generating invalid Java code as the markers will be present in the generated file's contents.
+
+==== Variable
+
+Acceleo 4 variables use the AQL syntax and inference logic for their typing.
+
+----
+<name> : <type>
+----
+
+name::
+Name of the variable. Only alphanumeric (and underscore`_`) characters are allowed, and the name cannot start with a number.
+type::
+Type of the variable. Four different kind of types are accepted
++
+* primitive : Integer, Double, String, Boolean
+* collection : Sequence, OrderedSet. Collection types have to be further specified with their content types, such as Sequence(String) for a list of String elements.
+* eclassifier : in the form <epackage_name>::<classifier_name> such as ecore::EClass.
+* union type : in the form {<epackage_name>::<classifier_name> | <epackage_name>::<classifier_name> | ...}. This kind of typing describes a variable that can be either one of the _n_ specified classifiers. e.g. {ecore::EAttribute | ecore::EReference }.
+
+=== Query
A query is a re-useable AQL expression that can return any type of Object. They are commonly used to extract information from the input models. A query is enclosed in a `[query ...]` tag.
@@ -147,139 +270,4 @@
return type::
The return type describes the kind of object this query is expected to return. If the expression does not return an object of the accurate type, the evaluation will fail at runtime.
-See also the <<syntax#_query,Query syntax documentation>>.
-
-== File Block
-
-File blocks are used to tell the Acceleo engine it must generate the body of the `[file ...]` block in an actual file.
-
-----
-[file (<uri>, <open mode>, <charset>)][/file]
-----
-
-uri::
-An AQL expression denoting the output file name. Must evaluate to a String.
-open mode::
-The open mode for the file. This can be one of:
-+
-* append : Append to the end of the file if it already exists, create it otherwise.
-* overwrite : Overwrite the whole file if it already exists, create it otherwise.
-* create : Do not change the file if it already exists, create it otherwise.
-charset::
-This can be used to tell Acceleo which charset to use for the generated file. This is optional and will default to UTF-8
-
-Example:
-
-----
-[template public generate(class : ecore::EClass)]
-[file (class.name + '.java', append, 'UTF-8')]
-[/file]
-[/template]
-----
-
-*Note* that the file will only be generated if the engine actually evaluates the file block. For example, if the template containing that block is never called, or if the file block is included in an `If` block which condition evalutes to `false`, then no file will be created.
-
-See also the <<syntax#_file_statement,File Statement syntax documentation>>.
-
-== For loops
-
-For loops in Acceleo need to be expressed using the following syntax:
-
-----
-[for (<variable> | <iteration expression>) separator(<separator expression>)]...[/for]
-----
-
-variable::
-The variable follows the <<_variable,format for variables>>. The variable type must match the result of the iteration expression. If the expression returns a collection of Strings, then the variable will be of type String. Because of this, typing the variable is optional.
-iteration expression::
-An AQL expression returning a collection of elements on which to iterate. If the expression doesn't return a collection but a single element, it will be used to iterate only once.
-separator::
-The separator expression will be evaluated to insert content in-between the content generated for each iteration of the for body. It will not be generated if the for loop doesn't generate text or only generates one iteration worth of content.
-
-Example:
-
-----
-[template public generate(class : ecore::EClass)]
-[for (feature | class.eStructuralFeatures)]
-[/for]
-[/template]
-----
-
-See also the <<syntax#_for_statement,For Statement syntax documentation>>.
-
-== If conditions
-
-The `If` statement in Acceleo uses the following syntax:
-
-----
-[if (condition)]
-[elseif (condition)]
-[else]
-[/if]
-----
-
-`elseif` and `else` are both optional. If one of the `condition` expressions does not evaluate to a boolean an error will be logged and nothing will be generated for that `if` block.
-
-See also the <<syntax#_if_statement,If Statement syntax documentation>>.
-
-== Let block
-
-Acceleo `Let` blocks use the following syntax:
-
-----
-[let <variable1> = <init expression>, <variable2> = <init expression>]
-[/let]
-----
-
-`Let` blocks allow template writers to define temporary variables that will be visible within the scope of the block.
-
-The variables follow the <<_variable,format for variables>>. All of their typing is optional since they must match the return type of their initialization expression.
-
-*Note* that all variables are immutable. Nested `Let` blocks can override the value of a variable within their own scope, but the variable will go back to its former value once outside of the nested `Let`. This will produce a warning during validation.
-
-See also the <<syntax#_let_statemnet,Let Statement syntax documentation>>.
-
-== Protected Area
-
-A protected area defines a set of statements that should only be generated if the file doesn't exist on disk or it does not contain an area with the specified protected area's identifier.
-
-Protected areas allow module writers to create a "safe" part of the generated file that can be modified directly in the generated file, without fear of these manual modifications to be lost during subsequent generations.
-
-----
-[comment @main/]
-[template public generate(class : ecore::EClass)]
-[file (class.name + '.java', overwrite, 'UTF-8')/]
-// [protected (class.name + ' imports')]
-imports java.util.List;
-// [/protected]
-
-public class [class.name.toUpperFirst()/] {
-
-}
-[/file]
-[/template]
-----
-
-The expression within the protected block's signature serves as the protected area's identifier and *must be unique* in the generated file's scope.
-
-*There must be nothing present on the line after the protected area's signature.* Otherwise, everything following said signature will be considered to be part of the area's identifier by the engine and the code will not be properly protected.
-
-Please also note that the protected area's first and last line are marked as comments in the generated code (by generating `//` at the start of their respective line, since this is Java code). This is to avoid generating invalid Java code as the markers will be present in the generated file's contents.
-
-== Variable
-
-Acceleo 4 variables use the AQL syntax and inference logic for their typing.
-
-----
-<name> : <type>
-----
-
-name::
-Name of the variable. Only alphanumeric (and underscore`_`) characters are allowed, and the name cannot start with a number.
-type::
-Type of the variable. Four different kind of types are accepted
-+
-* primitive : Integer, Double, String, Boolean
-* collection : Sequence, OrderedSet. Collection types have to be further specified with their content types, such as Sequence(String) for a list of String elements.
-* eclassifier : in the form <epackage_name>::<classifier_name> such as ecore::EClass.
-* union type : in the form {<epackage_name>::<classifier_name> | <epackage_name>::<classifier_name> | ...}. This kind of typing describes a variable that can be either one of the _n_ specified classifiers. e.g. {ecore::EAttribute | ecore::EReference }.
\ No newline at end of file
+See also the <<syntax#_query,Query syntax documentation>>.
\ No newline at end of file
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/migration.adoc b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/migration.adoc
index eab5346..68ed300 100644
--- a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/migration.adoc
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/migration.adoc
@@ -1,25 +1,31 @@
-= Acceleo
-Acceleo 3 to Acceleo 4 migration guide
+This section was written to describe the behavior changes between the two versions of Acceleo, for the purpose of migrating from one to the next.
-:doctype: book
-:source-highlighter: rouge
-:listing-caption: Listing
-:toc:
-:toclevels: 3
-:sectnums:
-:icons: image
+=== How to migrate Acceleo 3 templates to Acceleo 4
-== Preface
+==== The migration tool
-=== Intended Audience
+The migration tool consists on a java standalone utility deployed as a jar file, "migrator.jar". There is a library folder aside containing all of the required jars (Acceleo 3, Acceleo 4) required to perform a migration.
-This guide was written to describe the behavior changes between the two versions of Acceleo, for the purpose of migrating from one to the next.
+==== Launching a migration
-== Language Changes
+The migration tool requires a fully built Acceleo 3 project as input: the project folder must contain a bin/ folder with all of the compiled (.emtl) versions of the .mtl source files.
-=== Modules
+The migration jar can be run in command line with the following arguments. We assume we are in the folder containing the migration jar, and that the Acceleo project is at the same level. There is also an empty "output" folder to receive the result of the migration:
+----
+java -jar migrator.jar <myproject>/<sourcefolder> <output_folder>
+----
+For instance, for an Acceleo 3 project in which the source templates are in the src/ folder (anywhere in the sub-folders of src/):
+----
+java -jar migrator.jar myProject/src output
+----
+The converted .mtl files will be created in the output folder, accordingly to the folder structure in the source project.
-==== module name
+
+=== Language Changes
+
+==== Modules
+
+===== module name
Acceleo 3 allowed users to set the fully qualified name of the module in its declaration, such as
@@ -27,7 +33,7 @@
[module qualified::module::name(...)]
----
-Acceleo 4 forbids anything other than the actual module name and this should thus become.
+Acceleo 4 forbids anything other than the actual module name and this will thus become.
----
[module name(...)]
@@ -35,9 +41,9 @@
Both versions require the module name to be equal to the name of the containing file minus the extension.
-==== multiple inheritance
+===== multiple inheritance
-The acceleo 3 module declaration allowed users to declare multiple "extends" modules:
+The Acceleo 3 module declaration allowed users to declare multiple "extends" modules:
----
[module qualified::module::name(...) extends another::module, and::a:second::module]
@@ -45,22 +51,22 @@
Acceleo 4 modules can only define a single extended module.
-*Only the first extended module was taken into account* in Acceleo 3 so the migration can just strip all but the first extended modules' name.
+*Only the first extended module was taken into account* in Acceleo 3 so the migration just strips all but the first extended modules' name.
-==== module imports
+===== module imports
Acceleo 3 allowed imports of modules through unqualified names. This is forbidden in Acceleo 4 and the fully qualified names of the imports are required.
-=== Templates
+==== Templates
-*Important notes:* The Migration tool needs to somehow mark every template which had duplicated signatures (same name, same argument list, different pre-condition) to be manually checked after migration.
+*Important notes:* Every template which had duplicated signatures (same name, same argument list, different pre-condition) needs to be manually checked after migration.
* Acceleo 4 does not allow duplicated signatures and has no pre-condition, so duplicated templates might have to be combined into a single one with their pre-condition as an `If-Else` block inside.
* Initialization blocks could be different on duplicated templates, depending on the pre-condition. The migrated `Let` block thus needs to be different per branch of the above `If-Else`.
-Acceleo 4 templates will automatically override their super-module templates if the signature matches. This was not the case in Acceleo 3 and matching templates thus need to be marked for manual verification.
+Acceleo 4 templates will automatically override their super-module templates if the signature matches. This was not the case in Acceleo 3 and matching templates thus need verified manually.
-==== Overriding
+===== Overriding
Acceleo 3 templates allowed users to override an arbitrary template through the "overrides" keyword:
@@ -72,11 +78,11 @@
Furthermore, Acceleo 4 templates will automatically override their super-module's public or protected templates if they have the same signature.
-==== Pre-conditions
+===== Pre-conditions
Acceleo 4 does not allow pre-conditions on templates.
-==== Post-treatment
+===== Post-treatment
Acceleo 3 used an implicit String-typed variable so the post expression could be a simple call without a variable:
@@ -84,13 +90,13 @@
[template public aTemplateName(...) post (trim())]
----
-Acceleo 4 doesn't allow implicit variables. The result of the template call will be stored in the `self` variable and the migration must thus transform this expression into:
+Acceleo 4 doesn't allow implicit variables. The result of the template call will be stored in the `self` variable and the migration will thus transform this expression into:
----
[template public aTemplateName(...) post (self.trim())]
----
-==== Init block
+===== Init block
Acceleo 3 allowed variable initialization blocks on the template:
@@ -98,19 +104,17 @@
[template public aTemplateName(...) {var1 = 'string'; var2 = param1.feature;}]
----
-Acceleo 4 removes the initialization blocks altogether, so the variable declarations must be transformed into a `let` block at the start of the template.
+Acceleo 4 removes the initialization blocks altogether, so the variable declarations must be manually transformed into a `let` block at the start of the template (this is not supported by the migration tool).
-==== Namesakes
+===== Namesakes
Acceleo 3 allowed multiple templates with the same name and same argument list to co-exist within the same module, as long as their pre-condition differed.
-PENDING choice, remove one of the two:
Though Acceleo 4 will allow multiple templates with the same signature to exist in a module, only the last one will ever be resolved for a call or override, all subsequent being ignored.
-Acceleo 4 does not allow multiple templates with the same signature in a given module.
-=== Query
+==== Query
-==== Java services
+===== Java services
The best practice for Acceleo 3 was to wrap java services inside of a query. The special `invoke` service was used to this end.
@@ -122,15 +126,15 @@
Acceleo 4 allows users to directly import java services.
-=== File Block
+==== File Block
The second argument for the file block in Acceleo 3 was a boolean (false = overwrite the file, true = append at the end of the file).
Acceleo 4 uses an enumeration, which allows the keyword "overwrite", "append" or "create" instead.
-=== For Block
+==== For Block
-==== Simplified Syntax
+===== Simplified Syntax
Acceleo 3 allowed for loops in two formats:
@@ -146,7 +150,7 @@
Acceleo 4 only allows for the first of these two formats. Note that typing the iteration variable is optional in Acceleo 4.
-==== Iteration count
+===== Iteration count
Acceleo 3 defined an implicit variable, `i`, that held the current iteration count.
@@ -158,7 +162,7 @@
Acceleo 4 does not define any similar variable.
-==== before, separator, after
+===== before, separator, after
Acceleo 3 allowed users to specify a `before` expression that would be inserted right before the content generated by the loop body _if the loop had any iteration_. An `after` that would similarly inserted after the loop body if it generated any content, and finally a `separator` which content would be inserted in-between each iteration result.
@@ -166,9 +170,9 @@
[for (number : Integer | Sequence{1, 2, 3}) before ('int[] array = new int[') separator (', ') after ('];')][number/][/for]
----
-Acceleo 4 only supports `separator`. The migration could convert `before` and `after` into a `Let` holding the content of the iteration expression, then a `If` only generating before and after if the collection is not empty.
+Acceleo 4 only supports `separator`. This is not supported by the migration tool. To translate that in Acceleo 4 you could convert `before` and `after` into a `Let` holding the content of the iteration expression, then a `If` only generating before and after if the collection is not empty.
-==== Pre-condition
+===== Pre-condition
Acceleo 3 allowed users to specify a pre-condition that would be evaluated every iteration and that would prevent all generation for that iteration if `false`.
@@ -178,9 +182,9 @@
[/for]
----
-Acceleo 4 does not have pre-conditions. This could be converted to an `If` at the start of the for body.
+Acceleo 4 does not have pre-conditions. This could be manually converted to an `If` at the start of the for body (this is not supported by the migration tool).
-==== Init block
+===== Init block
Acceleo 3 allowed variable initialization blocks on the for:
@@ -190,15 +194,29 @@
[/for]
----
-Acceleo 4 removes the initialization blocks altogether, so the variable declarations must be transformed into a `let` block before the `For` block.
+Acceleo 4 removes the initialization blocks altogether, so the variable declarations must be manually transformed into a `let` block before the `For` block (this is not supported by the migration tool).
*Note* the initialization block was evaluated before the for itself, and not for every loop.
-=== Let Statement
+===== Ranges
+
+Acceleo 4 does not support ranges, e.g.:
+----
+[for (item : Integer | Sequence{1..5})]
+[item/]
+[/for]
+----
+Such for blocks are ignored by the migration tool.
+
+==== Let Statement
Acceleo 3 only allowed a single variable per `Let`, forcing users to have multiple nested `Let` blocks to define more. The migration could aggregate multiple nested blocks into one with multiple variables if the nested blocks don't use one of the outer `Let`'s variable.
-=== Invocation
+==== ElseLet Blocks
+
+Acceleo 4 does not support elselet blocks, they are ignored by the migration tool.
+
+==== Invocation
Acceleo 3 made use of implicit variables allowing module writers to avoid always specifying the target of an expression or call:
@@ -211,49 +229,49 @@
The implicit variable is always `self`, but the value of `self` may not be intuitive in all cases.
-The migration will have to take specific care of properly replacing the implicit variable with the correct variable for Acceleo 4.
+The migration replaces the implicit variable with the correct variable for Acceleo 4.
-==== Template
+===== Template
Acceleo 3 : `self` is the first argument of the template.
-Acceleo 4 : PENDING
+Acceleo 4 : The migration tool makes the variable explicit, using the first argument of the template
-==== Query
+===== Query
Acceleo 3 : `self` is the first argument of the query.
-Acceleo 4 : PENDING
+Acceleo 4 : The migration tool makes the variable explicit, using the first argument of the query
-==== For
+===== For
Acceleo 3 : `self` has the same value as the iteration variable.
-Acceleo 4 : PENDING
+Acceleo 4 : The migration tool makes the variable explicit, using the iteration variable
-==== If
+===== If
Acceleo 3 : The value of `self` is not changed within the `if` scope and remains the value of `self` outside of the `if`.
-Acceleo 4 : PENDING
+Acceleo 4 : The migration tool makes the variable explicit, using the parent context
-==== let
+===== let
Acceleo 3 : The value of `self` is not changed within the `let` scope and remains the value of `self` outside of the `let`.
-Acceleo 4 : PENDING
+Acceleo 4 : The migration tool makes the variable explicit, using the parent context
-==== Expression
+===== Expression
Acceleo 3/OCL : The value of `self` is defined by the current Acceleo scope and will not be altered by OCL.
-Acceleo 4/AQL : PENDING
+Acceleo 4/AQL : The migration tool makes the variable explicit, using the parent context
You can have a look at the MTL to AQL https://www.eclipse.org/acceleo/documentation/aql.html#MigratingfromMTLqueries[migration guide].
-=== Module Element Call
+==== Module Element Call
-==== Template invocation
+===== Template invocation
Acceleo 3 allowed special template calls such as the following:
@@ -269,13 +287,13 @@
Both `before` and `after` expression are handled by Acceleo 3 and will respectively generate their content before and after the callee's generated text. This is true even if the callee does not generate any text.
-`separator` is not implemented by the engine so the migration can strip it entirely.
+`separator` is not implemented by the engine so the migration strips it entirely.
-==== Query invocation
+===== Query invocation
-Similar to template invocations, query invocations support `before`, `separator` and `after` expressions. None of which is implemented in the Acceleo 3 generation engine so they can all be stripped entirely.
+Similar to template invocations, query invocations support `before`, `separator` and `after` expressions. None of which is implemented in the Acceleo 3 generation engine so they are stripped entirely.
-=== Variable
+==== Variable
Acceleo 3 supported unqualified type names for the variables.
@@ -285,7 +303,7 @@
[/let]
----
-Acceleo 4 only accepts qualified types for the classifiers and the above should become:
+Acceleo 4 only accepts qualified types for the classifiers and the above becomes:
----
[let var : ecore::EPackage = anotherVar.eContainer()]
@@ -293,15 +311,20 @@
[/let]
----
-=== Expressions
+==== Expressions
Acceleo 3 was using OCL as the underlying expression language, while Acceleo 4 is using AQL. Please look at the https://www.eclipse.org/acceleo/documentation/#MigratingfromMTLqueries[AQL Documentation] for more information on migrating OCL expressions to AQL.
-== Behavior Changes
+==== Set and Bags
-=== Modules
+The OCL collection types Set and Bag are not anymore available in AQL, which supports only two types: Sequence and OrderedSet. All collections are ordered.
+Thus the migration tool translates each Set into an OrderedSet and each Bag into a Sequence.
-==== inheritance behavior
+=== Behavior Changes
+
+==== Modules
+
+===== inheritance behavior
In Acceleo 3, once an overriding module (child) called a public or protected template of its extended module (parent), the execution flow would never come down to the child again until we `returned` out of the callee. This is contrary to other Object-oriented languages in which a `super` template could call down an `overriden` other template from the child when necessary.
@@ -331,9 +354,9 @@
[/template]
----
-=== Query
+==== Query
-==== Validation
+===== Validation
In Acceleo 3, the return type of a query was not validated at compile time, so it was very easy for ClassCastExceptions to occur at runtime or for invalid templates to be written with the error only detected at runtime.
@@ -355,13 +378,13 @@
Acceleo 4 validates the return type of the query's body expression.
-==== Cache
+===== Cache
The MTL specification enforces that "A query is required to produce the same result each time it is invoked with the same arguments.". The result of a query call was thus cached in Acceleo 3, and never reevaluated. (This behavior could be disabled through a preference for Acceleo 3.)
Acceleo 4 will always reevaluate the query's body even if the same argument list is passed twice.
-=== Let Statement
+==== Let Statement
The Acceleo 3 let statement was equivalent to an "instance of" condition check to enter a block.
@@ -375,4 +398,10 @@
In Acceleo 3, if the result of evaluating `anotherVar.eContainer()` is of type `EPackage` (the declared type of variable `var`), then this block will output the result of evaluating its body. In any other event, this would output no text and cause no failure as the block would be simply ignored if the types do not match.
-In Acceleo 4, this same let block will cause validation errors if the type of `anotherVar.eContainer()` cannot be an `EPackage`.
\ No newline at end of file
+In Acceleo 4, this same let block will cause validation errors if the type of `anotherVar.eContainer()` cannot be an `EPackage`.
+
+=== Limitations
+
+==== Comments
+
+Comments are mostly ignored by the migration tool, except for module / template / queries documentation.
\ No newline at end of file
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/start.adoc b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/start.adoc
new file mode 100644
index 0000000..f8f1b9f
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/start.adoc
@@ -0,0 +1,47 @@
+In this section, you will create a new project to work with Acceleo.
+
+First you need to create a *Java project*:
+
+1. Inside Eclipse select the menu item *File > New > Project...* to open the *New Project* wizard,
+2. Select *Java Project* then click *Next* to start the *New Java Project* wizard:
+
+image::images/NewProjectWizard.png[]
+
+On this page:
+
+1. Enter the Project name,
+2. Select the Java Runtime Environment (JRE) or leave it at the default,
+3. Then click *Finish*.
+
+image::images/NewProject.png[]
+
+1. In the *Package Explorer*, expand the project and select the source folder *src*,
+2. Select the menu item *File > New > File* to open the *New File* wizard,
+3. Select the *src* folder as parent folder,
+4. Enter the File name with the extension *.mtl*, for example: `MyTemplate.mtl`,
+5. Then click *Finish*.
+
+image::images/NewFile.png[]
+
+An empty editor opens, you can start writing your generation template.
+
+image::images/NewTemplate.png[]
+
+In order to launch an Acceleo generator, you just have to right-click on your main module and use the *Run As* menu.
+
+image::images/RunAs.png[Run As]
+
+From there the *Launch Configuration* menu will open.
+If you already have created a launch configuration you can access the launch configuration menu from the *Run > Run Configurations...* menu.
+In this menu, you will have access to the Acceleo Launch configuration.
+You just have to select:
+
+* your main *module file*,
+* your input *model file*,
+* the *destination folder* of the generation.
+
+image::images/LaunchConfig.png[Launch Configuration]
+
+INFO: Check that your generation is finished by opening the *Console* view.
+You should see a message like this `<terminated> generate.mtl[Acceleo4]`.
+
\ No newline at end of file
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/syntax.adoc b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/syntax.adoc
index 5064b12..46b495c 100644
--- a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/syntax.adoc
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/syntax.adoc
@@ -267,14 +267,12 @@
This is an Acceleo Query Language expression. It is used to navigate through models and call services. In the context of Acceleo, <<Template>> and <<Query>> can be called as services.
-TODO link AQL documentation
+See the https://www.eclipse.org/acceleo/documentation/aql.html[AQL documentation] for more details about the language itself, the full list of standard services, and the differences with Acceleo/MTL.
=== AQL Type Literal
This is a type literal as defined in the Acceleo Query Language.
-TODO link AQL documentation
-
=== Query
A query references an <<AQL Expression>> with parameters and can be called as a service. It can be preceded by a <<Module Element documentation>>.
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/tool.adoc b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/tool.adoc
new file mode 100644
index 0000000..1b472d8
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/tool.adoc
@@ -0,0 +1,142 @@
+=== The Acceleo Editor
+
+.Before you Start
+[IMPORTANT]
+====
+Use a *Java Project* and the classical *Java Perspective* for writing your Acceleo templates `.mtl` in the *src* folder.
+====
+
+The module editor provides the following features:
+
+* Syntax highlighting;
+* Content assistant (`Ctrl + Space`);
+* Error detection;
+* Outlines;
+* Quick outline (`Ctrl + O`);
+* Open declaration (either with `Ctrl + Left Click` or `F3`),
+* White spaces.
+
+==== Syntax Highlighting
+The editor uses specific colors for Acceleo templates:
+
+* red is used for template tags;
+* purple is used for other tags (queries, modules, imports, ...);
+* blue is used for dynamic expressions in templates or other places;
+* green is used for comments and String literals;
+* black is used for static text or query bodies.
+
+image::images/SyntaxHighlighting.png[Syntax Highlighting]
+
+==== Content assist
+
+The content assistant is traditionally invoked with `Ctrl + Space`.
+It proposes a choice of all elements that make sense at the place of invocation.
+It is available everywhere, so don't hesitate to hit `Ctrl + Space` anywhere!
+
+image::images/ContentAssistMetamodel.png[Content Assist]
+
+==== Real Time Errors Detection
+
+Obviously, Acceleo displays error markers when errors are detected.
+Acceleo displays error markers whenever a module file is not valid, whatever the reason.
+Errors appear in the *Problems* view (generally displayed at the bottom of the perspective), and double-clicking on an error in this view directly takes you to the file where it is located.
+
+image::images/ErrorInProblemsView.png[Errors in Problems view]
+
+Files with errors also appear with an error decorator.
+
+image::images/ErrorFile.png[Error at file level]
+
+Just hover the marker in the editor margin with the mouse to get a tooltip to appear with an explanation of the problem.
+
+image::images/ErrorTooltip.png[Error Tooltip]
+
+==== Outlines
+One of the great benefits of modern IDE tooling is the capacity to easily navigate in code from elements to their declarations and, vice-versa, from declarations to usages.
+
+===== The dynamic outline
+The traditional Eclipse *Outline* view is used by Acceleo to display the module's structure metamodels, templates, queries can be seen there, and double-clicking on any of them places the cursor at the corresponding position in the module (in the editor).
+
+image::images/Outline.png[Outline]
+
+===== The quick outline
+The quick outline, which can be displayed using `Ctrl + O`, displays just the necessary information to access any element in the current module.
+So, hitting `Ctrl + O` displays a pop-up with a list of templates and queries.
+
+A text field at the top allows you to quickly filter the content in order to easily find what you are looking for.
+
+image::images/QuickOutline.png[QuickOutline]
+
+==== Open Declaration
+
+The traditional shortcut `F3` is supported by Acceleo, along with `Ctrl + click`, which both take you to the declaration of the selected or clicked element.
+This is supported for all kinds of elements: templates, queries, metamodels, metamodel elements, EOperations, etc.
+
+image::images/OpenDeclaration.png[Open Declaration]
+
+==== White spaces
+
+When generating text, and especially code, white spaces and indentation is an important point.
+In order to keep template code indentation from interfering with the generated output, a few rules applies:
+
+- each block has a *mandatory indentation* of *two characters* than will not be generated in the output (in yellow below)
+- when generating a block if the last generated line is not empty, it is repeated at the beginning of each line generated by the block (in red below)
+
+image::images/Indentation.png[Indentation]
+
+[WARNING]
+====
+In a template you have to *let 2 whitespaces at the beginning of each line*, else the generated content will be truncated by 2 characters.
+====
+
+image::images/IndentationIssue.png[Truncated generation due to indentation]
+
+=== The Acceleo Debugger
+
+==== Breakpoints
+
+To add a breakpoint somewhere in a template, just double-click in the left margin on the line where you want to add the breakpoint.
+A nice bluish marker should appear, which should be very familiar to eclipse users.
+
+image::images/Breakpoint.png[Breakpoint]
+
+NOTE: Conditional breakpoints are not supported.
+
+==== Step by step execution
+
+To debug an Acceleo generation:
+
+* Right-click on your `.mtl` file, and select *Debug As > Debug Acceleo 4 generation*.
+
+image::images/DebugAs.png[Debug As]
+
+It is actually recommended to switch to the *Debug Perspective*, which is really more appropriate to debug executions.
+
+image::images/DebugSession.png[Debug]
+
+The debug perspective should be quite familiar to people used to the eclipse IDE.
+The *Debug* view (on the top left) displays the stack of the current execution.
+Clicking on any element of the stack will simultaneously display the corresponding Acceleo code in the edition area.
+
+The *Variables* view displays currently accessible variables.
+In the example below, the execution has met a breakpoint when computing `Attributes` for a class, so the current input is a class.
+The Variables view tells us that the current class is called `EAttribute`.
+
+image::images/VariablesView.png[VariablesView]
+
+NOTE: The debugger cannot step into AQL expressions only Acceleo elements are visible in the Variables view.
+
+As usual, it is possible to:
+
+* *Step into* a template (`F5`);
+* *Step over* a template (`F6`);
+* *Step Return* (`F7`), which means "go to the end of the current template";
+* *Resume* execution (`F8`);
+* *Stop* execution (`Ctrl + F2`).
+The icons above the *Debug* view serve the same purpose.
+
+Acceleo breakpoints can be temporarily deactivated, thanks to the *Breakpoints* view.
+Just uncheck the checkbox in front of a breakpoint to deactivate it.
+Here is an example of a deactivated breakpoint in this view:
+
+image::images/UnactivBreakpoint.png[Unchecked Breakpoint]
diff --git a/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/use.adoc b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/use.adoc
new file mode 100644
index 0000000..fb23931
--- /dev/null
+++ b/plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/use.adoc
@@ -0,0 +1,44 @@
+Acceleo 4 can be used programmatically and for instance integrated in other products.
+
+=== Parsing
+
+[source,java]
+---------
+URI destination = URI.createURI(...);
+environment = new AcceleoEnvironment(new DefaultGenerationStrategy(), destination);
+IQualifiedNameResolver moduleResolver = new ClassLoaderQualifiedNameResolver(getClass().getClassLoader(), environment.getQueryEnvironment());
+environment.setModuleResolver(moduleResolver);
+Module module = environment.getModule(qualifiedName);
+---------
+
+
+=== Validation
+
+[source,java]
+----
+AcceleoValidator validator = new AcceleoValidator(environment);
+List<IValidationMessage> messages = validator.validate(astResult, qualifiedName).getValidationMessages();
+----
+
+=== Completion
+
+[source,java]
+----
+AcceleoCompletor completor = new AcceleoCompletor();
+String source = ...;
+List<ICompletionProposal> proposals = completor.getProposals(environment, source, position);
+----
+
+=== Generation
+
+[source,java]
+----
+AcceleoEvaluator evaluator = new AcceleoEvaluator(environment);
+ResourceSetImpl rs = new ResourceSetImpl();
+Resource model = rs.getResource(..., true);
+AcceleoUtil.generate(evaluator, environment, module, model);
+----
+
+=== Unit test module
+
+You can unit test your modules using the same JUnit test suite we are using for the development of Acceleo 4. You will simply need to create a class extending the class org.eclipse.acceleo.tests.utils.AbstractEvaluationTestSuite and create a folder with you test folders. Those folders need to respect a naming convention. You can find a working example with the class https://git.eclipse.org/c/acceleo/org.eclipse.acceleo.git/tree/acceleo-aql/org.eclipse.acceleo.aql.tests/src/org/eclipse/acceleo/tests/evaluation/FileStatementTests.java?h=acceleo-aql[FileStatementTests] and the corresponding https://git.eclipse.org/c/acceleo/org.eclipse.acceleo.git/tree/acceleo-aql/org.eclipse.acceleo.aql.tests/resources/evaluation/fileStatement?h=acceleo-aql[folder].
\ No newline at end of file
