re-generate webpages from adoc
diff --git a/articles/index.html b/articles/index.html
index 16c065c..f26723d 100644
--- a/articles/index.html
+++ b/articles/index.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>N4JS Articles</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/faq/comparison-java.html b/faq/comparison-java.html
index 6e33c26..6942623 100644
--- a/faq/comparison-java.html
+++ b/faq/comparison-java.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>N4JS and Java</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/faq/comparison-typescript.html b/faq/comparison-typescript.html
index 6808798..45f273a 100644
--- a/faq/comparison-typescript.html
+++ b/faq/comparison-typescript.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>N4JS and TypeScript</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
@@ -198,6 +198,9 @@
</tr>
</tbody>
</table>
+<div class="paragraph">
+<p>TypeScript 3 introduced the <code>unknown</code> type which behaves like N4JS’s <code>any</code> type, with the exception that it isn’t currently being used by default and has to be declared explicitly.</p>
+</div>
</div>
<div class="sect2">
<h3 id="_type_errors_are_show_stoppers_in_n4js"><a class="link" href="#_type_errors_are_show_stoppers_in_n4js">Type Errors Are Show-Stoppers in N4JS</a></h3>
@@ -613,7 +616,7 @@
</dl>
</div>
<div class="paragraph">
-<p>The difference between structural and nominal typing is described in further detail in the <a href="features/nominal-vs-structural-typing.html#nominal_vs_structural_typing">nominal vs. structural subtyping feature</a>.</p>
+<p>The difference between structural and nominal typing is described in further detail in the <a href="features/nominal-vs-structural-typing.html.html#nominal_vs_structural_typing">nominal vs. structural subtyping feature</a>.</p>
</div>
</div>
<div class="sect2">
diff --git a/faq/index.html b/faq/index.html
index 62100d8..9e5fc61 100644
--- a/faq/index.html
+++ b/faq/index.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>FAQ</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/features/async-await.html b/features/async-await.html
index 15c93fb..dad0dfd 100644
--- a/features/async-await.html
+++ b/features/async-await.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>Async/Await</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/features/dependency-injection.html b/features/dependency-injection.html
index 2f57c82..f9bad9e 100644
--- a/features/dependency-injection.html
+++ b/features/dependency-injection.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>Dependency Injection in N4JS</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/features/generics.html b/features/generics.html
index d5079be..92d2fcc 100644
--- a/features/generics.html
+++ b/features/generics.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>Generics</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/features/index.html b/features/index.html
index 09742de..040442a 100644
--- a/features/index.html
+++ b/features/index.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>Remarks</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/features/modules.html b/features/modules.html
index c524a72..483c200 100644
--- a/features/modules.html
+++ b/features/modules.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>Modules</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/features/nodejs-support.html b/features/nodejs-support.html
index 0944d31..85e2787 100644
--- a/features/nodejs-support.html
+++ b/features/nodejs-support.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>Node.js Support</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
@@ -157,7 +157,7 @@
The <code>package.json</code> content can be customized by creating a <code>package.json</code> template file in the root of
the N4JS project
With this template, additional attributes can be defined.
-This feature is further explained in the <a href="../userguides/npm-export-guide.html#npm_export_guide">npm export guide</a>.</p>
+This feature is further explained in the <a href="../userguides/npm-export-guide.html.html#npm_export_guide">npm export guide</a>.</p>
</div>
</div>
</div>
diff --git a/features/nominal-and-structural-typing.html b/features/nominal-and-structural-typing.html
index 9f95735..2cf0853 100644
--- a/features/nominal-and-structural-typing.html
+++ b/features/nominal-and-structural-typing.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>Nominal And Structural Typing</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/features/testing.html b/features/testing.html
index 3e99596..d3d5ed3 100644
--- a/features/testing.html
+++ b/features/testing.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>Testing</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/headers/articles/docinfo-footer.html b/headers/articles/docinfo-footer.html
new file mode 100644
index 0000000..5559f5b
--- /dev/null
+++ b/headers/articles/docinfo-footer.html
@@ -0,0 +1,65 @@
+<div class="Grid social" style="color:#d5dfea">
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <h2>Quick Links</h2>
+ <ul>
+ <li><a href="../downloads.html">Download</a></li>
+ <li><a href="../userguides/index.html">Documentation</a></li>
+ <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
+ <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
+ </ul>
+ </div>
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <br/><br/>
+ <ul>
+ <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
+ <li><a href="http://n4js.blogspot.de/">Blog</a></li>
+ <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
+ <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
+ <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
+ </ul>
+ </div>
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <br/><br/>
+ <ul>
+ <li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
+ <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
+ <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
+ <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
+ <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
+ </ul>
+ </div>
+ <div style="clear: both; height: 0; overflow: hidden;"></div>
+</div>
+
+<script>
+ // Toggle the table of contents
+ $( "button#tocbutton" ).click(function() {
+ if ($("#tocbutton").css('right') == '25px') {
+ $( "#tocbutton" ).animate({right: '215px'},"slow");
+ $( "#toc.toc2" ).animate({right: '0'},"slow");
+ }
+ else {
+ $( "#tocbutton" ).animate({right: '25px'},"slow");
+ $( "#toc.toc2" ).animate({right: '-13rem'},"slow");
+ }
+ });
+</script>
+
+<script type="text/javascript">
+ // Create a back to top button
+ $('body').prepend('<a href="#" class="back-to-top">Back to Top</a>');
+ var amountScrolled = 500;
+ $(window).scroll(function() {
+ if ( $(window).scrollTop() > amountScrolled ) {
+ $('a.back-to-top').fadeIn('slow');
+ } else {
+ $('a.back-to-top').fadeOut('slow');
+ }
+ });
+ $('a.back-to-top, a.simple-back-to-top').click(function() {
+ $('html, body').animate({
+ scrollTop: 0
+ }, 700);
+ return false;
+ });
+</script>
diff --git a/headers/articles/docinfo.html b/headers/articles/docinfo.html
new file mode 100644
index 0000000..b2d210e
--- /dev/null
+++ b/headers/articles/docinfo.html
@@ -0,0 +1,42 @@
+<!-- ************* Meta ************* -->
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />
+
+<!-- ************* OpenGraph ************-->
+<meta name="description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects.">
+
+<meta property="og:site_name" content="Eclipse N4JS"/>
+<meta property="og:title" content="Eclipse N4JS Language and IDE"/>
+<meta property="og:url" content="https://numberfour.github.io/n4js"/>
+<meta property="og:description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects."/>
+<meta property="og:image" content="../images/n4js.png">
+
+<!-- ************* Favicon ************-->
+<link rel="icon" href="../images/favicon.ico" />
+<link rel="icon" type="image/png" href="../images/favicon-32x32.png" sizes="32x32" />
+<link rel="icon" type="image/png" href="../images/favicon-16x16.png" sizes="16x16" />
+
+<!-- ************* Back-to-top JQuery ************* -->
+<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
+<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>
+
+<!-- ************* Prism.js Syntax Highlighter ******-->
+<link href="../styles/prism.min.css" rel="stylesheet"/>
+<script src="../scripts/prism.js"></script>
+
+<!-- ************* Styles ************* -->
+
+<link rel="stylesheet" type="text/css" href="../styles/n4js-adoc.css">
+
+<!-- ****************** NavBar ****************** -->
+<div id="menubar">
+ <div class="banner">
+ <a href="../index.html"><img id="logo" src="../images/n4js-logo.png" alt="N4JS Language and IDE"></a>
+ </div>
+<ul>
+ <li><a href="../downloads.html"></i>Download</a></li>
+ <li><a href="../community.html"></i>Community</a></li>
+ <li><a href="../userguides/index.html">Documentation</a></li>
+</ul>
+</div>
+<button id="tocbutton">TOC</button>
diff --git a/headers/docinfo-footer.html b/headers/docinfo-footer.html
new file mode 100644
index 0000000..fb1c17b
--- /dev/null
+++ b/headers/docinfo-footer.html
@@ -0,0 +1,41 @@
+<div class="Grid social" style="color:#d5dfea">
+ <ul>
+ <li><a href="downloads.html">Download</a></li>
+ <li><a href="userguides/index.html">Documentation</a></li>
+ <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
+ <li><a href="https://eclipse.org/n4js">Eclipse Project Page</a></li>
+ </ul>
+</div>
+
+<script>
+ // Toggle the table of contents
+ $( "button#tocbutton" ).click(function() {
+ if ($("#tocbutton").css('right') == '25px') {
+ $( "#tocbutton" ).animate({right: '215px'},"slow");
+ $( "#toc.toc2" ).animate({right: '0'},"slow");
+ }
+ else {
+ $( "#tocbutton" ).animate({right: '25px'},"slow");
+ $( "#toc.toc2" ).animate({right: '-13rem'},"slow");
+ }
+ });
+</script>
+
+<script type="text/javascript">
+ // Create a back to top button
+ $('body').prepend('<a href="#" class="back-to-top">Back to Top</a>');
+ var amountScrolled = 300;
+ $(window).scroll(function() {
+ if ( $(window).scrollTop() > amountScrolled ) {
+ $('a.back-to-top').fadeIn('slow');
+ } else {
+ $('a.back-to-top').fadeOut('slow');
+ }
+ });
+ $('a.back-to-top, a.simple-back-to-top').click(function() {
+ $('html, body').animate({
+ scrollTop: 0
+ }, 700);
+ return false;
+ });
+</script>
diff --git a/headers/docinfo.html b/headers/docinfo.html
new file mode 100644
index 0000000..fe76e56
--- /dev/null
+++ b/headers/docinfo.html
@@ -0,0 +1,42 @@
+<!-- ************* Meta ************* -->
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />
+
+<!-- ************* OpenGraph ************-->
+<meta name="description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects.">
+
+<meta property="og:site_name" content="Eclipse N4JS"/>
+<meta property="og:title" content="Eclipse N4JS Language and IDE"/>
+<meta property="og:url" content="https://numberfour.github.io/n4js"/>
+<meta property="og:description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects."/>
+<meta property="og:image" content="../images/n4js.png">
+
+<!-- ************* Favicon ************-->
+<link rel="icon" href="../images/favicon.ico" />
+<link rel="icon" type="image/png" href="../images/favicon-32x32.png" sizes="32x32" />
+<link rel="icon" type="image/png" href="../images/favicon-16x16.png" sizes="16x16" />
+
+<!-- ************* Back-to-top JQuery ************* -->
+<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
+<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>
+
+<!-- ************* Prism.js Syntax Highlighter ******-->
+<link href="styles/prism.min.css" rel="stylesheet"/>
+<script src="scripts/prism.js"></script>
+
+<!-- ************* Styles ************* -->
+
+<link rel="stylesheet" type="text/css" href="styles/n4js-adoc.css">
+
+<!-- ****************** NavBar ****************** -->
+<div id="menubar">
+ <div class="banner">
+ <a href="index.html"><img id="logo" src="images/n4js-logo.png" alt="Eclipse N4JS Language and IDE"></a>
+ </div>
+<ul>
+ <li><a href="downloads.html"></i>Download</a></li>
+ <li><a href="community.html"></i>Community</a></li>
+ <li><a href="userguides/index.html">Documentation</a></li>
+</ul>
+</div>
+<button id="tocbutton">TOC</button>
diff --git a/headers/faq/docinfo-footer.html b/headers/faq/docinfo-footer.html
new file mode 100644
index 0000000..49149cd
--- /dev/null
+++ b/headers/faq/docinfo-footer.html
@@ -0,0 +1,65 @@
+<div class="Grid social" style="color:#d5dfea">
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <h2>Quick Links</h2>
+ <ul>
+ <li><a href="../downloads.html">Download</a></li>
+ <li><a href="../userguides/index.html">Documentation</a></li>
+ <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
+ <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
+ </ul>
+ </div>
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <br/><br/>
+ <ul>
+ <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
+ <li><a href="http://n4js.blogspot.de/">Blog</a></li>
+ <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
+ <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
+ <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
+ </ul>
+ </div>
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <br/><br/>
+ <ul>
+ <li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
+ <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
+ <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
+ <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
+ <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
+ </ul>
+ </div>
+ <div style="clear: both; height: 0; overflow: hidden;"></div>
+</div>
+
+<script>
+ // Toggle the table of contents
+ $( "button#tocbutton" ).click(function() {
+ if ($("#tocbutton").css('right') == '25px') {
+ $( "#tocbutton" ).animate({right: '215px'},"slow");
+ $( "#toc.toc2" ).animate({right: '0'},"slow");
+ }
+ else {
+ $( "#tocbutton" ).animate({right: '25px'},"slow");
+ $( "#toc.toc2" ).animate({right: '-13rem'},"slow");
+ }
+ });
+</script>
+
+<script type="text/javascript">
+ // Create a back to top button
+ $('body').prepend('<a href="#" class="back-to-top">Back to Top</a>');
+ var amountScrolled = 300;
+ $(window).scroll(function() {
+ if ( $(window).scrollTop() > amountScrolled ) {
+ $('a.back-to-top').fadeIn('slow');
+ } else {
+ $('a.back-to-top').fadeOut('slow');
+ }
+ });
+ $('a.back-to-top, a.simple-back-to-top').click(function() {
+ $('html, body').animate({
+ scrollTop: 0
+ }, 700);
+ return false;
+ });
+</script>
diff --git a/headers/faq/docinfo.html b/headers/faq/docinfo.html
new file mode 100644
index 0000000..6172a09
--- /dev/null
+++ b/headers/faq/docinfo.html
@@ -0,0 +1,52 @@
+<!-- ************* Meta ************* -->
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />
+
+<!-- ************* OpenGraph ************-->
+<meta name="description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects.">
+
+<meta property="og:site_name" content="Eclipse N4JS"/>
+<meta property="og:title" content="Eclipse N4JS Language and IDE"/>
+<meta property="og:url" content="https://numberfour.github.io/n4js"/>
+<meta property="og:description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects."/>
+<meta property="og:image" content="../images/n4js.png">
+
+<!-- ************* Favicon ************-->
+<link rel="icon" href="../images/favicon.ico" />
+<link rel="icon" type="image/png" href="../images/favicon-32x32.png" sizes="32x32" />
+<link rel="icon" type="image/png" href="../images/favicon-16x16.png" sizes="16x16" />
+
+<!-- ************* Back-to-top JQuery ************* -->
+<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
+<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>
+
+<!-- ************* Prism.js Syntax Highlighter ******-->
+<link href="../styles/prism.min.css" rel="stylesheet"/>
+<script src="../scripts/prism.js"></script>
+
+<!-- ************* Styles ************* -->
+
+<link rel="stylesheet" type="text/css" href="../styles/n4js-adoc.css">
+
+<!-- ****************** NavBar ****************** -->
+<div id="menubar">
+ <div class="banner">
+ <a href="../index.html"><img id="logo" src="../images/n4js-logo.png" alt="N4JS Language and IDE"></a>
+ </div>
+<ul>
+ <li><a href="../downloads.html"></i>Download</a></li>
+ <li><a href="../community.html"></i>Community</a></li>
+ <li><a href="../userguides/index.html">Documentation</a></li>
+</ul>
+</div>
+<button id="tocbutton">TOC</button>
+<div id=faq>
+<nav>
+ <h2>FAQ</h2>
+ <ul>
+ <li><a href="index.html" >FAQ</a></li>
+ <li><a href="comparison-java.html" class="is-active">N4JS and Java</a></li>
+ <li><a href="comparison-typescript.html" >N4JS and Typescript</a></li>
+ </ul>
+</nav>
+</div>
diff --git a/headers/features/docinfo-footer.html b/headers/features/docinfo-footer.html
new file mode 100644
index 0000000..49149cd
--- /dev/null
+++ b/headers/features/docinfo-footer.html
@@ -0,0 +1,65 @@
+<div class="Grid social" style="color:#d5dfea">
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <h2>Quick Links</h2>
+ <ul>
+ <li><a href="../downloads.html">Download</a></li>
+ <li><a href="../userguides/index.html">Documentation</a></li>
+ <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
+ <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
+ </ul>
+ </div>
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <br/><br/>
+ <ul>
+ <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
+ <li><a href="http://n4js.blogspot.de/">Blog</a></li>
+ <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
+ <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
+ <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
+ </ul>
+ </div>
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <br/><br/>
+ <ul>
+ <li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
+ <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
+ <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
+ <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
+ <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
+ </ul>
+ </div>
+ <div style="clear: both; height: 0; overflow: hidden;"></div>
+</div>
+
+<script>
+ // Toggle the table of contents
+ $( "button#tocbutton" ).click(function() {
+ if ($("#tocbutton").css('right') == '25px') {
+ $( "#tocbutton" ).animate({right: '215px'},"slow");
+ $( "#toc.toc2" ).animate({right: '0'},"slow");
+ }
+ else {
+ $( "#tocbutton" ).animate({right: '25px'},"slow");
+ $( "#toc.toc2" ).animate({right: '-13rem'},"slow");
+ }
+ });
+</script>
+
+<script type="text/javascript">
+ // Create a back to top button
+ $('body').prepend('<a href="#" class="back-to-top">Back to Top</a>');
+ var amountScrolled = 300;
+ $(window).scroll(function() {
+ if ( $(window).scrollTop() > amountScrolled ) {
+ $('a.back-to-top').fadeIn('slow');
+ } else {
+ $('a.back-to-top').fadeOut('slow');
+ }
+ });
+ $('a.back-to-top, a.simple-back-to-top').click(function() {
+ $('html, body').animate({
+ scrollTop: 0
+ }, 700);
+ return false;
+ });
+</script>
diff --git a/headers/features/docinfo.html b/headers/features/docinfo.html
new file mode 100644
index 0000000..ede334c
--- /dev/null
+++ b/headers/features/docinfo.html
@@ -0,0 +1,42 @@
+<!-- ************* Meta ************* -->
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />
+
+<!-- ************* OpenGraph ************-->
+<meta name="description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects.">
+
+<meta property="og:site_name" content="Eclipse N4JS"/>
+<meta property="og:title" content="Eclipse N4JS Language and IDE"/>
+<meta property="og:url" content="https://numberfour.github.io/n4js"/>
+<meta property="og:description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects."/>
+<meta property="og:image" content="../images/n4js.png">
+
+<!-- ************* Favicon ************-->
+<link rel="icon" href="../images/favicon.ico" />
+<link rel="icon" type="image/png" href="../images/favicon-32x32.png" sizes="32x32" />
+<link rel="icon" type="image/png" href="../images/favicon-16x16.png" sizes="16x16" />
+
+<!-- ************* Back-to-top JQuery ************* -->
+<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
+<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>
+
+<!-- ************* Prism.js Syntax Highlighter ******-->
+<link href="../styles/prism.min.css" rel="stylesheet"/>
+<script src="../scripts/prism.js"></script>
+
+<!-- ************* Styles ************* -->
+
+<link rel="stylesheet" type="text/css" href="../styles/n4js-adoc.css">
+
+<!-- ****************** NavBar ****************** -->
+<div id="menubar">
+ <div class="banner">
+ <a href="../index.html"><img id="logo" src="../images/n4js-logo.png" alt="Eclipse N4JS Language and IDE"></a>
+ </div>
+<ul>
+ <li><a href="../downloads.html"></i>Download</a></li>
+ <li><a href="../community.html"></i>Community</a></li>
+ <li><a href="../userguides/index.html">Documentation</a></li>
+</ul>
+</div>
+<button id="tocbutton">TOC</button>
diff --git a/headers/releases/docinfo-footer.html b/headers/releases/docinfo-footer.html
new file mode 100644
index 0000000..49149cd
--- /dev/null
+++ b/headers/releases/docinfo-footer.html
@@ -0,0 +1,65 @@
+<div class="Grid social" style="color:#d5dfea">
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <h2>Quick Links</h2>
+ <ul>
+ <li><a href="../downloads.html">Download</a></li>
+ <li><a href="../userguides/index.html">Documentation</a></li>
+ <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
+ <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
+ </ul>
+ </div>
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <br/><br/>
+ <ul>
+ <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
+ <li><a href="http://n4js.blogspot.de/">Blog</a></li>
+ <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
+ <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
+ <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
+ </ul>
+ </div>
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <br/><br/>
+ <ul>
+ <li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
+ <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
+ <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
+ <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
+ <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
+ </ul>
+ </div>
+ <div style="clear: both; height: 0; overflow: hidden;"></div>
+</div>
+
+<script>
+ // Toggle the table of contents
+ $( "button#tocbutton" ).click(function() {
+ if ($("#tocbutton").css('right') == '25px') {
+ $( "#tocbutton" ).animate({right: '215px'},"slow");
+ $( "#toc.toc2" ).animate({right: '0'},"slow");
+ }
+ else {
+ $( "#tocbutton" ).animate({right: '25px'},"slow");
+ $( "#toc.toc2" ).animate({right: '-13rem'},"slow");
+ }
+ });
+</script>
+
+<script type="text/javascript">
+ // Create a back to top button
+ $('body').prepend('<a href="#" class="back-to-top">Back to Top</a>');
+ var amountScrolled = 300;
+ $(window).scroll(function() {
+ if ( $(window).scrollTop() > amountScrolled ) {
+ $('a.back-to-top').fadeIn('slow');
+ } else {
+ $('a.back-to-top').fadeOut('slow');
+ }
+ });
+ $('a.back-to-top, a.simple-back-to-top').click(function() {
+ $('html, body').animate({
+ scrollTop: 0
+ }, 700);
+ return false;
+ });
+</script>
diff --git a/headers/releases/docinfo.html b/headers/releases/docinfo.html
new file mode 100644
index 0000000..b2d210e
--- /dev/null
+++ b/headers/releases/docinfo.html
@@ -0,0 +1,42 @@
+<!-- ************* Meta ************* -->
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />
+
+<!-- ************* OpenGraph ************-->
+<meta name="description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects.">
+
+<meta property="og:site_name" content="Eclipse N4JS"/>
+<meta property="og:title" content="Eclipse N4JS Language and IDE"/>
+<meta property="og:url" content="https://numberfour.github.io/n4js"/>
+<meta property="og:description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects."/>
+<meta property="og:image" content="../images/n4js.png">
+
+<!-- ************* Favicon ************-->
+<link rel="icon" href="../images/favicon.ico" />
+<link rel="icon" type="image/png" href="../images/favicon-32x32.png" sizes="32x32" />
+<link rel="icon" type="image/png" href="../images/favicon-16x16.png" sizes="16x16" />
+
+<!-- ************* Back-to-top JQuery ************* -->
+<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
+<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>
+
+<!-- ************* Prism.js Syntax Highlighter ******-->
+<link href="../styles/prism.min.css" rel="stylesheet"/>
+<script src="../scripts/prism.js"></script>
+
+<!-- ************* Styles ************* -->
+
+<link rel="stylesheet" type="text/css" href="../styles/n4js-adoc.css">
+
+<!-- ****************** NavBar ****************** -->
+<div id="menubar">
+ <div class="banner">
+ <a href="../index.html"><img id="logo" src="../images/n4js-logo.png" alt="N4JS Language and IDE"></a>
+ </div>
+<ul>
+ <li><a href="../downloads.html"></i>Download</a></li>
+ <li><a href="../community.html"></i>Community</a></li>
+ <li><a href="../userguides/index.html">Documentation</a></li>
+</ul>
+</div>
+<button id="tocbutton">TOC</button>
diff --git a/headers/userguides/docinfo-footer.html b/headers/userguides/docinfo-footer.html
new file mode 100644
index 0000000..12a2d6b
--- /dev/null
+++ b/headers/userguides/docinfo-footer.html
@@ -0,0 +1,64 @@
+<div class="Grid social" style="color:#d5dfea">
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <h2>Quick Links</h2>
+ <ul>
+ <li><a href="../downloads.html">Download</a></li>
+ <li><a href="index.html">Documentation</a></li>
+ <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
+ <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
+ </ul>
+ </div>
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <br/><br/>
+ <ul>
+ <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
+ <li><a href="http://n4js.blogspot.de/">Blog</a></li>
+ <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
+ <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
+ <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
+ </ul>
+ </div>
+ <div class="Cell Cell--2-12 m-Cell--withMargin">
+ <br/><br/>
+ <ul>
+ <li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
+ <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
+ <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
+ <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
+ <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
+ </ul>
+ </div>
+ <div style="clear: both; height: 0; overflow: hidden;"></div>
+</div>
+
+<script>
+ // Toggle the table of contents
+ $( "button#tocbutton" ).click(function() {
+ if ($("#tocbutton").css('right') == '25px') {
+ $( "#tocbutton" ).animate({right: '215px'},"slow");
+ $( "#toc.toc2" ).animate({right: '0'},"slow");
+ }
+ else {
+ $( "#tocbutton" ).animate({right: '25px'},"slow");
+ $( "#toc.toc2" ).animate({right: '-13rem'},"slow");
+ }
+ });
+</script>
+<script type="text/javascript">
+ // Create a back to top button
+ $('body').prepend('<a href="#" class="back-to-top">Back to Top</a>');
+ var amountScrolled = 300;
+ $(window).scroll(function() {
+ if ( $(window).scrollTop() > amountScrolled ) {
+ $('a.back-to-top').fadeIn('slow');
+ } else {
+ $('a.back-to-top').fadeOut('slow');
+ }
+ });
+ $('a.back-to-top, a.simple-back-to-top').click(function() {
+ $('html, body').animate({
+ scrollTop: 0
+ }, 700);
+ return false;
+ });
+</script>
diff --git a/headers/userguides/docinfo.html b/headers/userguides/docinfo.html
new file mode 100644
index 0000000..1848f61
--- /dev/null
+++ b/headers/userguides/docinfo.html
@@ -0,0 +1,43 @@
+<!-- ************* Meta ************* -->
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />
+
+<!-- ************* OpenGraph ************-->
+<meta name="description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects.">
+
+<meta property="og:site_name" content="Eclipse N4JS"/>
+<meta property="og:title" content="Eclipse N4JS Language and IDE"/>
+<meta property="og:url" content="https://numberfour.github.io/n4js"/>
+<meta property="og:description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects."/>
+<meta property="og:image" content="../images/n4js.png">
+
+<!-- ************* Favicon ************-->
+<link rel="icon" href="../images/favicon.ico" />
+<link rel="icon" type="image/png" href="../images/favicon-32x32.png" sizes="32x32" />
+<link rel="icon" type="image/png" href="../images/favicon-16x16.png" sizes="16x16" />
+
+<!-- ************* Back-to-top JQuery ************* -->
+<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
+<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>
+
+<!-- ************* Prism.js Syntax Highlighter ******-->
+<link href="../styles/prism.min.css" rel="stylesheet"/>
+<script src="../scripts/prism.js"></script>
+
+<!-- ************* Styles ************* -->
+
+<link rel="stylesheet" type="text/css" href="../styles/n4js-adoc.css">
+
+<!-- ****************** NavBar ****************** -->
+<div id="menubar">
+ <div class="banner">
+ <a href="../index.html"><img id="logo" src="../images/n4js-logo.png" alt="N4JS Language and IDE"></a>
+ </div>
+<ul>
+ <li><a href="../downloads.html"></i>Download</a></li>
+ <li><a href="../community.html"></i>Community</a></li>
+ <li><a href="index.html">Documentation</a></li>
+</ul>
+</div>
+<button id="tocbutton">TOC</button>
+
diff --git a/releases/index.html b/releases/index.html
index 4687433..6f89322 100644
--- a/releases/index.html
+++ b/releases/index.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>Releases</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/releases/reporting-bugs.html b/releases/reporting-bugs.html
index d90f671..1aabbaf 100644
--- a/releases/reporting-bugs.html
+++ b/releases/reporting-bugs.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>Reporting Bugs</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/src/articles/index.adoc b/src/articles/index.adoc
new file mode 100644
index 0000000..09ffd03
--- /dev/null
+++ b/src/articles/index.adoc
@@ -0,0 +1,53 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+:doctype: book
+:notitle:
+
+.N4JS Articles
+= N4JS Articles
+
+.A selection of articles covering the features of N4JS, Current Releases, how to report bugs and contribute to the platform.
+
+== Index
+
+* <<../features/index.adoc#n4js-language-and-ide-features,Feature Table>> - A comprehensive overview of current and planned features of the N4JS IDE.
+* <<../features/async-await.adoc#async-await,Async/Await>> - Learn about the benefits of asynchronous data flows and how they work with N4JS code.
+* <<../features/dependency-injection.adoc#dependency-injection-in-n4js,Dependency Injection>> - Configure dependencies between classes with built-in Dependency Injection support.
+* <<../features/modules.adoc#modules,Modules>> - Modules help keep code well-defined and easy to comprehend. Read about keeping large projects maintainable with Module support within the N4JS IDE.
+* <<../features/nodejs-support.adoc#node-js-support,Node.js Support>> - Seamless integration of N4JS projects with existing node.js-based environments.
+* <<../features/nominal-and-structural-typing.adoc#nominal-and-structural-typing,Nominal & Structural Typing>> - N4JS provides both forms of typing. Read the feature on how they are combined in N4JS.
+* <<../features/testing.adoc#testing,Testing>> - The N4JS IDE and the built-in test execution runtime Mangelhaft were designed from the ground-up to support Test Driven Development. Explore how testing with N4JS will help ensure your projects behave as expected.
+
+---
+**Releases**
+
+* <<../releases/index.adoc#releases,Information on N4JS Releases>> - This page contains details on the current state of N4JS and how we track issues.
+* <<../releases/reporting-bugs.adoc#reporting-bugs,Reporting Bugs>> - Find out how to report N4JS bugs from within the IDE with Xpect.
+
+---
+
+**FAQ**
+
+* <<../faq/index.adoc#faq,Frequenctly Asked Questions>> -Common N4JS topics such as Open-Sourcing, JavaScript, Java and Typescript Comparison.
+* <<../faq/comparison-java.adoc#n4js-and-java,N4JS & Java Comparison>> - A comparison between the features of N4JS and Java.
+* <<../faq/comparison-typescript.adoc#n4js-and-typescript,N4JS & Typescript Comparison>> - A comparison between the features of N4JS and Typescript.
+
+---
+
+**N4JS Userguides**
+
+
+From brief quickstart guides to fully-involved tutorials, the following N4JS documentation will help beginners get started with the N4JS IDE and advanced users to build and maintain large server-side projects.
+
+* <<../userguides/n4js-ide-setup.adoc#_ide_setup,N4JS IDE Setup Guide>> - Basic installation and setup instructions.
+* <<../userguides/npm-export-guide.adoc#_npm_export_guide,npm Export Guide>> - Basic npm export and publishing instructions.
+* <<../userguides/tutorial.adoc#_tutorial,In-Depth Tutorial>> - Begin using the more powerful features N4JS has to offer!
diff --git a/src/faq/comparison-java.adoc b/src/faq/comparison-java.adoc
new file mode 100644
index 0000000..dfa3623
--- /dev/null
+++ b/src/faq/comparison-java.adoc
@@ -0,0 +1,244 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+
+
+.N4JS and Java
+= N4JS and Java
+:doctype: book
+:notitle:
+:toc: right
+
+== Introduction
+
+N4JS is an extension of ECMAScript. It is therefore as different from Java as ECMAScript is. There are additional features which
+are quite similar to Java, actually making ECMAScript feel more like **Java**Script. In the following, we describe the most
+important similarities and differences of Java and N4JS.
+
+
+
+== Similarities
+
+
+The general idea of N4JS is to make ECMAScript as type safe as Java. For that reason, N4JS adds a static type system to ECMAScript.
+Many concepts of this type system are similar to Java's type system.
+
+=== Nominal Typing
+
+
+N4JS supports both, <<../features/nominal-and-structural-typing#nominal_and_structural_typing,nominal and structural typing>>. Java has a nominal
+type system and this is also the default mode in N4JS. When you just use a simple type reference, nominal typing (as in Java) is applied.
+
+
+The following example should be easily understood by Java developers:
+
+
+[source,java]
+----
+class A { public foo(): void {} }
+class B extends A {}
+class C { public foo(): void {} }
+
+function f(p: A) {}
+
+f(new B());
+f(new C()); // error: C is not a subtype of A.
+----
+
+
+This example will produce an error in the last line because `C` is not a nominal subtype of `A`.
+
+
+Overriding of members in N4JS is quite similar to Java although N4JS allows for slightly more flexibility due to the underlying
+ECMAScript semantics (see <<Function Subtyping>>).
+
+
+=== Generics
+
+The most important concept (taken more or less 1:1 from Java) is generics. There are a lot of languages providing support for
+generics. Often there is limited support compared to Java, or different concepts are used. There are languages, for example,
+which support generic types but not generic functions, or do not support wildcards. Languages such as Scala, for instance, have
+different concepts for generics.
+
+
+N4JS provides all features related to generics as Java does. Supported are:
+
+
+* generic types and generic methods (and functions)
+* type variables with lower bounds
+* parameterization with wildcards (and upper and lower bounds)
+
+
+N4JS even uses the very same https://docs.oracle.com/javase/specs/jls/se8/html/jls-18.html[algorithm to infer type
+variables as Java 8]. This algorithm is, of course, slightly adapted to support extra features of N4JS such as union types.
+
+
+As a consequence, generics and parameterization should immediately be understood by Java programmers (as far as 'immediately
+understood' can be applied to generics).
+
+
+At the moment, the N4JS type system has some known issues when substituting type variables and instantiating wildcard
+expressions. For the latter, Java uses a technique called "capture conversion" while N4JS implements a slightly simpler
+one called "existential types". Future releases of N4JS will fix these issues.
+
+=== Interfaces and Abstract Declarations
+
+
+ECMAScript 2015 introduces classes similar to Java. In both languages, single inheritance is used. Although this simplifies
+ many scenarios, the limitations of single inheritance are often problematic. In Java, many of these problematic cases can
+be solved with interfaces. N4JS also provides the concept of interfaces, allowing for classes to implement multiple interfaces.
+ Interfaces in N4JS allow for the definition of default methods as in Java 8, therefore overcoming most of the problems
+introduced by single inheritance. Related to interfaces are abstract methods and, consequently, abstract classes which are
+also supported in N4JS similarly to Java.
+
+
+N4JS adapts the `instanceof` operator so it can be used in combination with interfaces at runtime.
+
+=== Access Modifiers
+
+
+When designing larger systems and frameworks, limiting access to certain elements is important for maintainability. Similar
+to Java, N4JS introduces access modifiers to limit visibility of types and members. The following table shows the access
+modifiers of N4JS compared to Java:
+
+
+|=======================
+^|*Java* ^|*N4JS* 2+| *Remark*
+2+^|Public 2+| Types and members, similar semantic
+2+^|Protected 2+| Members only, similar semantic
+^|Package
+^|Project 2+| See below
+|private
+|members only, similar semantic
+|=======================
+
+While it is possible to organize modules in folders which could be interpreted as packages, N4JS does not really support the
+notion of packages. Instead, it uses projects to encapsulate coherent functionality. Project is the default visibility in
+N4JS as package is in Java. The semantics are also similar in both cases: elements (types or members) can only be accessed
+from the same container (project in N4JS and package in Java).
+
+
+== Differences
+
+=== Auto-Boxing
+
+In Java, primitive types can be auto-boxed to their corresponding object types (and vice versa). This is also true for
+ECMAScript but there are subtle differences which might lead to misconceptions as shown in the following example:
+
+
+[source,n4js]
+----
+let bool: boolean = false;
+let Bool: Boolean = new Boolean( false );
+
+console.log( bool.valueOf(), bool ? "true" : "false");
+console.log( Bool.valueOf(), Bool ? "true" : "false");
+----
+
+
+Probably surprising for Java programmers, this would print out
+
+
+[source,n4js]
+false 'false'
+false 'true'
+
+In order avoid these problems, N4JS does not support auto-boxing. Instead, primitives and object types have to be
+explicitly converted using either the `constructor`, `Object.valueof` or other related methods.
+
+
+=== Function Subtyping
+
+Function (or method) subtyping comes into play in two cases: method overriding and passing functions as arguments
+(callbacks, for example). In both cases, the type checker has to ensure that a function `*f*` is compatible with
+another function `*f'*` (in other words, that the type of `*f*` is a subtype of the type of `*f'*`). In Java this is called
+"override compatible".
+
+In Java, a method `*f*` is override compatible to a `*f'*` if and only if
+
+. it has the same name
+. it has the same number of parameters
+. the type of each parameter of `*f*` must be a supertype of the corresponding parameter of `*f'*`
+. its return type is a subtype of the return type of `*f'*`
+
+In ECMAScript, it is possible to call a function of a method with more or less arguments than declared
+formal parameters. Calling a function with less arguments is not allowed in N4JS (unless the parameters
+are declared as optional). The definition of "override compatible" is, therefore, a little bit different
+in N4JS.
+
+In N4JS,`*f'*` is override comptabible to `*f*` (or its type is a subtype of the type of `*f*`), if
+
+. it has the same name (in case of method override)
+. it has the same number or less of parameters, or superfluous parameters are optional
+. the type of each parameter of `*f'*` must be a subtype of the corresponding parameter of `*f*`
+. its return type is a subtype of the return type of `*f*` , or `*f*` has no return type (it's void).
+
+For example, the following code is correct in N4JS while it would cause compile errors in Java:
+
+[source,n4js]
+class A {
+ foo(s: string): void {}
+}
+class B extends A {
+ @Override
+ foo(): number { return 0 }
+}
+
+
+=== Overloading
+
+
+There is no method overloading in ECMAScript and therefore there cannot be overloading in N4JS. In order to 'emulate'
+overloading to a certain degree, union types and optional parameters can be used.
+
+
+=== Static Members
+
+In Java, a static member of a class can be accessed either
+
+
+
+. via the declaring class (or a subclass)
+. via an instance
+
+
+In N4JS, a static member can only be called via the declaring class.
+
+
+Note that the `this` literal is bound to the class (to the constructor function, in fact). This enables
+static polymorphism as shown in the next example:
+
+
+[source,n4js]
+----
+class A {
+ public static s() { console.log("A.s"); this.t(); };
+ public static t() { console.log("A.t"); };
+}
+class B extends A {
+ @Override
+ public static t() { console.log("B.t"); };
+}
+
+A.s();
+B.s();
+----
+
+This will print out
+
+
+[source]
+A.s
+A.t
+A.s
+B.t
+
+The last line in particular may be surprising for Java programmers.
diff --git a/src/faq/comparison-typescript.adoc b/src/faq/comparison-typescript.adoc
new file mode 100644
index 0000000..5ec4ddd
--- /dev/null
+++ b/src/faq/comparison-typescript.adoc
@@ -0,0 +1,425 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+
+
+.N4JS and TypeScript
+= N4JS and TypeScript
+:doctype: book
+:notitle:
+:toc: right
+
+[.faq-intro]
+N4JS and TypeScript are both supersets of ECMAScript. They both introduce type annotations and a
+static type checker. However, in their relation to JavaScript, they follow different approaches.
+
+image::images/ts_n4js.svg[]
+
+TypeScript tries to make ECMAScript type-safe without invalidating existing ECMAScript code. Its
+type system is optional and the TypeScript transpiler aims to accept plain ECMAScript wherever as possible.
+
+Although N4JS is a superset of ECMAScript in terms of syntax and features, it does not
+try to be compatible with ECMAScript at all cost.
+One way of looking at the N4JS approach is to begin with ECMAScript, add Java's strict
+and rigorous type system and then to make this amalgamation as flexible as possible.
+The idea is that this fulfills the expectations of JavaScript programmers while keeping the type system sound.
+
+[.language-n4js]
+== Differences
+
+In many cases TypeScript's design prioritizes the transition from ECMAScript to TypeScript
+over type safety. N4JS was designed with ease of transition in mind, but type safety has a higher
+priority than the ease of transition.
+
+=== Any
+
+Both languages introduce a type called `any`.
+However, the precise meaning of `any` is probably the most important difference between N4JS and TypeScript.
+Simply put:
+
+**In N4JS you can do *nothing* with `any`, in TypeScript you can do anything.**
+
+The following example illustrates the difference:
+
+[source,n4js]
+----
+function f(p: any) {
+ p.foo(); // error in N4JS, no error in TypeScript
+}
+----
+
+N4JS will issue an error: `Couldn't resolve reference to IdentifiableElement 'foo'`, because in N4JS, the type `any`
+has no properties.
+
+Furthermore, in N4JS `any` is the top type: every type is a subtype of `any`. In TypeScript it is treated as a bottom
+type similar to `undefined` (or `null`): `any` is a subtype of every other type. The effect of these different semantics is shown in the following example:
+
+[source,n4js]
+----
+function bar(p: string) {
+ p.charAt(0);
+}
+
+var s: string = "Hello";
+var x: any = 42;
+
+bar(s);
+bar(x); // error in N4JS, no error in TypeScript
+----
+
+Of course, you would get an error at runtime: `TypeError: p.charAt is not a function`
+
+The differing interpretations of `any` reflect the different approaches visualized in the figure at the beginning.
+`any` in TypeScript is JavaScript in pure form: access anything, assign to everything. `any` in N4JS is even more rigorous than type `Object` in Java: access nothing, assign to nothing (except `any` itself).
+
+////
+It also illustrates how both languages are moving closer to each other: The better the type inferencer is and the more alternative concepts are provided, the less often any is to be used.
+With the introduction of union types for instance, the usage of any has been reduced in TypeScript and N4JS.
+Another example is "this" type, introduced with TypeScript 1.8 and also available in N4JS; it also makes some usages of any expandable.
+////
+
+N4JS allows developers to use types in dynamic way, by using the `+` type modifier.
+This so-called *dynamic type modifier* allows for accessing arbitrary properties even when they are not known to the type system. The following example shows the effect:
+
+[source,n4js]
+----
+function f(p: any, d: any+) {
+ p.foo(); // error in N4JS
+ d.foo(); // no error in N4JS, as `d` is "dynamic"
+}
+----
+
+While `any+` resembles TypeScript's behavior of `any`, it is still more restrictive: `any+` will never be used as a default, it has to be declared explicitly; and a value of type `any+` still cannot be assigned to variables of other types except `any`.
+
+|===
+2+| h| access anything h| assign to everything h| used as default
+.2+h| N4JS h| `any` h| no h| no | •
+h| `any+` h| yes h| no |
+h| TypeScript h| `any` h| yes h| yes | • footnote:[In TypeScript, implicit usage of `any` can be disallowed by means of a compiler flag.]
+|===
+
+TypeScript 3 introduced the `unknown` type which behaves like N4JS's `any` type, with the exception that it isn't currently being used by default and has to be declared explicitly.
+
+=== Type Errors Are Show-Stoppers in N4JS
+
+N4JS has two general levels of issues reported by the compiler: *warning* and *error*.
+Serious issues like type errors are treated as errors in N4JS and all errors will prevent the transpiler to emit any JavaScript code in order to avoid producing code that might cause exceptions at runtime.
+For TypeScript, on the other hand, it is a main concern to never impede the developer, the transpiler will thus produce JavaScript output code even in the case of compile errors.
+Given the example from the beginning
+
+[source,n4js]
+----
+var str = 'Hello';
+str = 42; // <1>
+str.charAt(2);
+----
+<1> Both N4JS and TypeScript show an error here.
+
+The N4JS transpiler will reject the compilation of that code, while TypeScript will create a JavaScript output file
+that causes exceptions at runtime in the last line.
+
+=== Parameter Contra-variance vs. Bivariance
+
+In N4JS, when overriding a method in a subtype, the types of the parameters may be super types, and the return type may be a sub type.
+Compare this to Java, where the return type may also be a sub type, but the parameter types must be the same.
+Given the following classes
+
+[source,java]
+----
+class A { fa() {} }
+class B extends A { fb() {} }
+class C extends B { fc() {} }
+----
+
+and the following super type
+
+[source,java]
+----
+class Sup {
+ f(b: B): B { return new B() }
+}
+----
+
+a sub type of `Sup` may override `f` as follows:
+
+[source,java]
+----
+class Sub extends Sup {
+ @Override
+ f(a: A): C { return new C() }
+}
+----
+
+In type theory, this is expressed with co- and contra-variance: Given a type `Sup` with a method `M`, and a subtype of `Sub` with a method `N` overriding `M` (that is, `M` and `N` have the same names), then:
+
+* the parameter types of overriding methods need to be contra-variant - the type of the parameters of `N` need to be super types footnote:[Super and sub type relation is reflexive here.] of the types of the parameters of `M`
+* the return type of overriding methods need to be co-variant, that is the type of the parameters of `N` need to be a sub type of the return type of `M`
+
+The same is true when checking assignability for function types, e.g.
+
+[source,java]
+----
+f(callback: (B)=>B) {}
+----
+
+can be called with
+
+[source,java]
+----
+f((a: A) => return new C())
+----
+
+In Typescript, the parameter types may be contra- or covariant, that is bivariant (see http://www.typescriptlang.org/docs/handbook/type-compatibility.html#function-parameter-bivariance[Handbook] and https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md#3.11.4[TypeScript Spec, Assignment Compatibility] and https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md#8.2.3[Inheritance and Overriding]).
+
+This is *unsound*, as already stated in the TypeScript (http://www.typescriptlang.org/docs/handbook/type-compatibility.html#function-parameter-bivariance[Handbook]):
+
+[quote,TypeScript Handbook]
+This is unsound because a caller might end up being given a function that takes a more specialized type, but invokes the function with a less specialized type.
+
+In the context of function objects (as in the example with the callback parameter) this may be quite convenient. And for that very special use case, we agree with the TS handbook:
+
+[quote,TypeScript Handbook]
+In practice, this sort of error is rare, and allowing this enables many common JavaScript patterns.
+
+However, in the context of overriding methods and generics, this leads to severe problems, which are probably not that "rare".
+
+==== Violated Substitution Principle
+
+This assumed bivariance actually violates the so called https://en.wikipedia.org/wiki/Liskov_substitution_principle[subsitution principle]. In TypeScript, the following code is accepted without errors or warnings:
+
+[source,java]
+----
+class TSSub extends Sup {
+ f(b: C): B { b.fc(); return new B() }
+}
+----
+
+The following function uses the super class `Sup` and assumes that its method `f` accepts a parameter of type `B`.
+
+[source,java]
+----
+function g(s: Sup) {
+ let b = s.f(new B());
+}
+----
+
+The substitution principles states that we can use a subclass instead of the super class.
+However, this is not true in case of TypeScript anymore.
+The following code will create a runtime error:
+
+[source,java]
+----
+f(new TSSub());
+----
+
+This will be surprising for the programmer of that call, but also for the developer of function `g`.
+
+==== Use-Site Variance vs. Assumed Co-Variance
+
+Parameter bivariance seems to solve some variance problems in the context of generics.
+Let's have a look at the hello-world example for generics, a simplified list that can hold only a single element:
+
+[source,java]
+----
+class List<T> {
+ read(): T { /* .. */ }
+ write(T) { /* .. */ }
+}
+----
+
+and two variables
+
+[source,java]
+----
+let la: List<A>(), lb: List<B>;
+----
+
+Programmers familiar with Java or Scala know that it often causes headaches when using generics and assigning instances of generics.
+Take the following assignments for example:
+
+[source,java]
+----
+la = lb; // <1>
+lb = la; // <2>
+----
+<1> This works in TypeScript. N4JS (and Java) issue an error
+<2> Both TypeScript and N4JS (and Java) issue an error
+
+On first glance, it looks great that TypeScript does not issue any errors here.
+Since it's not obvious why both assignments are rejected by N4JS, let's have a look at what happens next:
+
+[source,java]
+----
+la = new List<A>(); la.write(a); lb = la; lb.read().fb();
+----
+
+TypeScript would issue no errors, but we would get a runtime error in the last call:
+since the list does not contain an instance of `B`, the method is undefined.
+The same error occurs in the following case:
+
+[source,java]
+----
+lb = new List<B>(); la = lb; la.write(a); lb.read().fb());
+----
+
+This is true because `List<T>` is invariant (that it is neither co- nor contra-variant):
+* List is not co-variant: Even if `B` is a subtype of `A`, `List<B>` is not a subtype of `List<A>`
+* List is not contra-variant: Even if `B` is a subtype of `A`, `List<B>` is not a supertype of `List<A>`
+
+In practice, this is very inconvenient.
+It would be O.K. to use `lb` instead of `la` assuming we only want to read from the list.
+On the other hand, if we only want to write to the list then we could use `la` instead of `lb` since adding `B` s to a list expecting `A` does not do any harm.
+There are different solutions to the same problem.
+
+Java uses use-site variance, and this is also supported by N4JS.
+When the list is used, we can define whether we want to read or write from it.
+This can be done by using so-called 'wildcards' and constraints when parameterizing the list, for example:
+
+[source,n4js]
+----
+function copy(readOnlyList: List<? extends A>, writeOnlyList: List<? super A>) {
+ writeOnlyList.write( readOnlyList.read() );
+}
+----
+
+Scala uses def-site variance, which is also supported by N4JS. In that case, you define at the definition of a generic type that a type variable is only used for read or write. E.g.,
+
+[source,n4js]
+----
+interface ReadOnlyList<out T> {
+ read(): T
+}
+interface WriteOnlyList<in T> {
+ write(T): void
+}
+
+class List <T> implements ReadOnlyList<T>, WriteOnlyList<T> {
+ @Override
+ read(): T { /* .. */ return null;}
+ @Override
+ write(T) { /* .. */ }
+}
+
+function copy(readOnlyList: ReadOnlyList<A>, writeOnlyList: WriteOnlyList<A>) {
+ writeOnlyList.write( readOnlyList.read() );
+}
+----
+
+For more information on generics, please refer to the link:../features/generics.html[generics feature page].
+
+== Similarities
+
+=== Explicit and Implicit typing
+
+In both languages, types can either be defined explicitly (via a type annotation) or implicitly.
+In the latter case, the type is to be inferred by the type system. A simple example is the assignment
+of a value to a newly declared variable, such as
+
+[source,n4js]
+let foo = "Hello";
+
+Both languages would infer the type of `foo` to `string`.
+In both languages the following assignment would, therefore, lead to an error:
+
+[source,n4js]
+foo = 42; // error
+
+* N4JS would issue `int is not a subtype of string.`,
+* TypeScript would issue ``Type `number` is not assignable to type `string```
+
+=== Structural Types
+
+N4JS and TypeScript both support <<../features/nominal-and-structural-typing#nominal_and_structural_typing,structural types>>.
+This allows for managing relations between types without the need for excessive declarations.
+Instead of explicitly defining type relations via `extends` or `implements`, the type system compares the properties of two types.
+If one type has all the properties of another type, it is considered to be a subtype.
+
+As a significant difference between the two languages, N4JS also supports **nominal types** and nominal typing **is the default**.
+Thus, structural types have to be explicitly annotated as being structural, using the `pass:[~]` or `pass:[~~]` type constructors.
+
+[cols="1a,1a"]
+|===
+^|N4JS ^|JavaScript
+
+|
+[source,n4js]
+----
+export public interface~Point {
+ x: number;
+ y: number;
+}
+export public interface~Point3D {
+ x: number;
+ y: number;
+ z: number;
+}
+var p: Point = {
+ x: 0,
+ y: 10,
+};
+var p3d: Point3D = {
+ x: 0,
+ y: 10,
+ z: 20
+}
+
+p = p3d;
+p3d = p; // error
+----
+
+|
+
+[source,javascript]
+----
+interface Point {
+ x: number;
+ y: number;
+}
+interface Point3D {
+ x: number;
+ y: number;
+ z: number;
+}
+var p: Point = {
+ x: 0,
+ y: 10,
+};
+var p3d: Point3D = {
+ x: 0,
+ y: 10,
+ z: 20
+}
+
+p = p3d;
+p3d = p; // error
+----
+|===
+
+NOTE: N4JS is using different defaults for access modifiers, e.g. `public` is not the default. For that reason, the interfaces have to be marked as public (and exported).
+
+In both languages, an error will be issued on the last line:
+
+N4JS:: `Point is not a structural subtype of Point3D: missing field z.`
+Typescript:: `Type 'Point' is not assignable to Type 'Point3D'. Property 'z' is missing in type 'Point'.`
+
+The difference between structural and nominal typing is described in further detail in the <<features/nominal-vs-structural-typing.html#nominal_vs_structural_typing,nominal vs. structural subtyping feature>>.
+
+=== Using Existing JavaScript Libraries
+
+An important aspect of being an ECMAScript superset is to enable developers to use existing JavaScript libraries. N4JS and
+TypeScript support type definitions for existing code. For TypeScript, there is a great project called
+http://definitelytyped.org/[DefinitelyTyped] where type definitions are collected. For
+N4JS, a similar https://github.com/NumberFour/n4jsd[GitHub project] exists, but it contains
+very few definitions at the moment. Contributions are welcome for both projects.
+
+It is also possible to use existing code in both languages without type definitions, Common.js modules in particular.
+The N4JS IDE <<../features/nodejs-support#nodejs-support,integrates support for NPM>>, so that these modules, even without a
+type definition, can seamlessly be used in N4JS.
diff --git a/src/faq/images/ts_n4js.graffle b/src/faq/images/ts_n4js.graffle
new file mode 100644
index 0000000..5a0c251
--- /dev/null
+++ b/src/faq/images/ts_n4js.graffle
Binary files differ
diff --git a/src/faq/images/ts_n4js.svg b/src/faq/images/ts_n4js.svg
new file mode 100644
index 0000000..a8c0cfc
--- /dev/null
+++ b/src/faq/images/ts_n4js.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="33 26 342 108" width="342pt" height="9pc" xmlns:dc="http://purl.org/dc/elements/1.1/"><metadata> Produced by OmniGraffle 6.5.1 <dc:date>2016-03-10 19:49:38 +0000</dc:date></metadata><defs><font-face font-family="Helvetica Neue" font-size="10" panose-1="2 0 5 3 0 0 0 2 0 4" units-per-em="1000" underline-position="-100" underline-thickness="50" slope="0" x-height="517" cap-height="714" ascent="951.99585" descent="-212.99744" font-weight="500"><font-face-src><font-face-name name="HelveticaNeue"/></font-face-src></font-face><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="SharpArrow_Marker" viewBox="-4 -4 10 8" markerWidth="10" markerHeight="8" color="black"><g><path d="M 5 0 L -3 -3 L 0 0 L 0 0 L -3 3 Z" fill="currentColor" stroke="currentColor" stroke-width="1"/></g></marker><font-face font-family="Helvetica Neue" font-size="11" panose-1="2 0 5 3 0 0 0 2 0 4" units-per-em="1000" underline-position="-100" underline-thickness="50" slope="0" x-height="517" cap-height="714" ascent="951.99585" descent="-212.99744" font-weight="500"><font-face-src><font-face-name name="HelveticaNeue"/></font-face-src></font-face></defs><g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"><title>Canvas 1</title><rect fill="white" width="1378" height="1056"/><g><title>Layer 1</title><path d="M 206.07873 87.726065 L 119.00849 76.537743 C 125.1961 65.463526 140.30372 56.021646 161.00786 50.28921 Z" fill="white"/><path d="M 206.07873 87.726065 L 119.00849 76.537743 C 125.1961 65.463526 140.30372 56.021646 161.00786 50.28921 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="4"/><path d="M 206.07873 87.726065 L 251.1496 50.28921 C 294.26373 62.22639 309.03573 88.66444 284.14377 109.340244 C 259.25182 130.01605 204.12199 137.1001 161.00786 125.16292 C 140.30372 119.430484 125.1961 109.988604 119.00849 98.91439 Z" fill="white"/><path d="M 206.07873 87.726065 L 251.1496 50.28921 C 294.26373 62.22639 309.03573 88.66444 284.14377 109.340244 C 259.25182 130.01605 204.12199 137.1001 161.00786 125.16292 C 140.30372 119.430484 125.1961 109.988604 119.00849 98.91439 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="4"/><text transform="translate(227.51969 29.573421)" fill="black"><tspan font-family="Helvetica Neue" font-size="10" font-weight="500" x="1.8076211" y="10" textLength="24.45">N4JS</tspan></text><text transform="translate(145.14961 29.573421)" fill="black"><tspan font-family="Helvetica Neue" font-size="10" font-weight="500" x=".295" y="10" textLength="5.74">T</tspan><tspan font-family="Helvetica Neue" font-size="10" font-weight="500" x="4.925" y="10" textLength="42.78">ypeScript</tspan></text><ellipse cx="206.07873" cy="87.726065" rx="90.141843" ry="43.228405" fill="white"/><line x1="249.3622" y1="48.922655" x2="249.21071" y2="48.8538" marker-end="url(#SharpArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><line x1="159.95794" y1="48.922655" x2="164.64651" y2="47.717053" marker-end="url(#SharpArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(84.03937 81.586066)" fill="black"><tspan font-family="Helvetica Neue" font-size="10" font-weight="500" x="0" y="10" textLength="55">ECMAScript</tspan></text><text transform="translate(301.22048 81.586066)" fill="black"><tspan font-family="Helvetica Neue" font-size="10" font-weight="500" x="3.567621" y="10" textLength="20.93">Java</tspan></text><text transform="translate(33.015748 75.418066)" fill="black"><tspan font-family="Helvetica Neue" font-size="11" font-weight="500" x=".111" y="10" textLength="41.778">dynamic</tspan><tspan font-family="Helvetica Neue" font-size="11" font-weight="500" x="3.6915" y="22.307999" textLength="5.698">fl</tspan><tspan font-family="Helvetica Neue" font-size="11" font-weight="500" x="9.3895" y="22.307999" textLength="28.919">exible</tspan></text><text transform="translate(333.28572 75.418066)" fill="black"><tspan font-family="Helvetica Neue" font-size="11" font-weight="500" x="7.157" y="10" textLength="26.686">static</tspan><tspan font-family="Helvetica Neue" font-size="11" font-weight="500" x=".436" y="22.307999" textLength="22.396">rigor</tspan><tspan font-family="Helvetica Neue" font-size="11" font-weight="500" x="22.634" y="22.307999" textLength="17.93">ous</tspan></text></g></g></svg>
diff --git a/src/faq/index.adoc b/src/faq/index.adoc
new file mode 100644
index 0000000..fafed29
--- /dev/null
+++ b/src/faq/index.adoc
@@ -0,0 +1,72 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+
+.FAQ
+= FAQ
+:doctype: book
+:notitle:
+:toc: right
+
+
+== Why Did You Create N4JS?
+
+
+N4JS is created by http://www.numberfour.eu[NumberFour AG]. Our goal is to create a single
+business platform on which apps can be installed and run. These apps are written in N4JS which is based
+on JavaScript/ECMAScript.
+
+JavaScript is the best language for external developers to contribute to our platform but we needed
+important features to build large, reliable systems that are maintainable over time. What we needed was
+a sound type system and that's why we developed N4JS to provide these missing features.
+
+== Why Do You Open-Source N4JS?
+
+We stand on the shoulders of open technology and it's our turn to give back. We see the strength of N4JS
+not only for our own platform but as a foundation for others to build upon. This is why we release N4JS
+as open-source. We are excited for feedback and always open for contributions!
+
+== How does N4JS compare to JavaScript/ECMAScript?
+
+
+N4JS is based on JavaScript/ECMAScript. Feature-wise it is a super set of ECMAScript: It supports all
+constructs known from JavaScript and most features from ECMAScript 2015 (missing features are to be
+added soon). Since it provides a static type checker, the transpiler may find errors in given n4js
+files containing plain JavaScript code. It would then reject the compilation to JavaScript and issue
+errors instead. In the N4JS IDE, you can also edit plain JavaScript. In that case, the type checker
+won't issue any errors but will probably lead to runtime errors.
+
+== How does N4JS compare to Java?
+
+
+N4JS is an extension of ECMAScript making it is as different from Java as ECMAScript itself. N4JS does
+add features which are quite similar to Java and the general idea is to make ECMAScript as type safe as
+Java. For that reason, N4JS adds a static type system to ECMAScript, many concepts of which are similar
+to Java's type system.
+
+We explain the <<comparison-java#comparison_java,differences and similarities between N4JS and Java on an
+extra page>>.
+
+== How does N4JS compare to TypeScript?
+
+We created N4JS with the goal to enable writing large ECMAScript projects that are as maintainable as
+Java. To do this, we took the Java type system and adjusted it to ECMAScript's characteristics. The N4JS
+type checker is rigorous: type errors are not accepted. Where TypeScript also adds a static type system
+on top of ECMAScript, their approach is quite the opposite in that their goal is to enable a smooth
+transition from untyped to typed ECMAScript. The type checker in TypeScript makes some compromises in order
+to accept more ECMAScript code.
+
+Eventually both approaches will lead to similar solutions: The smarter and better the type checker
+of N4JS becomes, the more programs it will accept without losing its soundness. The smarter and better
+TypeScript's type checker becomes, the less gaps there will be for incorrect ECMAScript code.
+
+For a thorough explanation of the <<comparison-typescript#_comparison_typescript,differences and similarities
+between N4JS and TypeScript>> see our comparison page.
diff --git a/src/features/async-await.adoc b/src/features/async-await.adoc
new file mode 100644
index 0000000..a840ebc
--- /dev/null
+++ b/src/features/async-await.adoc
@@ -0,0 +1,175 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+.Async/Await
+= Async/Await
+:doctype: book
+:toc: right
+
+
+Due to the event-driven nature inherent in JavaScript, asynchronous code has
+always been explicit and verbose, leading to projects which are hard to read and maintain.
+N4JS already implements the async/await proposal and it provides additional features allowing
+the use of legacy code in combination with await and promises.
+
+Over the years, growing trends have been to migrate from
+simple callbacks to Promise objects which is making the chaining of asynchronous data
+flows easier. This still urges the developer to implement callbacks on
+the resolution of a Promise.
+
+
+N4JS implements a new approach proposed by TC39 on https://tc39.github.io/ecmascript-asyncawait/[async functions]
+to tackle the problem. It conceals the drawn-out details and formal approach so that a
+developer would have less code to write. A function or method can essentially become an
+**asynchronous** function by prepending the keyword `async`.
+Inside the function, the developer can call other functions and wait for their
+results using the keyword `async`:
+
+[source,n4js]
+----
+async function foo(): int {
+ let res = await anotherAsyncFunction();
+ ++res;
+ return res;
+}
+----
+
+The benefit here is that async functions integrate well with any existing
+Promise-based APIs, i.e. N4JS treats any return type **T** of an async method
+or function as a **Promise<T, any>**.
+
+On the other hand, async code can simply await on functions that return a Promise
+object:
+
+[source,n4js]
+----
+function fetch(url: string): Promise<Response, any> {
+ // WHATWG fetch
+ return null;
+}
+
+async function foo() {
+ let html = await (await fetch('http://www.google.com')).text();
+ console.log(html);
+}
+----
+
+== Error Handling
+
+Since there's a one-to-one mapping to Promises, exceptions being thrown within
+an async function call are rejecting the corresponding Promise:
+
+[source,n4js]
+----
+function throwr() { return Promise.reject(new Error('bah!')); }
+
+async function foo() {
+ try {
+ await throwr();
+ } catch (err) {
+ (err as Error).message === 'bah!';
+ }
+}
+----
+
+
+A rejected Promise will be reflected as an exception being thrown in the
+async function:
+
+
+[source,n4js]
+----
+async function throwr() { throw new Error('bah!'); }
+let promise: Promise<void, ?> = throwr();
+
+promise.catch(err => (err as Error).message === 'bah!');
+----
+
+== "await" for Legacy Code
+
+There's quite a lot of callback-driven code alive that is not returning Promises,
+especially with reference to Node.js core modules:
+
+
+[source,n4js]
+----
+import * as fs from 'fs';
+
+fs.readFile('myFile.txt', (err, content) => {
+ if (err) throw err;
+ console.log(content);
+})
+----
+
+
+This code follows the general Node.js callback pattern of passing the error as
+a first argument following the result value(s).
+
+
+Since N4JS encourages you to use and define types where possible, we can do
+better here, too. N4JS allows to use the **@Promisifiable** annotation in this
+case (and actually the Node.js runtime definitions provided by N4JS already make use of it):
+
+[source,n4js]
+----
+@Promisifiable
+export external public function readFile(
+ filename: string,
+ options: ~Object with {encoding: string?; flag: string?;},
+ callback: {function(Error, string)}?): void;
+----
+
+
+This allows to call the function without implementing any callback, and let the
+transpiler wire up a Promise for you using the **@Promisify** annotation:
+
+[source,n4js]
+----
+import { readFile } from 'fs';
+
+function foo(): Promise<string, any> {
+ var promise = @Promisify readFile('myFile.txt', { encoding: 'UTF-8' });
+ return promise.then(content => content.replace(/foo/g, 'bar'));
+}
+----
+
+Since promises integrate with async functions, we could even further
+condense this down:
+
+[source,n4js]
+----
+import { readFile } from 'fs';
+
+async function foo(): string {
+ var content = await readFile('myFile.txt', { encoding: 'UTF-8' });
+ return content.replace(/foo/g, 'bar');
+}
+----
+
+
+Finally, it's noteworthy to mention that arrow functions can work asynchronously as well,
+which is particularly helpful. The following example demonstrates how we can easily test async
+code to throw an error using an async arrow expression in the context of the N4JS test framework "mangelhaft".
+
+[source,n4js]
+----
+import { Assert } from 'n4/mangel/assert/Assert';
+
+export public class FooTest {
+
+ @Test async myTest() {
+ await Assert.throwsAsync(async () => {
+ // async piece of code that is throwing an error
+ });
+ }
+
+}
+----
diff --git a/src/features/dependency-injection.adoc b/src/features/dependency-injection.adoc
new file mode 100644
index 0000000..f7f714d
--- /dev/null
+++ b/src/features/dependency-injection.adoc
@@ -0,0 +1,231 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+.Dependency Injection in N4JS
+= Dependency Injection in N4JS
+:doctype: book
+:toc: right
+
+
+Dependency injection (DI) is a concept that allows for configuring dependencies
+between classes at a central location. Instead of passing dependencies from class to class, N4JS' built-in
+DI support does this automatically.
+
+
+This makes the user code much cleaner, easier to maintain and also improves
+its testability. N4JS DI framework follows Java JSR-330/Google Guice, making its usage easy for Java developers.
+
+== Application Object Graph
+
+In object oriented languages, applications are composed from objects that interact with each other. Instances
+of those objects need to be created and wired together on application startup to create a so-called object
+graph of the application. While it's possible to manually create this object graph, it quickly becomes
+complicated. This is especially so if we want flexibility and reconfigurability to be long-lasting features
+of our application.
+
+Solutions for manually wiring the object graph come with their distinct disadvantages:
+
+
+* Hard coding dependencies makes code inflexible and complicate testing.
+* Passing dependencies to constructors bloats the constructors.
+* Using factories requires passing the factory and also bloats the code.
+
+== Dependency Injection (DI)
+
+Dependency injection (DI) and DI frameworks aim to help with issues described before, specifically with the
+following:
+
+
+* The object graph is created automatically which removes burden of writing object factories.
+* Injection of the created instances is done behind the scenes where needed, which separates object-creation
+from object-usage and keeps constructors simple.
+* The application's configuration can be changed without changing its components.
+
+
+N4JS provides built-in support for dependency injection using a lightweight syntax with annotation similar to
+Java https://jcp.org/en/jsr/detail?id=330[JSR-330] / https://github.com/google/guice[Google Guice].
+The N4JS testing framework also supports dependency injection which allows for special test settings in order to test components individually.
+
+== Example
+
+In the following example, two versions of a simple weather application are implemented. Both versions use a
+module WeatherEngine which returns the temperature for a given city. For this example, we use a timeout to
+emulate a real request to a weather server:
+
+
+[source,n4js]
+----
+export public class WeatherEngine {
+ data = [ {city: 'Berlin', temp: 5}, {city: 'Hamburg', temp: 15}, {city: 'Palo Alto', temp: 10} ];
+
+ public temperature(city: string): Promise<number, ?> {
+ return new Promise<number, any>(
+ (cb: {function(number)}) => {
+ setTimeout(() => cb(this.data.find(e => e.city == city).temp) , Math.random() * 2000);
+ });
+ }
+}
+----
+
+In order to keep the examples as small as possible, in the non-DI version no manual wiring of the dependencies
+is used. The components are instead set up by initializing the fields directly.
+
+[cols="2*"]
+|===
+|**Without Dependency-Injection**
+|**With Dependency-Injection**
+a|
+.WeatherApp.n4js
+[source,n4js]
+----
+import { WeatherEngine } from 'WeatherEngine';
+
+export class WeatherApp {
+ private engine: WeatherEngine = new WeatherEngine();
+
+ async printTemp(city: string): string {
+ return city + ': ' + (await this.engine.temperature(city));
+ }
+}
+
+
+export class Server {
+ weatherApp: WeatherApp = new WeatherApp();
+
+ async run() {
+ for (var s of ['Berlin', 'Hamburg', 'Palo Alto']) {
+ console.log(await this.weatherApp.printTemp(s));
+ }
+ }
+}
+----
+
+a|
+.WeatherAppDI.n4js
+[source,n4js]
+----
+import { WeatherEngine } from 'WeatherEngine';
+
+export class WeatherApp {
+ @Inject private engine: WeatherEngine;
+
+ async printTemp(city: string): string {
+ return city + ': ' + (await this.engine.temperature(city));
+ }
+}
+
+@GenerateInjector
+export class Server {
+ @Inject weatherApp: WeatherApp;
+
+ async run() {
+ for (var s of ['Berlin', 'Hamburg', 'Palo Alto']) {
+ console.log(await this.weatherApp.printTemp(s));
+ }
+ }
+}
+----
+
+a|
+.Starter.n4js
+[source,n4js]
+----
+import { Server } from 'WeatherApp'
+
+
+var server = new Server();
+server.run();
+----
+
+
+a|
+.StarterDI.n4js
+[source,n4js]
+----
+import { Server } from 'WeatherAppDI';
+import { N4Injector } from 'n4js/lang/N4Injector';
+
+var server = N4Injector.of(Server).create(Server);
+server.run();
+----
+|===
+The changes are only minimal: Instead of creating the field instances directly, they are annotated
+with `@Inject`. This should be familiar to Java programmers having used Google Guice.
+
+An interesting aspect of dependency injection is how to set up the injector. In N4JS, the
+annotation `@GenerateInjector` is used in order mark a class as a dependency
+injection component. In other words, to associate an injector with the class. Running the server now
+requires slightly different instantiation. Instead of constructing the server with `new`,
+the built-in class `N4Injector` is used to create the first instance.
+
+
+== Application Reconfigurability
+
+
+A very useful quality of DI is its flexibility. This is particularly beneficial during testing. Let's
+write a test class for our `WeatherApp`. We do not want to wait an arbitrary amount of
+seconds to receive the results of our test, we want to use a special version of the `WeatherEngine`
+which immediately returns a value. Let's have a look at the test module:
+
+
+[source,n4js,numbered]
+----
+import { WeatherApp } from 'WeatherAppDI';
+import { WeatherEngine } from 'WeatherEngine';
+import { Assert } from 'n4/mangel/assert/Assert';
+
+class WeatherEngineMock extends WeatherEngine { // <1>
+ @Override
+ public async temperature(city: string): number {
+ return 1;
+ }
+}
+
+@Binder // <2>
+@Bind(WeatherEngine, WeatherEngineMock)
+class WeatherAppTestConfig{ }
+
+@GenerateInjector() <3>
+@UseBinder(WeatherAppTestConfig) <4>
+export class WeatherAppTest {
+ @Inject weatherApp: WeatherApp;
+
+ @Test public async test() {
+ Assert.equal(await this.weatherApp.printTemp('Berlin'), 'Berlin: 1');
+ }
+}
+----
+
+<1> A mock engine must be written.
+
+<2> Followed by a "binder" which is a configuration telling the injector what type has to be used to instantiate objects. By default, the
+injector uses the same class as referenced in the code. We change this and bind the mock engine to the
+real engine.
+
+<3> As the N4JS test framework already supports DI, we can declare the test as a new dependency injection.
+component.
+
+<4> Specific test configuration. The important point is that the
+class `WeatherApp` now gets the `WeatherEngineMock` injected.
+
+
+
+
+== Advanced features
+
+Specific advantages and extended DI features are discussed in greater detail in the N4JS language
+spec. Some of the most notable features are:
+
+
+* Built-in pseudo-scope via `@Singleton`.
+* Possibility of nesting injectors via `@WithParentInjector`.
+* Built-in `Provider` type and possibility to create custom providers via `@Provides` to dynamically create instances.
+* Automatic resolution of dependency cycles.
diff --git a/src/features/generics.adoc b/src/features/generics.adoc
new file mode 100644
index 0000000..feda1df
--- /dev/null
+++ b/src/features/generics.adoc
@@ -0,0 +1,231 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+
+.Generics
+= Generics
+:doctype: book
+:toc: right
+
+
+Generics in N4JS are a language feature that allows for generic programming. They enable
+a function, class, interface, or method to operate on the values of various (possibly unknown)
+types while preserving compile-time type safety. If you are familiar with Java's generics,
+then N4JS's generics will look familiar as well. There are some differences, however, which we
+shall describe below.
+
+== Motivation
+
+Several language elements may be declared in a generic form; we'll start with focusing on classes,
+generic methods will be discussed after that.
+
+The standard case, of course, is a non-generic class. Take the following class, for example, that
+bundles a pair of two strings:
+
+[source,n4js]
+----
+export public class PairOfString {
+ first: string;
+ second: string;
+}
+----
+
+This implementation is fine as long as all we ever want to store are strings. As experience shows,
+someone is soon to come up with the idea of storing two values of another type, such as... numbers!
+Let's add another class:
+
+[source,n4js]
+----
+export public class PairOfNumber {
+ first: number;
+ second: number;
+}
+----
+
+Following this pattern of adding more classes for new types to be stored obviously has its limitations.
+We would soon end up with a multitude of classes that are basically serving the same purpose, leading to
+code duplication, terrible maintainability and many other problems.
+
+One solution could be having a class that stores two values of type `any` (in N4JS,
+`any` is the so-called 'top type', the common supertype of all other types).
+
+[source,n4js]
+----
+export public class PairOfWhatEver {
+ first: any;
+ second: any;
+}
+----
+
+Now we're worse off than before. We have lost the certainty that within a single pair, both values
+will always be of the same type. When reading a value from a pair, we have no clue what its
+type might be.
+
+== Generic Classes (and Interfaces)
+
+
+
+The way to solve our previous conundrum using generics is to introduce a **type variable** for the class
+We will then call such a class a **generic class**.
+A type variable can then be used within the class declaration just as any other ordinary type.
+
+
+[source,n4js]
+----
+export public class Pair<T> {
+ first: T;
+ second: T;
+}
+----
+
+The type variable `T`, declared after the class name in angle brackets, now represents
+the type of the values stored in the `Pair` and can be used as the type of the two fields.
+
+Now, whenever we refer to the class `Pair`, we will provide a **type argument**, in other words a
+type that will be used wherever the type variable `T` is being used inside the class
+declaration.
+
+[source,n4js]
+----
+import { Pair } from 'Pair';
+
+let myPair = new Pair<string>();
+myPair.first = '1st value';
+myPair.second = '2nd value';
+----
+
+By using a type variable, we have not just allowed any given type to be used as value type,
+we have also stated that both values, first and second, must always be of the same type. We
+have also given the type system a chance to track the types of values stored in a `Pair`:
+
+[source,n4js]
+----
+import { Pair } from 'Pair';
+
+let myPair2 = new Pair<string>();
+myPair2.first = '1st value';
+myPair2.second = 42; // error: 'int is not a subtype of string.'
+
+console.log(myPair2.first.charAt(2));
+// type system will know myPair2.first is of type string
+----
+
+The error in line 3 shows that the type checker will make sure we won't put any value of incorrect
+type into the pair. The fact that we can access method `charAt()` (available on strings)
+in the last line indicates that when we read a value from the pair, the type system knows its type
+and we can use it accordingly.
+
+Generic interfaces can be declared in exactly the same way.
+
+== Generic Functions (and Methods)
+
+With the above, we can now avoid introducing a multitude of classes that are basically serving the
+same purpose. It is still not possible, however, to write code that manipulates such pairs regardless of the type of
+its values may have. For example, a function for swapping the two values of a pair and
+then return the new first value would look like this:
+
+[source,n4js]
+----
+import { PairOfString } from 'PairOfString';
+
+function swapStrings1(pair: PairOfString): string {
+ let backup = pair.first; // inferred type of 'backup' will be string
+ pair.first = pair.second;
+ pair.second = backup;
+ return pair.first;
+}
+----
+
+The above function would have to be copied for every value type to be supported. Using the generic class
+`Pair<T>` does not help much:
+
+[source,n4js]
+----
+import { Pair } from 'Pair';
+
+function swapStrings2(pair: Pair<string>): string {
+ let backup = pair.first; // inferred type of 'backup' will be string
+ pair.first = pair.second;
+ pair.second = backup;
+ return pair.first;
+}
+----
+
+
+The solution is not only to make generic the type being manipulated generic (as we have done with class
+`Pair<T>` above) but to make the code performing the manipulation generic:
+
+
+[source,n4js]
+----
+import { Pair } from 'Pair';
+
+function <T> swap(pair: Pair<T>): T {
+ let backup = pair.first; // inferred type of 'backup' will be T
+ pair.first = pair.second;
+ pair.second = backup;
+ return pair.first;
+}
+----
+
+
+We have introduced a type variable for function `swap()` in much the same way as
+we have done for class `Pair` in the previous section (we then call such a function
+a **generic function**). Similarly, we can use the type variable in this function's signature
+and body.
+
+It is possible to state in the declaration of the function `swap()` above that
+it will return something of type `T` when having obtained a `Pair<T>` without
+even knowing what type that might be. This allows the type system to track the type of values passed
++between functions and methods or put into and taken out of containers and so on.
+
+**Generic methods** can be declared just as generic functions. There is one caveat, however:
+Only if a method introduces its own, new type variables is it called a generic method. If it is
+merely using the type variables of its containing class or interface, it's an ordinary method.
+The following example illustrates the difference:
+
+[source,n4js]
+----
+export public class Pair<T> {
+ …
+ public foo(): T { … }
+ public <S> bar(pair: Pair2<S>): void { … }
+}
+----
+
+The first method `foo` is a non generic method, while the second one `bar` is.
+
+A very interesting application of static methods is when using in combination with function type arguments:
+
+[source,n4js]
+----
+class Pair<T> {
+ …
+ <R> merge(merger: {function(T,T): R}): R {
+ return merger(this.first, this.second);
+ }
+}
+
+var p = new Pair<string>();
+…
+var i = p.merge( (f,s)=> f.length+s.length )
+----
+
+You will notice that N4JS can infer the correct types for the arguments and the return type of the arrow expression. Also the type for `i` will be automatically computed.
+
+== Differences to Java
+
+Important differences between generics in Java and N4JS include:
+
+* Primitive types can be used as type arguments in N4JS.
+* There are no raw types in N4JS. Whenever a generic class or interface is referenced, a type argument has to be provided - possibly in the form of a wildcard. For generic functions and methods, an
+ explicit definition of type arguments is optional if the type system can infer the type arguments
+ from the context.
diff --git a/src/features/images/moduleimport.png b/src/features/images/moduleimport.png
new file mode 100644
index 0000000..4194d69
--- /dev/null
+++ b/src/features/images/moduleimport.png
Binary files differ
diff --git a/src/features/images/nodejs.png b/src/features/images/nodejs.png
new file mode 100644
index 0000000..e253aad
--- /dev/null
+++ b/src/features/images/nodejs.png
Binary files differ
diff --git a/src/features/images/organizeimports.png b/src/features/images/organizeimports.png
new file mode 100644
index 0000000..fb712a5
--- /dev/null
+++ b/src/features/images/organizeimports.png
Binary files differ
diff --git a/src/features/images/quickfixnpminstall.png b/src/features/images/quickfixnpminstall.png
new file mode 100644
index 0000000..e56dd0f
--- /dev/null
+++ b/src/features/images/quickfixnpminstall.png
Binary files differ
diff --git a/src/features/images/testresultsview.png b/src/features/images/testresultsview.png
new file mode 100644
index 0000000..e2ad183
--- /dev/null
+++ b/src/features/images/testresultsview.png
Binary files differ
diff --git a/src/features/index.adoc b/src/features/index.adoc
new file mode 100644
index 0000000..1429976
--- /dev/null
+++ b/src/features/index.adoc
@@ -0,0 +1,347 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+[discrete]
+.Eclipse N4JS Language and IDE Features
+= Eclipse N4JS Language and IDE Features
+:doctype: book
+:toc: right
+
+
+[discrete]
+== Feature Table
+
+ifdef::index[]
+++++
+<div id=features-nav>
+<nav>
+ <h2>N4JS Features</h2>
+ <ul>
+ <li><a href="#_statements-and-expressions">Statements and Expressions</a></li>
+ <li><a href="#_scoping-and-access-restrictions">Scoping and Access Restrictions</a></li>
+ <li><a href="#_functions">Functions</a></li>
+ <li><a href="#_declared-types">Declared Types</a></li>
+ <li><a href="#_types">Types</a></li>
+ <li><a href="#_generics">Generics</a></li>
+ <li><a href="#_type-constructors-and-special-types">Type Constructors and Special Types</a></li>
+ <li><a href="#_asynchronous-programming">Asynchronous Programming</a></li>
+ <li><a href="#_components-and-modules">Components and Modules</a></li>
+ <li><a href="#_api">API</a></li>
+ <li><a href="#_testing">Testing</a></li>
+ <li><a href="#_node-js-support">Node.js Support</a></li>
+ <li><a href="#_n4js-ide-features">N4JS IDE Support</a></li>
+ <li><a href="#_n4js-headless-compiler">N4JS Headless Compiler</a></li>
+ </ul>
+</nav>
+</div>
+++++
+endif::[]
+
+The following table gives an overview of features implemented by N4JS.
+
+== Remarks
+
+[#remarks]
+* The parser fully supports ECMAScript 2015 syntax including unicode escape sequences, regular expressions and automatic semicolon insertion. Not all constructs are fully supported by the type-checker yet.
+* The transpiler translates N4JS to V8-compatible JavaScript. ES2015 constructs not supported by latest V8 are rejected by N4JS.
+* Except ``project`` (as an access modifier, will be removed in future versions as it is the default), N4JS does not introduce any new keywords to ECMAScript 2015/ES.next.
+If additional functionality requires explicit declarations, this is done via annotations similar to Java (using ``@``).
+There are no user-defined annotations supported at the moment (this is why we do not list annotations as a feature).
+
+== Feature Table
+
+
+[role=done,cols="^2,^1,<4"]
+|===
+3+h| [[_statements-and-expressions]] Statements and expressions
+
+h| Feature h| Similar to h| Description
+s| ECMAScript 5 | ES5 | ES5 expressions, statements and declarations are fully supported (except scoping in with-statement) including type constraints and inference.
+|===
+
+[role=most,cols="^2,^1,<4"]
+|===
+s| Import, Export | ES2015 | import statement fully supported, exporting declarations is supported, re-export not fully supported yet, no relative imports, no anonymous default export.
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+3+h| [[_scoping-and-access-restrictions]] Scoping and access restrictions
+
+s| for..of loops | ES2015 | Fully supported including destructuring.
+s| Function scoping | ES5 | ES5-like function scoping with ``var``
+s| Block scoping | ES2015 | ES2015-like block scoping with ``let`` and ``const``
+s| Constants | ES2015 | const variables (requiring initializers at declaration) with block scoping using keyword ``const``
+s| Final fields | Java | final fields (requiring initialization in constructor) with annotation ``@Final``
+s| Access modifiers | Java | Access modifiers almost similar to Java: public, protected, private. Instead of
+package, project is introduced limiting access to the current project or
+component. For larger projects with components from multiple vendors, an additional modifier ``@Internal`` is
+introduced to restrict access to vendor-types only.
+s|String templates | ES2015 | ES2015-like string templates with validation (of expressions inside the template).
+|===
+
+
+[role=done,cols="^2,^1,<4"]
+|===
+3+h| [[_functions]] Functions
+
+s| Function objects | ES | Function (and method) expressions and declarations are modeled as function objects (with function type)
+s| Function subtyping | Java+ES | Override compatibility (similar to Java) with notion of ECMAScript semantics (superfluous or variadic parameters)
+s| Arrow expression | ES2015 | Arrow functions with this binding according to ES2015
+s| Rest parameters | ES2015 | Fully supported, parameters are treated as arrays inside function
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+s| Optional parameters | | Parameters can be marked optional. This is going to be replaced with ES2015 default parameters.
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+s| Super calls | ES2015 | Inside methods (of classes), super can be used to call overridden method (or constructor)
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+s| Generators | ES2015 | Syntax supported but not supported by language (type checker) yet.
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+3+h| [[_declared-types]] Declared types
+
+s| Classes | ES2015/Java | Class declarations as in ES2015 (or Java) with single inheritance but implementation of multiple interfaces as in Java)
+s| Interfaces | Java | Interface declarations with default methods (as in Java 8) and data fields (treated as default implementation, can be implemented with field accessors). ``instanceof`` operator can be used with interfaces as well.
+s| Enumeration | *˜ TS* | Simple enumerations with literals and basic reflection
+s| String-based enums | | string based enumerations, literals are of type string
+s| Methods | ES2015 | Methods as in ES2015, including constructor and static methods; overridden or implemented members are to be annotated with ``@Override`` as in Java
+|===
+
+[role=tbc,cols="^2,^1,<4"]
+|===
+s| Field accessors | ES2015 | Getters and setters (in object literals and classes, instance and static); at the moment pairs are automatically recognized, will be changed to ES2015 semantics
+|===
+
+
+[role=done,cols="^2,^1,<4"]
+|===
+s| Data fields | Java | Instance and static fields including initializers as in Java
+s| Class modifiers | Java | As in Java, classes can be declared abstract or final (using ``@Final`` annotation).
+|===
+
+[role=tbc,cols="^2,^1,<4"]
+|===
+3+h| [[_types]] Types
+
+s| Type annotation | ES4 | Type annotations using colon syntax similar to ECMAScript 4 proposal or TS, some special types use different syntax (will probably be adjusted to be compatible with TS)
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+s| any | TS | Top type (super type of every other type), used as default type in N4JS files if no more specific type is declared or can be inferred. No property access is possible, since any has no properties. This is probably the most important difference to TypeScript: In TypeScript anything can be called on any, in N4JS nothing! However, this can be changed with a dynamic modifier, see below.
+s| Primitives | ES | primitive types as in ES5 (number, string, boolean), special types null and undefined (with special variant void to be used for return type)
+|===
+
+[role=most,cols="^2,^1,<4"]
+|===
+s| int | | primitive type int, at the moment used synonymously to number, will be stricter checked and handled in future releases
+s| Symbols | ES2015 | Built-in symbols are supported, dynamically created symbols are not supported yet.
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+s| Nominal types | Java | By default, all subtyping is done nominally as in Java, i.e. subtype relations are to be explicitly declared with ``extends`` and ``implements``
+s| Structural types | *˜ TS* | Modifiers at declarations or references enable structural subtyping. Access modifiers are taken in to account, i.e. only public members become part of a structural type.
+s| Field structural type | | Similar to structural typing, but only fields (data/accessors) are taken into account. Different variants (all fields, read-only fields/getter, write-only fields/setter, initializer variant for special constructor initializer) supported.
+s| Static types | Java | By default, only declared properties of a type can be accessed. This is true independent from the syntax (property access with dot-syntax ``(a.x)`` or index access ``(a["x"])``. To model the map-behavior of Object, arbitrary index access on variables of type Object is allowed.
+s| Dynamic types | | Type modifier ``+`` enables arbitrary property access. Actually ``any+`` is similar to TypeScript's any semantics. This is known to be unsafe, so it is not the default behavior (in particular not for any) but only to be used as an "escape hatch".
+s| Arrays | ES | Arrays are modeled as a generic type (extending Object)
+s| Object literals | ES | Object literals are modeled as structural types (\~Object with { properties })
+s| Type cast | *˜ TS* | Expressions can be explicitly casted to a type via ``as``
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+3+h| [[_generics]] Generics
+
+s| Generic types | Java | Generic class and interface declarations, parameterized type references (raw type usage not allowed)
+s| Generic functions and methods | Java | Generic functions (and methods)
+s| Type variables, wildcards | Java | Type variables (in declarations) and wildcards (in references) with upper and lower bounds</tr>
+s| Type variable inference | Java | Type variables are inferred if not explicitly bound by type arguments in the reference, this is particularly important for generic function/method calls. The type inference algorithm matches the Java 8 specification.
+|===
+
+
+[role=done,cols="^2,^1,<4"]
+|===
+3+h| [[_type-constructors-and-special-types]] Type Constructors and Special Types
+
+s| Union type | *˜ TS* | An union type defines that a variable (of that type) is subtype of (at least) one type defined in the union. Without further type checks, only members available in all types of the union are available. In case of methods, formal parameter types are merged by means of intersection types (and return types by means of union types)
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+s| Intersection type | TS | An intersection type defines that a variable (of that type) is subtype of all types defined in the intersection. Thus, members defined in any type of the union are available. Property access to intersection types is not fully supported yet.
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+s| Constructor type | *˜ TS* | Type of a (non-abstract) class declaration or expression itself. Special subtyping rules are implemented, i.e. constructor signature is taking into account.
+s| type type | | Type of a class or interface declaration, without any constructor. That is, variables of this type cannot be used in new-expressions. However, this type is useful in combination with static polymorphism.</tr>
+s| this type | *˜ TS* | Type of the this-literal, can be used in combination with structural typing. Via annotation ``@This`` this type can be explicitly defined for functions.
+s| Dynamic polyfills | | In order to model the commonly used pattern of polyfills and to add new properties to built-in types (as in ES2015), dynamic polyfills can be defined (in definition modules only). They look like partial classes. The modules defining these polyfills may define (plain JS) modules which are to be executed at initialization time in order to apply the polyfills at runtime.
+s| Static polyfills | | In larger projects, often classes are automatically generated. In order to enrich these classes without changing the generator, static polyfills can be defined. The transpiler merges these static polyfills into the original modules.
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+3+h| [[_asynchronous-programming]] Asynchronous Programming
+
+s| Promise | ES2015 | Object type Promise as defined in ECMAScript 2015 defined as ES2015 API type
+s| Async/await | ES.next | async and await keywords for implicit promises, syntax and semantics closely follow https://tc39.github.io/ecmascript-asyncawait/[ES proposal]; transpiled to generator functions; validation checks correct usage of async await, async functions will implicitly return Promises. async can be used with function or method declarations, function and arrow expressions
+s| Promisifiable | | Via annotations ``@Promisifiable`` ES5-conform functions following code conventions for asynchronous callback parameters (last parameter is a callback function etc.) can be used as if they were defined with ``async`` keyword, i.e. they can be used with ``await`` keyword (or a promise can be retrieved via annotation ``@Promisify``)
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+3+h| [[_components-and-modules]] Components and Modules
+
+s| Components | | N4JS and the N4JS IDE use the notion of components (or projects). An N4JS component is described with a manifest, in which the component and its dependencies are defined. N4JS introduces different component types: Runtime libraries and runtime environments define capabilities of specific JavaScript engines and execution environments (such as node.js vs. browser); test components have extended access to the tested components
+s| Modules | ES2015 | N4JS defines modules similar to ES2015, these modules are transpiled to V8-compatible JavaScript
+s| Type definition modules | TS | In order to provide type annotations for existing projects, definition files (n4jsd) are used.
+s| Module Loader | ES5/ES2015 | Unified output with support for https://github.com/systemjs/systemjs[System.js] and Common.js (https://nodejs.org/docs/latest/api/modules.html[Node.js implementation]) module loaders. Since System.js enables better handling of dependency cycles, this is the default loader used by the IDE
+s| Dependency Injection | Java | Dependency injection is supported using annotations similar to https://jcp.org/en/jsr/detail?id=330[JSR-330] (probably better known from https://github.com/google/guice[Guice]) and more to reduce client side glue code. Fields (and parameters) can be injected via ``@Inject``, injectors can be easily set up via ``@GenerateInjector`` and configured with binders (and ``@Bind annotation``). The built-in framework supports nesting of injectors, different injection points (field, constructor, method), providers and different scopes (default, singleton, injection-chain-singleton).
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+3+h| [[_api]] API
+
+s| ES5 object types | ES | All ECMAScript 5 object types are available in N4JS, type annotations are built-in
+|===
+
+[role=most,cols="^2,^1,<4"]
+|===
+s| ES2015 object types | ES2015 | ECMAScript 2015 object types are defined by means of runtime libraries and a runtime environment. N4JS does not provide any implementation of these object types. Also, not all details are defined yet. This will be updated in future releases, depending also on V8 capabilities. However, the most important object types such as collections are defined already.
+s| Reflection | | Besides ECMAScript reflection mechanisms, N4JS provides additional reflection at runtime via a built-in class N4Class. This class provides basic information at the moment, this will be improved in future releases
+|===
+
+
+[role=done,cols="^2,^1,<4"]
+|===
+3+h| [[_testing]] Testing
+
+s| JUnit-like annotations | Java | Tests can be annotated similar to http://junit.org/[JUnit], i.e. tests methods with ``@Test``, setup code with`` @Before``/``@BeforeAll`` etc.
+s| Built-in Test Framework | | An xUnit-like test framework "mangelhaft" using test annotations is provided with the IDE
+s| Extended Access | | Test classes (in special test components) have extended access to tested projects, e.g., can access non-public members
+s| Test Execution | | Tests can be started from the IDE using node.js. It is possible to run single test modules, single methods, or whole packages/projets.
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+3+h| [[_node-js-support]] node.js Support
+
+s| Dynamic Import | | In order to use projects without type annotations, the dynamic module import can be used to make the module dynamic (so that arbitrary properties can be accessed)
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+s| Automatic download of Type Definitions | | If available, type definitions are automatically downloaded when an NPM module is installed via the IDE.
+New type definitions will be added in the future.
+s| Execution | | Modules can be run from the IDE using node.js, either using module loader System.js (default) or Common.js
+s| npm Export | | Components an be exported to the file system, package.json is automatically created and content is organized according to NPM convention -- ready to be published with NPM (which is not done automatically in order to avoid rash publications)
+|===
+
+
+[role=done,cols="^2,^1,<4"]
+|===
+3+h| [[_n4js-ide-features]] N4JS IDE Features
+
+s| Syntax highlighting | | Syntax highlighting with special highlighting of type annotations, can be used for editing n4js, n4jsd or plain js files
+s| Immediate validation | | Code is validated as you type
+s| Incremental builder | | Code is transpiled as you save, only effected modules will be re-compiled
+|===
+
+[role=most,cols="^2,^1,<4"]
+|===
+s| Content assist | | Basic content assist (propose properties of the receiver, keywords) is working; will be improved in future releases
+s| Quickfixes | | Quick fixes to solve common issues, e.g. adding missing annotations or modifiers; more quickfixes will be added in future releases
+s| Wizards | | Wizards for creating new projects, classes or interfaces.
+More wizards will be added in future releases
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+s| Organize imports | | Automatically add missing imports and remove unused imports. A
+lso content assist and quickfixes will add imports - you never have to type import statements.
+s| Project and outline view | | Project view showing all components in workspace, (quick) outline view to easily navigate to declared elements.
+s| Jump to declaration | | Navigate from reference to bound declaration
+s| Find all references | | Find all references bound to a declaration
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+s| Error reporting | | We embrace bug reports! In order to enable easier writing of bug reports, language tests can be written inside the IDE.
+This feature will be improved in the future.
+|===
+
+[role=done,cols="^2,^1,<4"]
+|===
+s| Eclipse-powered | | Since the IDE is based on Eclipse, additional features such as git support are integrated or can easily be installed
+|===
+
+[role=most,cols="^2,^1,<4"]
+|===
+3+h| [[_n4js-headless-compiler]] N4JS Headless Compiler
+
+s| n4jsc | | The headless compiler is workspace aware, i.e. it can compile all projects with a single command.
+This makes it very easy to set up CI jobs. At the moment, the headless compiler is made available as a jar-file.
+Additional support simplifying installation and usage will be added in future releases
+|===
+
+
+== Legend
+
+[role=done]
+|===
+5+^h|FeatureTable
+
+s|green 4+| available, although there might be bugs in the alpha-release.
+|===
+
+[role=most]
+|===
+s|yellow 4+| mostly available, some aspects or parts of the feature are not implemented yet or will be improved in the future.
+|===
+
+[role=tbc]
+|===
+s|orange 4+| feature available but syntax or semantics will be changed in future releases
+|===
+
+[role=tbd]
+|===
+s|red 4+| planned for future releases but not implemented yet.
+|===
+
+
+== References
+
+|===
+5+^h|References
+
+s|ES 4+| http://www.ecma-international.org/ecma-262/5.1/[ECMAScript Language Specification] / ISO/IEC. Geneva, Switzerland, Juni 2011 (ECMA-262, 5.1 Edition)
+s|ES2015 4+| http://www.ecma-international.org/ecma-262/6.0/[ECMAScript 2015 Language Specification] / ISO/IEC (ECMA-262, 6th Edition). – International Standard.
+s|ES4 4+| Proposed ECMAScript 4th Edition – Language Overview / ECMA. – Proposal, http://www.ecmascript.org/es4/spec/overview.pdf[PDF].
+s|ES.next 4+| ECMAScript proposals (ECMAScript 2017 or later or never)
+s|TS 4+| Hejlsberg, Anders ; Lucco, Steve: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md[TypeScript Language Specification]. 1.8. Microsoft, Januar 2016.
+**˜ TS** means very similar functionality.
+s|Java 4+| Gosling, James et al: https://docs.oracle.com/javase/specs/jls/se8/html/index.html[The Java Language Specification]. Java SE 8 Edition. JSR-337 Java SE 8 Release Contents.
+|===
diff --git a/src/features/modules.adoc b/src/features/modules.adoc
new file mode 100644
index 0000000..3936ba7
--- /dev/null
+++ b/src/features/modules.adoc
@@ -0,0 +1,125 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+
+.Modules
+= Modules
+:doctype: book
+:toc: right
+
+
+Large-scale projects of almost any language require good modularization for maintenance reasons.
+It's vital for projects that modules don't become oversized and comprise a well-defined purpose
+that is easy to comprehend for developers. The N4JS IDE helps for keeping track of your code modules and validates their usage.
+
+== Multiple Exports
+
+While it's a good habit to assign one module for a single type, it may
+be suitable to define multiple types or variables in a single module in cases where they
+correspond or are related.
+ECMAScript 2015 allows for this with the module syntax it defines. The good news is
+that N4JS already supports most of it:
+
+[source,n4js]
+----
+export public function inc(): void { ++count; }
+export public var count = 5;
+export default public class Foo {
+ public callOnIt(): void { }
+}
+----
+
+Importing an ECMAScript 2015 module and consuming exports is as easy as the following:
+
+[source,n4js]
+----
+import { inc, count } from 'Counter';// Named imports
+import Foo from 'Counter'; // Default import
+import { readFile } from 'fs' // Node.js core modules
+import express from 'express'; // npm modules
+import * as plainJsModule+ from 'plainJsModule'; // Dynamic import
+----
+
+The module could also be imported as a whole:
+
+[source,n4js]
+import * as foo from 'Counter'; // Namespace import
+
+NOTE: Anonymous default exports and relative module paths are not yet supported. The module specifier is the relative path of the
+module in its source folder. Optionally the project name can be used as prefix, e.g., in case of ambiguities.
+
+== N4JS IDE Organizes Imports
+
+Manually writing import statements is not necessary: the N4JS IDE does this automatically.
+The IDE will recognise all projects involved via various runtime and
+library dependencies that are defined in by the user in the manifest.n4mf file.
+Simply write the type or variable you require and press kbd:[Ctrl+SPACE].
+Content assist within the IDE will add the missing import statement for you:
+
+image::images/moduleimport.png[]
+
+When pasting in a code snippet, you could use kbd:[Ctrl+Shift+O]
+(on Windows and Linux, kbd:[Cmd+Shift+O] on Mac) which organizes your imports and
+will add any that are missing. This is also used to clean up any unused imports:
+
+image::images/organizeimports.png[]
+
+
+== Import Removal
+
+When developing in N4JS, you may notice that you sometimes need to import types to cast
+a variable or use it for a constraint in a generic.
+
+[source,n4js]
+----
+import Foo from 'Counter';
+
+var someOtherVar: Object;
+(someOtherVar as Foo).callOnIt();
+
+export function <T extends Foo> bar(t: T): void { }
+----
+
+The compiler will notice that there's no runtime code dependency on the
+imported module and will omit loading the module.
+
+
+== Read-only Views
+
+ES2015 modules have the concept of read-only views. Although you cannot modify anything imported from
+a module, your binding is live. In the case that the exporting party has modified
+the export, you will read the current value. For example:
+
+[source,n4js]
+----
+import {inc, count} from 'Counter';
+
+console.log(count); // 5
+inc();
+console.log(count); // 6
+----
+
+
+Although highly discouraged, read-only views allow to support some cyclic
+dependencies across modules. N4JS might even reorder type definitions to achieve this.
+
+
+== Loader Details
+
+So far, there's no engine/platform that has implemented the ES2015 specification natively. N4JS
+and most other transpilers, transpile modules into the SystemJS format.
+
+
+N4JS' output format goes a bit further and emits an unified format that works as well in a
+synchronous CommonJS/Node.js environment.
+Keep in mind, however, that when you load a module the CommonJS way, you are
+limited to this with regard to cyclic dependencies because it has to resolve all
+dependencies synchronously.
diff --git a/src/features/nodejs-support.adoc b/src/features/nodejs-support.adoc
new file mode 100644
index 0000000..ecc5c14
--- /dev/null
+++ b/src/features/nodejs-support.adoc
@@ -0,0 +1,98 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+
+.Node.js Support
+= Node.js Support
+:doctype: book
+:toc: right
+
+N4JS and its IDE are optimized to develop large scale server applications with https://nodejs.org[Node.js]
+Besides launching and testing code from the IDE using Node.js, additional support is provided for automatically downloading
+https://www.npmjs.com/[npm] packages and exporting N4JS projects to npm. This allows for seamless integration
+of N4JS projects with existing Node.js based environments.
+
+== Installing and using npm packages
+
+N4JS helps Node.js developers to use third-party npm packages with support both on the language and tooling level. The
+required packages can be downloaded and installed on-demand into the IDE via the library manager and this feature is also
+supported in the headless tooling.
+
+image::images/quickfixnpminstall.png[]
+
+=== Dynamic Import
+
+Third-party packages are supported in two different ways. If an npm package does not have any corresponding type definition
+files defined yet, then the required module can be imported into an N4JS module dynamically. In order to support the import
+of modules without any N4JS (`.n4js`) or N4JS type definition (`.n4jsd`) files, N4JS extends the ES2015
+module import. This is done by declaring the imported module with "`+`" appended to the end of the named import.
+This so called "dynamic module import" will be treated as a type of `any+`.
+
+[source,n4js,numbered]
+----
+import * as mongodb+ from 'mongodb';
+
+var client = mongodb.MongoClient;
+
+client.connect("…", function (err, db: any+) {
+ if (err) {
+ console.log('Unable to connect to the mongoDB:', err);
+ } else {
+ …
+ db.close();
+ console.log('Connection closed at', url);
+ }
+});
+----
+
+In the example above, `mongodb` is dynamically imported. It is therefor possible to access arbitrary properties,
+such as the "class" `MongoClient` in line 3. The type of these properties will become any+ as well, so that it is
+possible to access properties from the class as well, as shown in line 5 and 10.
+
+
+=== Automatic Download of Type Definitions
+
+If type definitions are available at https://github.com/NumberFour/n4jsd[our N4JS type definition project] for a
+particular npm package
+these definitions will be included automatically when the npm package is being downloaded and installed. All npm packages with
+type definitions seamlessly integrate into the N4JS system. This means that all third-party npm packages with the correct type
+definitions behave just like any other N4JS module or project declared in the workspace. The language provides type safety while
+the tooling provides content assist, navigation, search functionality and so on.
+
+image::images/nodejs.png[]
+
+The IDE also supports a way to check for any type definition updates in an on-demand fashion. This means that you can initially
+begin to use any third-party packages that don't yet have type definition files. In such cases (as described above) the modules
+from the npm packages have to be imported dynamically.
+It's then possible to perform a manual refresh from the IDE and the
+application will check for any type definition updates. If the type definitions have been declared and been made available,
+meanwhile, the application will download the definitions and warn the user at the location of the dynamic imports about the
+availability of the type definition file. It's then possible to switch to the type safe approach by removing the appended
+`+` from the named module import.
+
+At the moment, writing type definition files requires to manually set up a new project and configuring the manifest etc.
+accordingly. We will improve supporting that to simplify users to write new and enrich existing type definitions and share
+them with others via https://github.com/NumberFour/n4jsd[our N4JS type definition project] in future releases.
+
+== Exporting N4JS projects as npm packages
+
+Besides supporting npm package download and usage, the IDE comes with an npm package export feature.
+Any N4JS workspace project can then be transformed into a structure that complies to npm requirements and can be exported
+into the local file system.
+These exported structures can later be used to manually publish them as packages to npm.
+The corresponding `package.json` file will be created based on the dependencies declared in the N4JS manifest file of
+the exported N4JS project.
+Although all direct and transitive dependencies will be included in the brand new `package.json` file, only the
+desired N4JS projects will be transformed and exported.
+The `package.json` content can be customized by creating a `package.json` template file in the root of
+the N4JS project
+With this template, additional attributes can be defined.
+This feature is further explained in the <<../userguides/npm-export-guide.html#npm_export_guide,npm export guide>>.
diff --git a/src/features/nominal-and-structural-typing.adoc b/src/features/nominal-and-structural-typing.adoc
new file mode 100644
index 0000000..3932ba5
--- /dev/null
+++ b/src/features/nominal-and-structural-typing.adoc
@@ -0,0 +1,275 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+
+.Nominal And Structural Typing
+= Nominal And Structural Typing
+:doctype: book
+:toc: right
+
+
+One of the core responsibilities of a type system is to decide if two given types
+are **type compatible**, or if a type is a **subtype** of another type.
+N4JS provides support for different strategies of checking whether two types are compatible,
+namely nominal (as known from Java) and structural typing (as known from TypeScript).
+Additionally it proivdes certain variations of structural typing to support typical
+usages in ECMAScript.
+
+
+
+A type T~1~ is compatible with a type T~2~ if,
+roughly speaking, a value of type T~1~ may be used as if it were a value of
+type T~2~.
+Therefore, if type T~1~ is compatible to type T~2~, a value that is
+known to be of type T~1~
+may, for example, be assigned to a variable of type T~2~ or may be passed as
+an argument to a
+function expecting a value of type T~2~.
+There are two major classes of type systems that differ in how they decide on
+type compatibility:
+
+
+
+* Nominal type systems.
+* Structural type systems.
+
+
+Since N4JS provides both forms of typing, we briefly introduce each approach in
+the coming sections before we show how they are combined in N4JS.
+
+== Nominal Typing
+
+
+In a **nominal**, or **nominative**, type system, two types
+are deemded to be the same if they have the
+**same name** and a type T~1~ is deemed to be a (immediate) subtype of
+a type T~2~ if T~1~
+is **explicitly declared** to be a subtype of T~2~.
+
+
+
+In the following example, `Employee` is a subtype of `Person`
+because it is declared as such using keyword "extends"
+within its class declaration. Conversely, `Product` is not a subtype of
+`Person` because it lacks such an "extends"
+declaration.
+
+
+[source,n4js]
+----
+class Person {
+ public name: string;
+}
+
+class Employee extends Person {
+ public salary: number;
+}
+
+class Manager extends Employee { }
+
+class Product {
+ public name: string;
+ public price: number;
+}
+----
+
+
+The subtype relation is transitive and thus `Manager` is not just a subtype of
+`Employee` but also of `Person`. `Product` is not a
+subtype of `Person`, although it provides the same members.
+
+Most mainstream object-oriented languages use nominal subtyping, for example C++, C#, Java, Objective-C.
+
+== Structural Typing
+
+In a **structural** type system, two types are deemed the same if they are of the **same structure**.
+In other words, if they have the same public fields and methods of compatible type/signature. Similarly, a type
+T~1~ is deemed a subtype of a type T~2~ if and only if T~1~ has
+all public members (of compatible type/signature) that T~2~ has (but may have more).
+
+In the example from the previous section, we said ``Product`` is not a (nominal) subtype
+of Person. In a structural type system, however, ``Product`` would indeed be deemed a (structual)
+subtype of ``Person`` because it has all of ``Person``'s public members of compatible type (only field
+name" in this case). The opposite is, in fact, not true: ``Person`` is not a subtype of ``Product``
+because it lacks ``Product``'s field ``price``.
+
+== Comparison
+
+Both classes of type systems have their http://lambda-the-ultimate.org/node/5286[own advantages and proponents].
+Nominal type systems
+are usually said to provide more type safety and better maintainability whereas structual typing is mostly believed
+to be more flexible. As a matter of fact, nominal typing **is** structural typing extended with an extra relation
+explicitly declaring the subtype relation (like the ``extends`` clause). So the real question is: What are the
+advantages and disadvantages of such an explicit relation?
+
+Let's assume you want to provide a framework or library as follows:
+
+
+[source,n4js]
+----
+export public interface Identifiable {
+ public get name(): string
+
+ static check(identifiable: Identifiable): boolean {
+ return identifiable.name != 'anonymous';
+ }
+}
+----
+
+[source,n4js]
+----
+
+
+class A {
+
+ public get name(): string { return 'John'; }
+}
+----
+
+[source,n4js]
+----
+import { Identifiable } from 'Identifiable';
+
+class A implements Identifiable {
+ @Override
+ public get name(): string { return 'John'; }
+}
+----
+
+
+A client may use these classes as follows:
+
+
+[source,n4js]
+Identifiable.check(new A());
+
+
+This first example is only to demonstrate the conceptual differences. The
+structural variant would cause an error in N4JS.
+
+=== Maintainability
+
+
+Everything works fine. But maybe you consider to rename `name` to `id`. Assume you have
+thousands of classes and interfaces.
+You start by renaming the function in the interface:
+
+
+[source,n4js]
+----
+export public interface Identifiable {
+ public get id(): string
+ // …
+}
+----
+
+
+With structural typing, you won't get any errors in your framework. You are satisfied with your code and ship
+the new version. Alas! The client code will no longer work as you have forgotten to accordingly rename the
+function in class `A`.
+
+
+With nominal typing, you would have gotten errors in your framework code already ("Class A must implement
+getter id." and "The getter name must implement a getter from an interface."). Instead of breaking the code
+on the client side only, you find the problem in the framework code.
+In large systems, this can be a complete lifesaver. Without this strict validation, you probably wouldn't
+dare to refactor your framework. Of course, you may still break the client code, but even then it is much
+easier to pinpoint the problem.
+
+
+=== Flexibility
+
+
+Given the same code as in the previous example, assume that the client code also uses another framework
+providing a class Person as in the very first example.
+
+
+With structural typing, it is no problem to use the Person class with the function check since the Person
+class provides a data field name. So the code inside the function would work perfectly when called with an
+instance of Person.
+
+This won't work with nominal typing though. Since Person does not explicitly "implement" Identifiable,
+there is no chance to call function check. This can be quite annoying, particularly if the client can change
+neither your framework nor the person framework.
+
+
+
+== Combination of Nominal and Structural Typing in N4JS
+
+
+
+Because both classes of type systems have their advantages and because structural typing is particularly
+useful in the context of a dynamic language ecosystem as that of JavaScript, N4JS provides both
+kinds of typing and aims to combine them in a seamless way.
+
+
+
+N4JS uses nominal typing by default, but allows to switch to structural typing by way of special type
+constructors using the tilde symbol. The switch can be done with either of the following:
+
+* Globally when defining a type. This then applies to all uses of the type throughout the code, referred
+to as**definition-site structural typing**
+* Locally when referring to an existing nominal type, referred to as **use-site structural typing**.
+
+
+
+If we combine the above examples, we can use nominal and structural typing in N4JS as follows:
+
+
+[source,n4js]
+----
+export public interface Identifiable {
+ public get name(): string
+
+ static check(identifiable: ~Identifiable): boolean {
+ return identifiable.name != 'anonymous';
+ }
+}
+
+class A implements Identifiable {
+ @Override public get name(): string { return 'John'; }
+}
+----
+
+
+For the argument of method "check" we use a (use-site) structural
+type by prefixing the type reference with a +++~+++ (tilde), which means
+we are allowed, in the last line, to pass in an instance of ``Product``
+even though ``Product`` is not a nominal subtype of ``Identifiable``.
+
+
+
+This way, N4JS provides the advantages of nominal typing (which is the default form of typing)
+while granting many of the advantages of structural typing if the programmer so chooses.
+Additionally, if you would rename name to id, the tilde would tell you that there may be client code calling
+the method with a structural type.
+
+
+The full flexibility of a purely structurally typed language, however, cannot be achieved with
+this combination. For example, the client of an existing function that is declared to expect
+an argument of a nominal type N is confined to nominal typing. They cannot choose to invoke
+this function with an argument that is only a structural subtype of N (it would be a compile time
+error). This would possibly be exactly the intention of the framework author in order to enable easier
+refactoring later.
+This is comparable to access modifiers which serve the same purpose.
+
+
+=== Field Structural Typing
+
+N4JS provides some variants of structural types. Usually two structural types are compatible, if they
+provide the same properties, or in case of classes, public members. In ECMAScript we often only need to
+access the fields. In N4JS, we can use ``~~`` to refer to the so called "field structural type".
+Two field structural types are compatible, if they provide the same ``public`` fields - methods
+are ignored in these cases. Actually, N4JS can do even more. There are several modifiers to further filter
+the properties or members to be considered: ``\~r~`` only considers getters or data fields,
+``~w~`` only setters and data fields. ``\~i~`` is used for initializer parameters:
+For every setter or (non-optional) data field in the type, the ``~i~`` -type needs to provide
+at least a getter (or readable data field).
diff --git a/src/features/testing.adoc b/src/features/testing.adoc
new file mode 100644
index 0000000..cc4f84d
--- /dev/null
+++ b/src/features/testing.adoc
@@ -0,0 +1,107 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+
+.Testing
+= Testing
+:doctype: book
+:toc: right
+
+Test Driven Development (TDD) is one of the key techniques to write large systems with maintainable code.
+The more tests you write, the more confident you can be that your software works as expected and the more
+comfortable you feel when your refactoring the code, because the tests will tell you if you break something.
+The N4JS language, the N4JS IDE and the built-in test execution runtime (Mangelhaft) were designed and developed
+to support TDD as well as possible.
+
+== Built-In Test Support
+
+From the language perspective, there are annotations that can be used to declare and configure the test
+suites. Mangelhaft is an https://en.wikipedia.org/wiki/XUnit[xUnit-like] framework that
+provides an engine that executes the tests and reports back to the IDE while running the test suites.
+The IDE is responsible for indicating the actual test results received from Mangelhaft to the user. For
+creating a simple test suite, one requires an N4JS project with a test type source container, a test class
+in the test type source container and at least one method declared in the test class with the `@Test`
+annotation. This is described in more detail in the <<../userguides/tutorial#tutorial,tutorial>>.
+Besides the test execution and reporting engine support, Mangelhaft provides various utility classes
+that could come handy when test assertions or preconditions have to be used in the test suites or when negative tests are required.
+
+
+[source,n4js]
+----
+import { Assert } from 'n4/mangel/assert/Assert';
+import { Precondition } from 'n4/mangel/precondition/Precondition';
+
+export public class FooTest {
+
+ @Test
+ public notEquals() {
+ Assert.notEqual(36, 'foo');
+ }
+
+ @Test
+ public iAmSuperstitious() {
+ var today = new Date();
+
+ // Skip running the test on each 13th Friday.
+ var skipTestToday = this.is13thFriday(today);
+ Precondition.isFalse(skipTestToday);
+
+ // Rest of the test logic.
+ }
+
+ private is13thFriday(date: Date): boolean {
+ …
+ }
+}
+----
+
+== N4JS Language Support
+
+https://www.junit.org[Junit-like] annotations are are available to configure the test suits, such as:
+
+`@Test` - The annotated method will be percepted as a test case when configuring and running the test suite.
+`@Ignore` - The annotated method will be percepted as a test case when configuring the test suite but the marked case will be be executed as a part of the suite execution.
+`@Fixme` - The annotated method will be percepted as a test case when configuring and running the test suite but the assertion logic will be negated.
+
+Test classes can be created in the test container of any arbitrary project. With this approach,
+the production code can be separated from the test code but both production and test code will
+still be contained in the same N4JS project.
+
+
+Another implementation is that of a 'test project'-type implementation whereby one can completely
+separate the business logic form the test code. This is done literally using two separate projects;
+one for the production and one for the test code. Aside from the code separation, the major advantage
+of using a test project is that the default access visibility restrictions can be overruled.
+Project-visible classes and interfaces and their non-visible members and methods can then be called
+and tested from the test projects while still not visible in the production code. In a nutshell,
+one can easily test different aspects of the application without breaking the encapsulation.
+
+
+== N4JS IDE Support
+
+
+In the N4JS IDE, the Test Results view provides an informative overview of all executed and running
+test suites in a tree structure. Tests can be executed via the context menu's
+**menu:Run As[Test in Node.js]** item directly from the editor or from
+the Project Explorer view. It is possible to execute all tests form a particular project as well as
+one single, fine-grained test case from a particular test class.
+
+
+image::images/testresultsview.png[]
+
+== Additional Features
+
+
+* Navigate to test method.
+* Showing stack trace for failed tests.
+* Quick-test method overview in a popup window.
+* Test suite history.
+* Re-run previous test suite.
diff --git a/src/images/n4js-logo.png b/src/images/n4js-logo.png
new file mode 100644
index 0000000..e0b8340
--- /dev/null
+++ b/src/images/n4js-logo.png
Binary files differ
diff --git a/src/images/up-arrow.png b/src/images/up-arrow.png
new file mode 100755
index 0000000..1ff179f
--- /dev/null
+++ b/src/images/up-arrow.png
Binary files differ
diff --git a/src/releases/images/xpect_feature_request.png b/src/releases/images/xpect_feature_request.png
new file mode 100644
index 0000000..54acbea
--- /dev/null
+++ b/src/releases/images/xpect_feature_request.png
Binary files differ
diff --git a/src/releases/images/xpect_fixme.png b/src/releases/images/xpect_fixme.png
new file mode 100644
index 0000000..98eea9e
--- /dev/null
+++ b/src/releases/images/xpect_fixme.png
Binary files differ
diff --git a/src/releases/index.adoc b/src/releases/index.adoc
new file mode 100644
index 0000000..aa60832
--- /dev/null
+++ b/src/releases/index.adoc
@@ -0,0 +1,58 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+.Releases
+= Releases
+:doctype: book
+:notitle:
+
+[discrete]
+== Current N4JS Release
+
+
+The Eclipse N4JS project is in the link:https://wiki.eclipse.org/Development_Resources/HOWTO/Incubation_Phase[Incubation Phase] and there is no official release available yet (for unofficial releases see the link:../download.html[download page].
+This doesn't mean that N4JS is unstable; we have an extensive test suite (>90.000 tests including the https://github.com/tc39/test262[ECMAScript test suites]) to ensure a stable nightly build.
+N4JS has been in use in several large non-public projects for years.
+There still may be bugs (as there are always bugs) and features which are currently under development.
+We encourage feedback from all users! For questions about getting started with the N4JS Language and IDE for developing your own projects, see the link:https://www.eclipse.org/forums/index.php/f/365/[the Eclipse N4JS forum].
+
+== Known Issues
+
+Since we are using N4JS and the N4JS IDE internally for quite a while, we have found some issues.
+There are still a lot of bugs open and we have plenty of ideas for new features.
+We have used a non-public bug tracking system to manage bugs internally and we are currently migrating them to https://github.com/eclipse/n4js/issues[GitHub issues].
+Note that it's also possible to write and <<reporting-bugs#reporting_bugs,submit bug reports>> from within the N4JS IDE itself.
+
+== New Features
+
+In the future, the following topics are expected to be addressed:
+
+* Improved UI experience with a focus on customized content assist and quick-fixes.
+* Improved ECMAScript 2015 support.
+* Improved type inference and add type guards.
+* Improved refactoring capabilities.
+* Improved Node.js developer experience.
+* Support for browser-based projects.
+
+There may be other topics raised by users.
+Separating these topics into individual features and prioritizing them will **highly depend on your feedback**.
+
+== Incompatible Changes in Future Releases
+
+Yes, this may happen.
+It's quite possible that the language or APIs must be changed in future releases, which could break existing code.
+This is no cause for concern, however.
+As mentioned before, we have a substantial internal code base, so if incompatible changes are introduced, we will provide tools to migrate your code automatically unless the changes are easier to solve manually.
+
+To give you an idea of how this can happen: In earlier versions we used a Java-like syntax for type annotations.
+Since this did not work well together with features such as async/await, we changed the syntax to ECMAScript 4 colon style.
+This required our entire code base to be reworked.
+Fortunately this was simple as we provided a quick-fix, enabling almost all problems stemming from that change to be corrected with a single keystroke!
diff --git a/src/releases/reporting-bugs.adoc b/src/releases/reporting-bugs.adoc
new file mode 100644
index 0000000..efe7ae6
--- /dev/null
+++ b/src/releases/reporting-bugs.adoc
@@ -0,0 +1,126 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+:doctype: book
+:notitle:
+
+.Reporting Bugs
+= Reporting Bugs
+
+**We embrace bug reports and feature requests!**
+
+
+For the moment, we use https://github.com/eclipse/n4js/issues[GitHub issues] to manage
+issues found by users. We will soon migrate our current, internal list of bugs there. We greatly appreciate
+all bug reports, thank you so much for your time!
+
+If you like, you can try out a novel test technology called http://www.xpect-tests.org/[Xpect]
+that was designed for writing tests for domain-specific languages and that we have integrated into the N4JS
+IDE. It is described in detail in the coming section.
+
+
+== Write Bug Reports with Xpect
+
+With Xpect you can write concise bug reports and feature requests using N4JS and comments. What is a bug? A
+bug usually is a programming error that leads to unexpected behavior. What is a feature? A feature is a
+functionality provided by a system with a well-defined, i.e. expected, behavior. In other words: Bug
+reports and feature requests both have to describe the **expected** behavior. Instead of long explanations
+separated from the code, it is often easier to just add this **expectations** to the code.
+
+The following screenshot shows a typical feature request (on the left hand side), written with Xpect:
+
+
+image::images/xpect_feature_request.png[]
+
+The great thing about Xpect is that it actually defines a test. That is the feature request (or bug report)
+can be executed. This is even possible within the N4JS IDE, and the result is shown on the right hand side
+of the screenshot above. In order to do that, all you have to do is
+
+
+ * Create a new file with extension `n4js.xt` (".xt" will activate Xpect)
+ * Write the bug report or feature request, using comments and the keyword `XPECT` together with a known
+xpectation type (see below)
+ * Run the Xpect test from the context menu **menu:Run As[Xpect run]**.
+
+
+**Instead of writing long explanations, just file the `n4js.xt` file as bug report (and a short explanation)!**
+
+Note that in the screenshot the file does not contain any error markers - your expectation is already taken
+into account during validations, improving the readability of the bug report. As shown in the screenshot above,
+the Xpect test failed! In order to make things easier for the developer fixing the bug, you can add an additional
+keyword `FIXME` to expectations you have but which are not fulfilled. In particular in longer reports with several
+expectations, it is very helpful to easily identify what is expected and what is correct behavior. When running the
+test again with the `FIXME` annotation, it will succeed as shown in the following screenshot:
+
+image::images/xpect_fixme.png[]
+
+**Bug reporting will be improved in future releases!**
+
+In future releases, we will improve the Xpect support and simplify writing bug reports. In particular, we will
+provide content assist or wizards for adding certain types of expectations.
+
+In general, expectations are written inside comments preceding the line in the code which demonstrates the
+un-)expected behavior, according to the following pattern:
+
+[source]
+// «remark» XPECT «type» FIXME -->
+«expectation» at «location»
+
+ * *remark*: optional and can be omitted.
+ * *type:* The type of the expectation is one of the types described in the table below.
+ * *keyword* "FIXME": is optional and is used to indicate currently missing or unexpected behavior
+ * *expectation*: optional, usually used for the expected issue message, or value; concrete semantic depends
+on the expectation type.
+ * *location*: used to further indicate the location of the problem, usually just the next line is assumed. The location has to be prefixed with `at` in most cases
+
+
+If a single code line contains
+several issues, multi-line comments are to be used:
+
+[source,n4js]
+/* «remark» XPECT «type» ---
+"expectation1" at "location1"
+"expectation2" at "location2"
+...
+--- */
+
+Depending on the type of the expectation, the syntax may be a little bit different. The following table summarizes
+the known types along with an example snippet to illustrate the syntax.
+
+=== errors
+
+Probably the most often used expectation type, indicates a validation error to be issued.
+
+[source]
+// XPECT errors FIXME --> "float literal assigned to int"
+var i: int = 5.5;
+
+=== warnings
+
+ Similar to "errors", indicates a validation warning to be issued.
+
+[source]
+// XPECT warnings FIXME --> "float literal assigned to int"
+var i: int = 5.5;
+
+
+=== noerrors
+
+See example above, used if no error is expected.
+
+[source]
+var a: A;
+if (o instanceof A) {
+ // I want type guards XPECT noerrors FIXME -->
+ a = o;
+}
+
+More expectation types will become available in future versions.
diff --git a/src/userguides/images/architecture.graffle b/src/userguides/images/architecture.graffle
new file mode 100644
index 0000000..b3d190e
--- /dev/null
+++ b/src/userguides/images/architecture.graffle
Binary files differ
diff --git a/src/userguides/images/architecture.svg b/src/userguides/images/architecture.svg
new file mode 100644
index 0000000..5470972
--- /dev/null
+++ b/src/userguides/images/architecture.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="75 16 219 202" width="219pt" height="202pt" xmlns:dc="http://purl.org/dc/elements/1.1/"><metadata> Produced by OmniGraffle 6.5.1 <dc:date>2016-03-09 17:06:45 +0000</dc:date></metadata><defs><font-face font-family="Helvetica" font-size="12" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="522.94922" cap-height="717.28516" ascent="770.01953" descent="-229.98047" font-weight="500"><font-face-src><font-face-name name="Helvetica"/></font-face-src></font-face><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="StickArrow_Marker" viewBox="-1 -4 9 8" markerWidth="9" markerHeight="8" color="black"><g><path d="M 6.4 0 L 0 0 M 0 -2.4 L 6.4 0 L 0 2.4" fill="none" stroke="currentColor" stroke-width="1"/></g></marker></defs><g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"><title>Canvas 1</title><rect fill="white" width="724" height="753"/><g><title>Presentation</title><rect x="153.07087" y="18.425197" width="138.89764" height="21.643674" fill="white"/><rect x="153.07087" y="18.425197" width="138.89764" height="21.643674" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(158.07087 22.247034)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="10.106046" y="11" textLength="108.68555">Client (Browser/curl)</tspan></text><line x1="222.51969" y1="40.068871" x2="222.91103" y2="59.719476" marker-end="url(#StickArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g><g><title>Architecture</title><rect x="77.952757" y="53.858268" width="214.01575" height="161.5748" fill="#cbcbcb" fill-opacity=".51"/><rect x="77.952757" y="53.858268" width="214.01575" height="161.5748" stroke="#a0a0a0" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(82.952757 58.858268)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="0" y="11" textLength="21.351562">App</tspan></text><rect x="171.27115" y="144.5806" width="103.610277" height="21.643674" fill="white"/><rect x="171.27115" y="144.5806" width="103.610277" height="21.643674" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(176.27115 148.40243)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="8.1215445" y="11" textLength="77.367188">Domain Model</tspan></text><rect x="171.27115" y="106.299214" width="103.610277" height="21.643674" fill="white"/><rect x="171.27115" y="106.299214" width="103.610277" height="21.643674" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(176.27115 110.12105)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="20.795373" y="11" textLength="52.01953">Controller</tspan></text><rect x="171.27115" y="68.01783" width="103.610277" height="21.643674" fill="white"/><rect x="171.27115" y="68.01783" width="103.610277" height="21.643674" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(176.27115 71.839668)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="5.678185" y="11" textLength="32.003906">REST</tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x="37.471154" y="11" textLength="21.328125"> / W</tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x="58.58834" y="11" textLength="29.34375">eb-UI</tspan></text><line x1="223.07629" y1="89.661505" x2="223.07629" y2="97.999214" marker-end="url(#StickArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><line x1="223.07629" y1="127.94289" x2="223.07629" y2="136.2806" marker-end="url(#StickArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><rect x="171.27115" y="182.86198" width="103.610277" height="21.643674" fill="white"/><rect x="171.27115" y="182.86198" width="103.610277" height="21.643674" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(176.27115 186.68382)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="25.79049" y="11" textLength="42.029297">Storage</tspan></text><line x1="223.07629" y1="166.22427" x2="223.07629" y2="174.56198" marker-end="url(#StickArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g></g></svg>
diff --git a/src/userguides/images/asyncerrors.png b/src/userguides/images/asyncerrors.png
new file mode 100644
index 0000000..949d717
--- /dev/null
+++ b/src/userguides/images/asyncerrors.png
Binary files differ
diff --git a/src/userguides/images/awaitwarning.png b/src/userguides/images/awaitwarning.png
new file mode 100644
index 0000000..bd80ad3
--- /dev/null
+++ b/src/userguides/images/awaitwarning.png
Binary files differ
diff --git a/src/userguides/images/controllertest.graffle b/src/userguides/images/controllertest.graffle
new file mode 100644
index 0000000..4861eb9
--- /dev/null
+++ b/src/userguides/images/controllertest.graffle
Binary files differ
diff --git a/src/userguides/images/controllertest.svg b/src/userguides/images/controllertest.svg
new file mode 100644
index 0000000..27aa417
--- /dev/null
+++ b/src/userguides/images/controllertest.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="43 32 291 202" width="291pt" height="202pt" xmlns:dc="http://purl.org/dc/elements/1.1/"><metadata> Produced by OmniGraffle 6.5.1 <dc:date>2016-03-09 20:51:39 +0000</dc:date></metadata><defs><font-face font-family="Helvetica" font-size="12" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="522.94922" cap-height="717.28516" ascent="770.01953" descent="-229.98047" font-weight="500"><font-face-src><font-face-name name="Helvetica"/></font-face-src></font-face><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="StickArrow_Marker" viewBox="-1 -4 9 8" markerWidth="9" markerHeight="8" color="black"><g><path d="M 6.4 0 L 0 0 M 0 -2.4 L 6.4 0 L 0 2.4" fill="none" stroke="currentColor" stroke-width="1"/></g></marker></defs><g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"><title>Canvas 1</title><rect fill="white" width="520" height="737"/><g><title>Layer 1</title><rect x="45.35433" y="69.44882" width="214.01575" height="161.5748" fill="#cbcbcb" fill-opacity=".51"/><rect x="45.35433" y="69.44882" width="214.01575" height="161.5748" stroke="#a0a0a0" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(50.35433 74.44882)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="0" y="11" textLength="21.351562">App</tspan></text><rect x="138.67272" y="160.17115" width="103.610277" height="21.643674" fill="white"/><rect x="138.67272" y="160.17115" width="103.610277" height="21.643674" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(143.67272 163.99299)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="8.1215445" y="11" textLength="77.367188">Domain Model</tspan></text><rect x="138.67272" y="121.889765" width="103.610277" height="21.643674" fill="white"/><rect x="138.67272" y="121.889765" width="103.610277" height="21.643674" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(143.67272 125.7116)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="20.795373" y="11" textLength="52.01953">Controller</tspan></text><rect x="228.18898" y="34.015748" width="103.610277" height="21.643674" fill="white"/><rect x="228.18898" y="34.015748" width="103.610277" height="21.643674" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(233.18898 37.837586)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="8.229943" y="11" textLength="55.353516">Controller </tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x="63.37252" y="11" textLength="7.330078">T</tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" x="69.37252" y="11" textLength="16.0078125">est</tspan></text><line x1="279.99412" y1="55.659423" x2="222.12998" y2="115.90372" marker-end="url(#StickArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><line x1="190.47786" y1="144.03344" x2="190.47786" y2="151.87115" marker-end="url(#StickArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><rect x="138.67272" y="198.45253" width="103.610277" height="21.643674" fill="white"/><rect x="138.67272" y="198.45253" width="103.610277" height="21.643674" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(143.67272 202.27437)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="25.79049" y="11" textLength="42.029297">Storage</tspan></text><line x1="190.47786" y1="181.81482" x2="190.47786" y2="190.15253" marker-end="url(#StickArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g></g></svg>
diff --git a/src/userguides/images/createtestproject.png b/src/userguides/images/createtestproject.png
new file mode 100644
index 0000000..b365ec6
--- /dev/null
+++ b/src/userguides/images/createtestproject.png
Binary files differ
diff --git a/src/userguides/images/domainmodel.graffle b/src/userguides/images/domainmodel.graffle
new file mode 100644
index 0000000..5ef52c2
--- /dev/null
+++ b/src/userguides/images/domainmodel.graffle
Binary files differ
diff --git a/src/userguides/images/domainmodel.svg b/src/userguides/images/domainmodel.svg
new file mode 100644
index 0000000..b07d97b
--- /dev/null
+++ b/src/userguides/images/domainmodel.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="84 15 339 179" width="339pt" height="179pt" xmlns:dc="http://purl.org/dc/elements/1.1/"><metadata> Produced by OmniGraffle 6.5.1 <dc:date>2016-03-09 17:09:57 +0000</dc:date></metadata><defs><font-face font-family="Helvetica" font-size="3" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="522.94922" cap-height="717.28516" ascent="770.01953" descent="-229.98047" font-weight="500"><font-face-src><font-face-name name="Helvetica"/></font-face-src></font-face><font-face font-family="Helvetica" font-size="11" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="522.94922" cap-height="717.28516" ascent="770.01953" descent="-229.98047" font-weight="500"><font-face-src><font-face-name name="Helvetica"/></font-face-src></font-face><font-face font-family="Helvetica" font-size="12" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="532.22656" cap-height="719.72656" ascent="770.01953" descent="-229.98047" font-weight="bold"><font-face-src><font-face-name name="Helvetica-Bold"/></font-face-src></font-face><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="UMLInheritance_Marker" viewBox="-1 -8 14 16" markerWidth="14" markerHeight="16" color="black"><g><path d="M 12 0 L 0 -7 L 0 7 Z" fill="none" stroke="currentColor" stroke-width="1"/></g></marker></defs><g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"><title>Canvas 1</title><rect fill="white" width="603" height="715"/><g><title>Layer 1</title><rect x="321.73229" y="177.6378" width="99" height="14" fill="white"/><rect x="321.73229" y="177.6378" width="99" height="14" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(326.73229 182.6378)" fill="black"><tspan font-family="Helvetica" font-size="3" font-weight="500" x="0" y="3" textLength=".8334961"> </tspan></text><rect x="321.73229" y="141.6378" width="99" height="36" fill="white"/><rect x="321.73229" y="141.6378" width="99" height="36" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(326.73229 146.6378)" fill="black"><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="10" textLength="50.128418">time: Date</tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="23" textLength="59.307617">place: string</tspan></text><rect x="321.73229" y="117.637796" width="99" height="24" fill="white"/><rect x="321.73229" y="117.637796" width="99" height="24" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(326.73229 122.637796)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="7.506836" y="11" textLength="73.98633">Appointment</tspan></text><rect x="86.456694" y="133.70079" width="99" height="14" fill="white"/><rect x="86.456694" y="133.70079" width="99" height="14" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(91.456694 138.70079)" fill="black"><tspan font-family="Helvetica" font-size="3" font-weight="500" x="0" y="3" textLength=".8334961"> </tspan></text><rect x="86.456694" y="97.70079" width="99" height="36" fill="white"/><rect x="86.456694" y="97.70079" width="99" height="36" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(91.456694 102.70079)" fill="black"><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="10" textLength="41.572266">id: string</tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="23" textLength="56.251465">label: string</tspan></text><rect x="86.456694" y="73.70079" width="99" height="24" fill="white"/><rect x="86.456694" y="73.70079" width="99" height="24" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(91.456694 78.70079)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="31.266602" y="11" textLength="7.330078">T</tspan><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="37.711914" y="11" textLength="20.021484">ask</tspan></text><rect x="321.73229" y="90.59449" width="99" height="14" fill="white"/><rect x="321.73229" y="90.59449" width="99" height="14" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(326.73229 95.59449)" fill="black"><tspan font-family="Helvetica" font-size="3" font-weight="500" x="0" y="3" textLength=".8334961"> </tspan></text><rect x="321.73229" y="41.594488" width="99" height="49" fill="white"/><rect x="321.73229" y="41.594488" width="99" height="49" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(326.73229 46.594488)" fill="black"><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="10" textLength="70.936035">dueDate: Date</tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="23" textLength="66.63379">priority: enum</tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="36" textLength="69.73291">done: boolean</tspan></text><rect x="321.73229" y="17.594488" width="99" height="24" fill="white"/><rect x="321.73229" y="17.594488" width="99" height="24" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(326.73229 22.594488)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="30.282227" y="11" textLength="7.330078">T</tspan><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="36.72754" y="11" textLength="21.990234">odo</tspan></text><path d="M 321.73229 82.84449 L 306.23229 82.84449 L 253.23229 82.84449 L 253.23229 110.70079 L 200.95669 110.70079 L 198.95669 110.70079" marker-end="url(#UMLInheritance_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><path d="M 321.73229 136.1378 L 306.23229 136.1378 L 253.23229 136.1378 L 253.23229 110.70079 L 200.95669 110.70079 L 198.95669 110.70079" marker-end="url(#UMLInheritance_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g></g></svg>
diff --git a/src/userguides/images/exportwizard.png b/src/userguides/images/exportwizard.png
new file mode 100644
index 0000000..6808c0f
--- /dev/null
+++ b/src/userguides/images/exportwizard.png
Binary files differ
diff --git a/src/userguides/images/fibonacciconsole.png b/src/userguides/images/fibonacciconsole.png
new file mode 100644
index 0000000..b86fb64
--- /dev/null
+++ b/src/userguides/images/fibonacciconsole.png
Binary files differ
diff --git a/src/userguides/images/firstlaunch.png b/src/userguides/images/firstlaunch.png
new file mode 100644
index 0000000..1f0118a
--- /dev/null
+++ b/src/userguides/images/firstlaunch.png
Binary files differ
diff --git a/src/userguides/images/firstlaunchconsole.png b/src/userguides/images/firstlaunchconsole.png
new file mode 100644
index 0000000..ab3b337
--- /dev/null
+++ b/src/userguides/images/firstlaunchconsole.png
Binary files differ
diff --git a/src/userguides/images/firsttestresults.png b/src/userguides/images/firsttestresults.png
new file mode 100644
index 0000000..1afa448
--- /dev/null
+++ b/src/userguides/images/firsttestresults.png
Binary files differ
diff --git a/src/userguides/images/helloworldclass.png b/src/userguides/images/helloworldclass.png
new file mode 100644
index 0000000..03abde1
--- /dev/null
+++ b/src/userguides/images/helloworldclass.png
Binary files differ
diff --git a/src/userguides/images/ide.png b/src/userguides/images/ide.png
new file mode 100644
index 0000000..c5194dc
--- /dev/null
+++ b/src/userguides/images/ide.png
Binary files differ
diff --git a/src/userguides/images/injectionwarning.png b/src/userguides/images/injectionwarning.png
new file mode 100644
index 0000000..432c888
--- /dev/null
+++ b/src/userguides/images/injectionwarning.png
Binary files differ
diff --git a/src/userguides/images/newclasswizard.png b/src/userguides/images/newclasswizard.png
new file mode 100644
index 0000000..12f09db
--- /dev/null
+++ b/src/userguides/images/newclasswizard.png
Binary files differ
diff --git a/src/userguides/images/newproject.png b/src/userguides/images/newproject.png
new file mode 100644
index 0000000..a3b4575
--- /dev/null
+++ b/src/userguides/images/newproject.png
Binary files differ
diff --git a/src/userguides/images/newprojectwizard.png b/src/userguides/images/newprojectwizard.png
new file mode 100644
index 0000000..03e2f25
--- /dev/null
+++ b/src/userguides/images/newprojectwizard.png
Binary files differ
diff --git a/src/userguides/images/npmexport.png b/src/userguides/images/npmexport.png
new file mode 100644
index 0000000..ae5163e
--- /dev/null
+++ b/src/userguides/images/npmexport.png
Binary files differ
diff --git a/src/userguides/images/npmtargetfolder.png b/src/userguides/images/npmtargetfolder.png
new file mode 100644
index 0000000..7847d9a
--- /dev/null
+++ b/src/userguides/images/npmtargetfolder.png
Binary files differ
diff --git a/src/userguides/images/outlineview.png b/src/userguides/images/outlineview.png
new file mode 100644
index 0000000..59f25e7
--- /dev/null
+++ b/src/userguides/images/outlineview.png
Binary files differ
diff --git a/src/userguides/images/projectexplorer.png b/src/userguides/images/projectexplorer.png
new file mode 100644
index 0000000..187931d
--- /dev/null
+++ b/src/userguides/images/projectexplorer.png
Binary files differ
diff --git a/src/userguides/images/quickfixnpminstall.png b/src/userguides/images/quickfixnpminstall.png
new file mode 100644
index 0000000..e56dd0f
--- /dev/null
+++ b/src/userguides/images/quickfixnpminstall.png
Binary files differ
diff --git a/src/userguides/images/runhello.png b/src/userguides/images/runhello.png
new file mode 100644
index 0000000..29e913f
--- /dev/null
+++ b/src/userguides/images/runhello.png
Binary files differ
diff --git a/src/userguides/images/startupprefs.png b/src/userguides/images/startupprefs.png
new file mode 100644
index 0000000..232f4b8
--- /dev/null
+++ b/src/userguides/images/startupprefs.png
Binary files differ
diff --git a/src/userguides/images/storage.graffle b/src/userguides/images/storage.graffle
new file mode 100644
index 0000000..e7658cf
--- /dev/null
+++ b/src/userguides/images/storage.graffle
Binary files differ
diff --git a/src/userguides/images/storage.svg b/src/userguides/images/storage.svg
new file mode 100644
index 0000000..2884914
--- /dev/null
+++ b/src/userguides/images/storage.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="109 24 413 139" width="413pt" height="139pt" xmlns:dc="http://purl.org/dc/elements/1.1/"><metadata> Produced by OmniGraffle 6.5.1 <dc:date>2016-03-09 17:59:16 +0000</dc:date></metadata><defs><font-face font-family="Helvetica" font-size="12" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="532.22656" cap-height="719.72656" ascent="770.01953" descent="-229.98047" font-weight="bold"><font-face-src><font-face-name name="Helvetica-Bold"/></font-face-src></font-face><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="UMLInheritance_Marker" viewBox="-1 -8 14 16" markerWidth="14" markerHeight="16" color="black"><g><path d="M 12 0 L 0 -7 L 0 7 Z" fill="none" stroke="currentColor" stroke-width="1"/></g></marker><font-face font-family="Helvetica" font-size="11" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="522.94922" cap-height="717.28516" ascent="770.01953" descent="-229.98047" font-weight="500"><font-face-src><font-face-name name="Helvetica"/></font-face-src></font-face><font-face font-family="Helvetica" font-size="10" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="522.94922" cap-height="717.28516" ascent="770.01953" descent="-229.98047" font-weight="500"><font-face-src><font-face-name name="Helvetica"/></font-face-src></font-face></defs><g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"><title>Canvas 1</title><rect fill="white" width="603" height="715"/><g><title>Layer 1</title><rect x="378.4252" y="52.440945" width="141.519685" height="24" fill="white"/><rect x="378.4252" y="52.440945" width="141.519685" height="24" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(383.4252 57.440945)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="15.082108" y="11" textLength="101.35547">StorageInMemory</tspan></text><rect x="378.4252" y="112.13386" width="141.519685" height="24" fill="white"/><rect x="378.4252" y="112.13386" width="141.519685" height="24" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(383.4252 117.13386)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="15.096757" y="11" textLength="101.32617">StorageMongoDB</tspan></text><path d="M 378.4252 64.440945 L 362.9252 64.440945 L 327.9252 64.440945 L 327.9252 93.929134 L 293.08268 93.929134 L 291.08268 93.929134" marker-end="url(#UMLInheritance_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1" stroke-dasharray="4,4"/><path d="M 378.4252 124.13386 L 362.9252 124.13386 L 327.9252 124.13386 L 327.9252 93.929134 L 293.08268 93.929134 L 291.08268 93.929134" marker-end="url(#UMLInheritance_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1" stroke-dasharray="4,4"/><rect x="111.968505" y="85.929134" width="165.61417" height="75" fill="white"/><rect x="111.968505" y="85.929134" width="165.61417" height="75" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(116.968505 90.929134)" fill="black"><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="10" textLength="44.617676">size(): int</tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="23" textLength="31.168457">clear()</tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="36" textLength="22.010742">getT</tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="20.791504" y="36" textLength="28.72998">asks: </tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="48.919922" y="36" textLength="39.423828">Array<T</tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="87.12451" y="36" textLength="23.541504">ask></tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="49" textLength="31.173828">storeT</tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="29.95459" y="49" textLength="47.066895">ask(task: </tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="76.828125" y="49" textLength="6.7192383">T</tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="82.328125" y="49" textLength="53.791504">ask): string</tspan><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="62" textLength="84.379883">isEmpty: boolean</tspan></text><rect x="111.968505" y="62.929134" width="165.61417" height="23" fill="white"/><rect x="111.968505" y="62.929134" width="165.61417" height="23" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(116.968505 67.929134)" fill="black"><tspan font-family="Helvetica" font-size="11" font-weight="500" x="0" y="10" textLength="3.0561523"> </tspan></text><rect x="111.968505" y="26.929134" width="165.61417" height="36" fill="white"/><rect x="111.968505" y="26.929134" width="165.61417" height="36" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(116.968505 31.929134)" fill="black"><tspan font-family="Helvetica" font-size="10" font-weight="500" x="53.068317" y="10" textLength="49.47754">«interface»</tspan><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="55.46822" y="23" textLength="44.677734">Storage</tspan></text></g></g></svg>
diff --git a/src/userguides/images/testinnodejs.png b/src/userguides/images/testinnodejs.png
new file mode 100644
index 0000000..b53bcd8
--- /dev/null
+++ b/src/userguides/images/testinnodejs.png
Binary files differ
diff --git a/src/userguides/index.adoc b/src/userguides/index.adoc
new file mode 100644
index 0000000..fc5a458
--- /dev/null
+++ b/src/userguides/index.adoc
@@ -0,0 +1,113 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+
+[discrete]
+.N4JS Userguides
+= N4JS Userguides
+:doctype: book
+:notitle:
+
+
+== FAQ
+
+Find concise answers for the most frequently asked questions about the Eclipse N4JS project.
+
+[horizontal]
+<<../faq/index.adoc#faq,Frequenctly Asked Questions>> :: Common N4JS topics such as Open-Sourcing, JavaScript, Java and Typescript Comparison.
+<<../faq/comparison-java.adoc#n4js-and-java,N4JS & Java Comparison>> :: A comparison between the features of N4JS and Java.
+<<../faq/comparison-typescript.adoc#n4js-and-typescript,N4JS & Typescript Comparison>> :: A comparison between the features of N4JS and Typescript.
+
+---
+
+== Features
+
+The link:../features/index.html[Feature Table] describes the state of all current N4JS Language and IDE features.
+For specifics on each feature described here, see their respective feature pages:
+
+[horizontal]
+link:../features/async-await.html[Async/Await] :: Learn about the benefits of asynchronous data flows and how they work with N4JS code.
+link:../features/dependency-injection.html[Dependency Injection] :: Configure dependencies between classes with built-in Dependency Injection support.
+link:../features/generics.html[Generics] :: N4JS Generics look similar to Java's generics with some differences that are illustrated in this article.
+link:../features/modules.html[Modules] :: Modules help keep code well-defined and easy to comprehend. Read about keeping large projects maintainable with Module support within the N4JS IDE.
+link:../features/nodejs-support.html[Node.js Support] :: Seamless integration of N4JS projects with existing node.js-based environments.
+link:../features/nominal-and-structural-typing.html[Nominal vs. Structural Typing] :: N4JS provides both forms of typing. Read the feature on how they are combined in N4JS.
+link:../features/testing.html[Test Support] :: The N4JS IDE and the built-in test execution runtime Mangelhaft were designed from the ground-up to support Test Driven Development. Explore how testing with N4JS will help ensure your projects behave as expected.
+
+---
+
+== Tutorials
+
+=== IDE Setup & HelloWorld!
+
+This short introduction covers the basics of getting up and running with the
+N4JS IDE. From installation to running HelloWorld!, quickly learn about new features
+of the N4JS IDE, how to create a new project, manage workspaces and begin development!
+
+
+[horizontal]
+<<n4js-ide-setup.adoc#n4js-ide-setup,N4JS IDE Setup Guide>> :: Basic installation and setup instructions.
+
+
+=== npm Export Guide
+
+The npm Export Guide briefly covers the essentials of Node.js development. A simple
+code example is written and exported from the N4JS IDE as an npm package, run from
+the command line and published to the npm registry. Quickly learn how to streamline Node.js development
+using the N4JS IDE.
+
+[horizontal]
+<<npm-export-guide.adoc#npm-export-guide,npm Export Guide>> :: Basic npm export and publishing instructions.
+
+
+=== In-Depth Tutorial
+
+Using the built-in example projects as a reference, this in-depth tutorial covers the most important tools and features
+of the N4JS IDE. The example project is explained as a domain model and built step-by-step.
+New features of the N4JS IDE are introduced along the way such as *modules*, *type annotations*,
+*dependency injection*, *testing* with an example test project and more.
+
+[horizontal]
+<<tutorial.adoc#tutorial,In-Depth Tutorial>> :: Begin using the more powerful features N4JS has to offer!
+
+---
+
+== Specification
+
+=== N4JS Language Specification
+
+For a complete reference of the N4JS Language, the Specification is available at the following location:
+
+* link:https://www.eclipse.org/n4js/spec/index.html[N4JS Language Specification]
+
+=== N4JS IDE Specification
+
+For a reference of the N4JS IDE, i.e. the specific views and UI features of the Eclipse based IDE, the Specification is available at the following location:
+
+* link:https://www.eclipse.org/n4js/idespec/index.html[N4JS IDE Specification]
+
+=== N4JS Design Documentation
+
+The design and other internal information valuable for contributors to Eclipse N4JS can be found at the following location:
+
+* link:https://www.eclipse.org/n4js/design/index.html[N4JS Design Documentation]
+
+== Release Notes
+
+Information on the current state of the N4JS Language and IDE including details of known issues and upcoming features that are under development.
+
+* link:../releases/index.html[Eclipse N4JS Release Notes]
+
+=== Copyright Information
+
+* <<license.adoc#license,License>>
+
+
diff --git a/src/userguides/license.adoc b/src/userguides/license.adoc
new file mode 100644
index 0000000..869556e
--- /dev/null
+++ b/src/userguides/license.adoc
@@ -0,0 +1,37 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+:doctype: book
+:toc: right
+:toc-title: Jump to topic:
+
+.License
+= N4JS License
+
+The section states the license of the N4JS Eclipse Plugin.
+
+== EPL 1.0
+
+December 14, 2008
+
+The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise
+indicated below, the Content is provided to you under the terms and conditions of the
+Eclipse Public License Version 1.0 ("EPL").
+
+A copy of the EPL is available at http://www.eclipse.org/legal/epl-v10.html.
+For purposes of the EPL, "Program" will mean the Content.
+
+If you did not receive this Content directly from the Eclipse Foundation, the Content is
+being redistributed by another party 'Redistributor' and different terms and conditions may
+apply to your use of any object code in the Content. Check the Redistributor's license that was
+provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise
+indicated below, the terms and conditions of the EPL still apply to any source code in the Content
+and such source code may be obtained at http://www.eclipse.org
diff --git a/src/userguides/n4js-ide-setup.adoc b/src/userguides/n4js-ide-setup.adoc
new file mode 100644
index 0000000..822cb95
--- /dev/null
+++ b/src/userguides/n4js-ide-setup.adoc
@@ -0,0 +1,208 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+:doctype: book
+:toc: right
+:toc-title: Jump to topic:
+:commandkey: ⌘
+
+.N4JS IDE Setup
+= N4JS IDE Setup
+
+
+
+*Get the most from type safe development with the custom-built N4JS IDE*
+
+In order to fully utilize the strengths of the language, N4JS has its own Eclipse-based IDE
+with custom features designed to support safe and intuitive development of large-scale
+server-side applications.
+Code is validated as you type and workflow tools such as content assist
+and quick-fixes ensure applications are written safely and consistently. The N4JS IDE
+is a powerful tool for developing
+collaborative projects that are to be maintained over a long period of time.
+
+
+== Installation
+
+For all available options for downloads and installation steps using the Eclipse Installer, see the link:https://www.eclipse.org/n4js/downloads.html[download page].
+
+
+=== Requirements
+
+*Java 11*
+
+In order to run the N4JS IDE, Java 11 is required. Note that there exists a version of the IDE which
+includes an embedded JRE-11. Java installer packages can be downloaded from
+http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html[Oracle's Java pages].
+For Mac OS X users: Always install the *JDK* - the JRE is installed
+and only used in web browsers, not applications.
+
+*Existing Eclipse installation*
+
+When installing the N4JS features into an existing Eclipse installation, Xtext 2.9.1 must be available.
+In general, N4JS is based on the Eclipse Mars release.
+
+*node.js*
+
+In order to run or test code from the IDE, https://nodejs.org/en/[node.js 6] (or later) is required.
+
+== Launching the IDE
+
+image::images/startupprefs.png[]
+
+When launching the N4JS IDE, a dialog box allows to specify a workspace which is used to
+organize related projects in a single folder.
+A new name and location for the workspace can be selected but for this example we shall
+use the default settings.
+
+TIP: To manage the workspaces that are displayed in the workspace launcher,
+navigate to menu:Preferences[Startup and Shutdown,Workspaces]
+
+
+*N4JS IDE Overview*
+
+image::images/ide.png[]
+
+Developers who have previous experience using Eclipse will be familiar with many common UI
+features such as the Editor, Project Outline, Project Explorer and Console views.
+The arrangement of views can be easily selected using the perspectives icons as highlighted
+in the upper-right of the window as shown above.
+
+
+== Creating a new project[[new_project]]
+
+After having set up a default workspace, a new project can be created using the New N4JS
+Project wizard which is accessed at menu:File[New,N4JS Project] (Or using the keyboard shortcuts
+kbd:[{commandkey}+ Option + N] for Mac,
+kbd:[Alt-Shift-N] on Windows)
+
+image::images/newproject.png[]
+
+In this case, we name the project "hello.world" and select kbd:[Finish] to create a project in the
+default location (our current workspace).
+The New N4JS Project wizard will also ask to specify a working set to include the project in.
+Working sets are for grouping together elements to be displayed and will allow the user to
+focus on specific projects and files without
+switching between workspaces. At this point, it is not necessary to add working sets, but when
+dealing with
+multiple projects, working sets can be a highly efficient way of switching between related
+projects and resources.
+
+
+=== Project Explorer
+
+The Project Explorer view will display the structure of our new project:
+
+image::images/projectexplorer.png[]
+
+In the Project Explorer view, our project "hello.world" contains three folders with our resources:
+
+* *src* will contain our .n4js source files.
+* *src-gen* will contain the transpiled JavaScript that is generated after compiling n4js files.
+The IDE automatically transpiles n4js files on save.
+* *manifest.n4mf* is the project description file which contains descriptions of dependencies.
+
+
+
+== Creating a new class[[creating_classes]]
+
+In our new N4JS project, we can use the New N4JS Class wizard (accessed at *menu:File[New,N4JS Class]*
+or kbd:[{commandkey} + Option + n])
+to create a new class called "HelloWorld":
+
+
+image::images/helloworldclass.png[]
+
+
+Let's have a look at what a simple *HelloWorld!* example looks like in N4JS:
+
+[source,n4js]
+.HelloWorld.n4js
+----
+export public class HelloWorld {
+ public say_hi() {
+ var message: string = "Hello World!";
+ console.log(message);
+ }
+}
+var announce = new HelloWorld();
+announce.say_hi();
+----
+
+We can see some similarities with Java and JavaScript in this example, but with some notable features:
+
+* *export* makes the HelloWorld class available for import in another file or project.
+We modify this using the *public* keyword to specify where it is available. This demonstrates
+the use of *modules*
+inside N4JS which are fully explained in the <<../features/modules#modules,Modules>> feature
+
+* *string* we use the type annotation +string+ to define that the +message+ variable is of type *string*.
+More can be read about type annotations in the <<../features/nominal-and-structural-typing#nominal_and_structural_typing,Nominal vs. Structural Typing>> feature.
+
+
+As we have used the export keyword and made the class public using the +public+ *access modifier*,
+it is possible to call the methods of this class in another project. If we wanted to restrict access
+to this element, we would use +protected+
+so it may only be accessed from subclasses and +private+ for within the same module only.
+The default visibility of an element is +project+.
+
+If we create a new class and define it as follows:
+
+[source,n4js]
+.HelloCaller.n4js
+----
+import { HelloWorld } from "HelloWorld";
+
+export public class Caller {
+ public call () {
+ var c = new HelloWorld;
+ return c;
+ }
+}
+----
+
+
+We can run this module named "HelloCaller" and invoke the methods from our HelloWorld class.
+
+
+== Outline View[[outline_view]]
+
+
+The Outline View is a useful tool that provides a quick overview of the structure of our applications.
+If we look at the Outline View while we are editing our HelloWorld examples, we can see the following:
+
+image::images/outlineview.png[]
+
+The Outline View displays the structure of our very basic class with only one method. As
+projects become more populated
+and increase in complexity, the
+Outline View becomes helpful by assisting with navigating through the structure of a file.
+
+TIP: Instead of having the Outline View always open in the IDE, the shortcut kbd:[{commandkey}+O]
+will open a Quick Outline window on demand. With this Quick Outline window open, begin typing to
+easily search for fields, methods and classes.
+
+== Running as node.js
+
+To run this file, right-click inside the editor view and select *Run as | Launch in Node.js*:
+
+image::images/runhello.png[]
+
+The Console View will display the result of our +console.log+ command, and our Hello World!
+example is running in the N4JS IDE without
+errors.
+
+
+== What's Next?
+
+After creating a project and running some sample code, the next step we can have a look at is
+exporting our project as an npm package followed by running it from the command line and
+publishing to the npm registry. This is covered in the <<npm-export-guide#_npm_export_guide, export to npm>> guide.
diff --git a/src/userguides/npm-export-guide.adoc b/src/userguides/npm-export-guide.adoc
new file mode 100644
index 0000000..31e87c4
--- /dev/null
+++ b/src/userguides/npm-export-guide.adoc
@@ -0,0 +1,221 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+:toc: right
+:toc-title: Jump to section:
+:commandkey: ⌘
+
+
+.N4JS npm Export Guide
+= N4JS npm Export Guide
+
+N4JS was created with the intention of supporting safe and intuitive Node.js development.
+When a Node application
+is ready to be published, the default
+package manager is npm which is bundled with Node.js (a prerequisite of the N4JS IDE). npm is run on the
+command
+line and will organise and install
+dependencies for an application. npm can also be used to install Node.js applications available on the npm
+registry. This npm export guide demonstrates how N4JS can be used to develop and publish Node
+applications with a simple example module.
+
+
+== Project Example
+
+In order to demonstrate exporting as npm, we can begin by creating a new N4JS
+Project using the keyboard shortcut kbd:[{commandkey} + N] and naming
+it "fibonacci". We then create a class "Fibonacci" and define it as follows:
+
+[source,n4js]
+.Fibonacci.n4js
+----
+ export public class Fibonacci {
+ public seq() {
+ var arr = [];
+ var a = 0;
+ var b = 1;
+ for (var n = 1; n < 15; n++) {
+ var current = a + b;
+ arr.push(current);
+ a = b + a;
+ b = a - b;
+ }
+ console.log(arr);
+ }
+}
+var run = new Fibonacci();
+run.seq();
+----
+
+
+In the above example, we are creating a function which will iterate through the Fibonacci sequence,
+push each new value into an array and report the results in the console after the for loop is complete.
+When right-clicking the module and selecting menu:Run as[Launch in node.js], we have the
+following output in the console:
+
+image::images/fibonacciconsole.png[]
+
+
+
+== Exporting as npm
+
+
+To export our Fibonacci example, navigate to the Project
+Explorer view, right-click our Fibonacci.n4js file or the project name and select *Export*.
+An Export wizard will list the available types of exports.
+Select *N4JS npm export* in the *N4JS Exports* folder.
+
+
+image::images/exportwizard.png[]
+
+On the following screen, we can select a target folder and click "Finish" to complete the export. There is
+an option to compress the files on export which will create a tarball.
+
+
+image::images/npmtargetfolder.png[]
+
+
+If we have a look in the target folder, we can see that a new folder has been created which is our
+exported package. The contents of the package are:
+
+* *Fibonacci.js* the Fibonacci.n4js file transpiled to JavaScript.
+* *package.json* npm package description (name, author, version etc.) which is described in detail below.
+* *manifest.n4mf* N4JS project dependencies.
+* *Fibonacci.map* contains debugging information.
+* *src* folder containing the original Fibonacci.n4js file.
+
+== Running from the Command Line
+
+In the example so far, we exported our npm package to a folder on the desktop called "npm". We create
+a folder called *newinstall* located at `User/bsmith/Desktop/npm/newinstall`, but this can be anywhere
+outside of the exported project folder.
+
+With a Terminal window, cd to our new folder:
+[source]
+$ cd /User/Desktop/npm/newinstall
+
+and install the package
+[source]
+$ npm install ../fibonacci
+
+
+All dependiencies required for running the package will then be downloaded and installed
+to the "newinstall" folder
+
+[source,text]
+/User/Desktop/npm/newinstall
+└─┬ fibonacci@ 0.0.1
+└─┬ n4js-node@ 0.3.1
+├── n4js-es5@ 0.3.0
+├─┬ node-fetch@ 1.4.1
+│ ├─┬ encoding@ 0.1.12
+│ │ └── iconv-lite@ 0.4.13
+│ └── is-stream@ 1.0.1
+└─┬ systemjs@ 0.19.25
+└── when@ 3.7.7
+
+
+We can now create a new JavaScript file saved as "index.js" that calls the method in our package. In our
+case, the index.js only needs to contain the following line
+
+[source,javascript]
+.index.js
+var fib = require("fibonacci/Fibonacci");
+
+Our example module can now be called if we run the index.js file from the command line with node:
+
+[source]
+----
+$ node index.js
+[ 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610 ]
+$
+----
+
+If we wanted to run this node module by itself without the use of the index.js file, we can use the command
+
+[source]
+$ node -r fibonacci/Fibonacci
+
+
+
+== Modifying Package Info
+
+In our exported npm project, a package.json file is created from the project *manifest* which contains
+information about the package. The minimum information required for a package.json file is:
+
+
+* *name* of the package (all lowercase, one word, no spaces, dashes and underscores allowed).
+* *version* following https://docs.npmjs.com/getting-started/semantic-versioning[semver conventions] i.e.
+*1.0.0*.
+
+
+Let's say we wanted to change the version of our npm package, we can edit this in the manifest.n4mf file
+in the root of our fibonacci project:
+
+[source,n4mf]
+.manifest.n4mf
+----
+ProjectId: fibonacci
+ProjectType: library
+ProjectVersion: 1.2.3
+VendorId: eu.mycompany
+VendorName: "MyCompany AG"
+Output: "src-gen"
+Sources {
+ source {
+ "src"
+ }
+}
+----
+
+Above, we have made the simple change of our project from version "0.0.1" (the default) to "1.2.3"
+and the package.json file will contain our new version number the next time we export as npm.
+
+=== Editing the package.json from the Command Line
+
+It's possible to edit the package.json from the command line by using `npm init` which is normally
+used to create a new package:
+
+[source]
+$ cd /User/brian.smith/Desktop/npm/fibonacci
+$ npm init
+
+
+This will load a questionnaire that will cycle through the attributes of your existing package and
+update the *package.json* file if new information is provided.
+
+NOTE: It is recommended to edit the package information via the manifest.n4mf
+file within the N4JS IDE as exporting the project again will overwrite changes made to the package.json
+via the command line.
+
+
+== Publishing to npm
+
+
+In order to publish to npm, you must have an account on the npm registry. To store your credentials on the
+client:
+
+[source]
+$ npm login
+
+
+If you do not already have an account, use `npm adduser` to
+create a new account. Test that your credentials are stored on the client with *npm config ls.
+
+To publish our exported npm package, cd to the package and use the command `npm publish`
+
+[source]
+$ cd /Users/brian.smith/Desktop/npm/fibonacci
+$ npm publish
+
+
+We can now check if our package has been published to the registry, in our case, it would be published
+at *https://npmjs.com/package/fibonacci*
diff --git a/src/userguides/tutorial.adoc b/src/userguides/tutorial.adoc
new file mode 100644
index 0000000..a226bb1
--- /dev/null
+++ b/src/userguides/tutorial.adoc
@@ -0,0 +1,1334 @@
+////
+Copyright (c) 2016 NumberFour AG.
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License v1.0
+which accompanies this distribution, and is available at
+http://www.eclipse.org/legal/epl-v10.html
+
+Contributors:
+ NumberFour AG - Initial API and implementation
+////
+
+:toc: right
+:toc-title: Jump to topic:
+:commandkey: ⌘
+:bib-file: ../../res/n4js.bib
+
+.N4JS Tutorial
+= N4JS Tutorial
+
+*The flexibility of JavaScript with the type safety of Java*
+
+N4JS is a language and IDE designed for developers who need to build scalable projects whose code should be
+modular, reusable and easily maintainable over time. N4JS bridges the strengths of ECMAScript
+(also known as JavaScript) and Java. The result is a typed JavaScript superset that is dynamic,
+flexible and type-safe.
+
+*Experience with JavaScript or Java?*
+
+Developers who are experienced with JavaScript can easily apply their knowledge in N4JS. As N4JS is a
+typed superset of ECMAScript, it is possible to use plain ECMAScript in N4JS. Most of the important
+features from ECMAScript 2015 are supported, such as *modules* with import and export,
+*classes*, *iterables* and *destructuring* of arrays
+and objects. Developers with Java experience will be familiar with features from Java 8
+such as *nominal typing*, *interfaces* and *generic classes
+and methods*; even dependency injection and testing look similar.
+
+*Development Environment*
+
+N4JS has an IDE based on Eclipse. It comes with its own workspace, libraries and plugins. The
+IDE has a transpiler (i.e. a compiler that translates from one language to another) which validates
+N4JS code and then transforms it to JavaScript. The transpiler also performs imports from ECMAScript
+to N4JS. The benefit of type safety means that errors in code are noticed while editing in the
+IDE, allowing for problem-solving before code is ever deployed.
+
+Developers who have previous experience using Eclipse will be familiar with most of the common UI features
+such as Editor, Project Outline, Project Explorer and Console views. The arrangement of views
+can be easily selected using the perspectives icons as highlighted in the upper-right of the window.
+
+== Using N4JS to Implement a Node.js Application
+
+The following screenshot shows
+the most important views of the IDE:
+
+
+image::images/ide.png[N4JS IDE, title="N4JS IDE"]
+
+In order to illustrate some of the features of N4JS, we shall look at building a Node.js-based
+server of a Task Manager which serves as a reminder or to-do list application. As we build this
+basic example, we shall add improvements step-by-step, introducing new features with each
+increment in order to demonstrate some of the strengths of the language and IDE through a
+simple practical model.
+
+Before we dive in and start creating our example, it is worth briefly describing the architecture
+of our application in order to have a considered approach to the concept. In this particular
+example, we can think of a multi-tiered client-server structure. The idea here is that when we
+have the application separated, each tier can be reused for different purposes.
+
+image::images/architecture.svg[Architecture]
+
+We will start with modeling and implementing the domain model before implementing a first
+version of the storage tier which will enable our first tests. The controller is then built
+using a test-driven approach. We later improve the storage tier using a real database
+before adding a REST API with http://expressjs.com/[Express] and, finally, a simple Web UI.
+
+== Creating a new N4JS Project
+
+Let's begin by creating a new N4JS Project that contains our whole application. In case of
+larger applications, we might want to create projects for each component (or tier) of the
+application. In order to keep this example small, we will use only one project.
+
+The "New N4JS Project" wizard can be accessed at menu:File[New, N4JS Project] (Or using the
+keyboard shortcuts kbd:[{commandkey} + n] for Mac, kbd:[Alt+Shift+n] on Windows)
+
+image::images/newprojectwizard.png[New Project Wizard, 700]
+
+When we select kbd:[Finish], a new project folder is created with the following content:
+
+* folder *src*: contains the .n4js source files for the project.
+* folder *src-gen*: contains the transpiled JavaScript that is generated after compiling n4js
+files. The IDE automatically transpiles n4js files on save.
+* *manifest.n4mf*: project description file, containing description of dependencies.
+
+=== The Domain Model
+
+Before we start implementing the domain model, we shall take a look at a UML diagram of it:
+
+image::images/domainmodel.svg[]
+
+The UML diagram illustrates how the entities of our domain model are related
+and which features the classes of the model will have.
+We will begin by defining Task which is extended by Appointment and Todo.
+
+=== Creating new classes and modules
+
+In our new N4JS project, we can begin creating our entities. The easiest way to
+do this is to utilize the New N4JS Class wizard, accessed via menu:File[New,N4JS Class]
+
+image::images/newclasswizard.png[, 700]
+
+N4JS supports modules introduced by ECMAScript 2015. A module contains functions,
+classes and other declarations and code. The declared elements can be exported
+and imported by other modules. We will use a single module for all classes of our
+domain model. In larger projects, one might follow the Java convention to create
+a single file per class.
+
+The module specifier is the full path name of the module file, relative to the source
+folder. We use Unix-like path separators, that is forward slashes "/". In the Class
+Wizard (and later in import statements) we will omit the file extension.
+
+In the above figure, we are creating a new class named Task which will be saved in
+the module *model* in the project source folder.
+
+==== Implement the entity classes
+
+The class wizard has already created a file and the empty class "Task". We will
+manually enhance this class as follows:
+
+[source, n4js]
+----
+export abstract class Task { // <1>
+ public id: string?;
+ public label: string?;
+}
+----
+
+<1> In the first line of code, we have defined an *abstract class* named Task. Classes in
+N4JS are similar to classes in ECMAScript 2015 or Java. The concept of an abstract
+class is borrowed from Java. This means that we cannot have a _direct instance_
+of Task in our model, but we may have _subclasses_ of Task.
+
+We are populating the class with fields which are simple data fields of the class. This
+is also borrowed from Java. The transpiler will move the field (with possible
+initializers) into the constructor. The two data fields of Task are +id+ and +label+
+which we have annotated with types. The N4JS transpiler will later remove these type annotations.
+
+The type annotations declare the type of the data field. The type checker will issue
+errors if we later assign values of a non-compatible type to the variables. The question
+mark +?+ is a *type modifier* declaring the value as optional. That means that a new Task
+may or may not have values assigned for their +id+ and +label+.
+
+N4JS also provides the concept of *access modifiers* similar to Java with the modifiers
++public+, +protected+, +project+ and +private+. Access modifiers constrain the visibility
+of elements, that is, they restrict from where an element can be accessed.
+
+* `public` means that the element can be accessed from everywhere,
+* `protected` may only be accessed from subclasses,
+* `project` only from within the project (this is the default visibility)
+* `private` accessed only from within the same module.
+
+We now manually add two classes to the same file:
+
+[source, n4js]
+.model.n4js
+----
+/** An appointment. */ // <1>
+export class Appointment extends Task { // <2>
+ public time: Date; // <3>
+ public place: string; // <3>
+}
+
+export class Todo extends Task {
+ public dueDate: Date?;
+ public done = false; // <4>
+}
+----
+
+<1> Appointment is prefaced with a *JSDoc* annotation (a comment beginning with pass:[/**] and
+closed with pass:[*/] which documents that it is a single Appointment task. JSDoc comments are
+used to provide markup annotation of your code. The content of these comments is displayed when
+you hover over a reference to that element.
+<2> The class Appointment is a *subclass* of Task. This is achieved by using the keyword
++extends+ and demonstrates *inheritance*. N4JS supports single class inheritance similar
+to ECMAScript 2015 or Java. The subclass Appointment will inherit the members
++id+ and +label+ with types from Task.
+<3> We add the members +time+ and +place+ with *type annotations*. The
+type annotations of the members in Appointment are more strict than before, since
+the optional modifier (denoted by the question mark) is missing. We will see the effects
+of these different modifiers later on.
+<4> Class Todo has a data field without type annotation but with an *initializer*. The N4JS
+type checker can infer the type of the initializer, in this case a boolean literal,
+and implicitly sets the type of the field to boolean.
+
+In all classes we have defined above, we are using the ECMAScript 2015 +export+
+keyword so that Appointment and Task can be imported and reused in other modules.
+As the project grows, the benefits of having individual, reusable *modules* become
+more and more useful in that they can be imported into other modules or even other projects.
+
+
+=== Add an Enumeration
+
+
+We also want to add a priority field to the `Todo` class. We will modify the
+`Todo` class and add a new type `Priority` as follows:
+
+[source, n4js]
+.model.n4js (cntd.)
+----
+export class Todo extends Task {
+ public dueDate: Date?;
+ public priority = Priority.NORMAL;
+ public done = false;
+}
+
+@StringBased // <1>
+export enum Priority {
+ LOW, NORMAL, HIGH
+}
+----
+<1> Use string-based `enum` to simplify (de-)serialization
+
+Enumerations allow us to represent a fixed set of constants: `LOW`, `NORMAL` and `HIGH`.
+The reason we use an enumeration here is because we know all possible values for Priority
+at compile-time so we may limit it to these constants. N4JS provides two kinds of
+enumerations: "ordinary" and "string-based". The former
+will be translated to objects, enabling extended reflection (for example to get the type of
+the enumeration or get all literals). The latter will be translated to strings. Literals of
+string-based enumerations are, in fact, represented as plain strings in the JavaScript
+output code. As a result, they offer less reflection capabilities.
+
+
+=== The Storage Layer
+
+Let's first have a look at the UML diagram describing out storage tier:
+
+image::images/storage.svg[]
+
+The storage tier is responsible for persisting our entities. We will create two
+different kinds of "persistence". We will start with a simple in-memory peristence,
+which can be used for testing. Later on, we will add a proper persistence layer using MongoDB.
+
+==== Defining an Interface
+
+We can create the storage module with the New Class wizard.
+We call it "Storage.n4js", following Java's convention of naming the module similar
+to the contained class or interface. We will manually edit the file as follows:
+
+[source, n4js]
+.Storage.n4js
+----
+import { Task } from "model"
+
+export public interface Storage {
+
+ size(): int
+ clear()
+
+ getTasks(): Array<Task>
+ storeTask(task: Task): string
+
+ isEmpty(): boolean {
+ return (this.size()) === 0;
+ }
+}
+
+----
+
+
+The very first line of code displays ECMAScript 2015's import statement.
+It is a so-called "named import": We import the element "Task", in
+our case a class, from the module with the specifier "model".
+
+This time, we do not define a class but an interface "Storage". N4JS
+supports *interfaces* which operate similar to those in Java 8. Interfaces
+are similar to classes, but they cannot be instantiated. In N4JS it is
+however possible to use the "instanceof" operator with interfaces. Usually
+interfaces contain abstract methods, but they can contain data fields,
+getters and setters as well. Similar to Java 8, interface methods can
+provide a default implementation. Here, we provide a default implementation for the method +isEmpty+.
+Classes implementing the interface can either rely on the default
+implementation or provide a more efficient one. As in Java, a class
+can implement multiple interfaces, and also interfaces can extend multiple interfaces.
+
+=== Implement the Interface
+
+Since we cannot instantiate an interface, we need a class implementing the
+interface. We will create a new module for a class called "StorageInMemory.n4js".
+This module will simply keep all entities in memory. If you copy-paste the
+following code snippet in your IDE, you will see a few errors. Do not fret,
+it is expected and we will deal with them shortly.
+
+[source, n4js]
+.StorageInMemory.n4js
+----
+import { Storage } from "Storage"
+import { Task } from "model"
+
+export class StorageInMemory implements Storage { // <2>
+
+ private lowestUnusedId = 1;
+ @Final
+ private tasks = new Map<string,Task>(); // <1>
+
+ @Override
+ public size(): int {
+ return this.tasks.size;
+ }
+
+ @Override
+ public storeTask(task: Task): string {
+ let id = 'id' + this.lowestUnusedId++;
+ this.tasks.set(id, task);
+ task.id = id;
+ return id;
+ }
+
+ @Override
+ public clear() {
+ this.lowestUnusedId = 1;
+ this.tasks.clear();
+ }
+
+ @Override
+ public getTasks(): Array<Task> {
+ return Array.from(this.tasks.values());
+ }
+}
+----
+
+<1> The IDE will show an error here!
+
+<2> We use the keyword +implements+ (known from Java) to define that this class implements
+the interface. We have to provide specific implementation of the methods of the Storage
+interface by using the `@Override` annotation to define `size`, `clear`, `getTasks`
+and `storeTasks` (not all methods are shown here). This annotation is similar to
+the annotation used in Java. It ensures that whenever a method in the interface is
+changed, the type checker can issue a warning. This can be a lifesaver when larger
+projects are to be maintained over time or across several development teams.
+
+The above code will raise a compile error because type `Map` is not available
+in ECMAScript Version 5. We'll have to tell N4JS that our example is intended
+to run as ECMAScript 2015. Before doing this in the following section, let's
+first look at the other parts of the above class declaration in more detail.
+
+We use a data field `tasks` to store all the tasks in a map. The type Map stems from
+ECMAScript 2015. It is a generic type similar to Array, which the observant reader may
+have already seen in the Storage interface. N4JS provides support for generic types and methods
+is similar to Java 8.
+
+=== Edit the Manifest
+
+By default, N4JS provides all the types known by ECMAScript 5. In order to use elements
+(types, functions or variables) defined by a newer JavaScript version, we have to add
+a corresponding runtime library as project dependency to the manifest. This has no direct
+effect on the compiled code, it simply tells the type checker to assume that certain
+types of a newer JavaScript version will be available at runtime (provided by the JavaScript
+engine the code is intended for).
+
+Such meta information about an N4JS project is kept in a so-called *manifest file*.
+We need to open the `manifest.n4mf` file and edit a dependency. The default manifest
+files created by the New Project wizard look like the following:
+
+[source,n4mf]
+.manifest.n4mf
+----
+ProjectId: n4js.example.tasks
+ProjectType: library
+ProjectVersion: 0.0.1
+VendorId: eu.mycompany
+VendorName: "MyCompany AG"
+Output: "src-gen"
+Sources {
+ source {
+ "src"
+ }
+}
+----
+
+We need to add the following section at the end. Note that the manifest editor supports content
+assist similar to the N4JS editor.
+
+[source,n4mf]
+----
+RequiredRuntimeLibraries {
+ n4js-runtime-es2015
+}
+----
+
+This will add all additionally defined types of ECMAScript 2015. It will also add new methods
+ to types already defined in ECMAScript 5.
+
+== Running a Module
+
+Having created the first version of our domain model and storage tier, we are ready to try it out.
+ For that, we create a module "Runner.n4js" with the following code:
+
+[source, n4js]
+----
+import { StorageInMemory } from "StorageInMemory"
+import { Todo } from "model"
+
+let sim = new StorageInMemory();
+let todo = new Todo();
+todo.done = false;
+todo.dueDate = new Date();
+todo.label = "Test TODO";
+sim.storeTask(todo);
+
+console.log(sim.getTasks());
+----
+
+We then launch this module with Node.js. The easiest way to do that is with the context menu
+(accessed by right-clicking in the editor) and selecting "Launch in Node.js". as shown in the
+following screenshot:
+
+image::images/firstlaunch.png[]
+
+This will run the module currently opened in the editor. The output will be printed to the console
+view, for example
+
+image::images/firstlaunchconsole.png[]
+
+[.language-n4js]
+== Extend Entities with Spec-Constructor
+
+When we look at the runner code, creating a new task is quite annoying: It has to be created with
+a new expression, and then every data field has to be set separately. To simplify this, we add
+a constructor to our base entity class Task as follows:
+
+[source, n4js]
+.model.n4js (cntd.)
+----
+export abstract class Task {
+ // ...
+
+ constructor(@Spec spec: ~i~this=undefined) {
+ // code for initialization will be generated due to @Spec annotation
+ }
+}
+...
+----
+
+The concept of constructors is taken from ECMAScript 2015. However, the parameter is very special
+to N4JS. We briefly describe the type expression `pass:[~i~this=undefined]` used here. The part `=undefined` declares
+the default initializer of the parameter `spec` (c.f. ECMAScript 2015 cite:[ECMA11a]). Parameters which have default
+initializers are optional, hence N4JS allows for omitting them in function calls (or in case of
+constructors, in the `NewExpression`).
+`this` is a known keyword in ECMAScript, it usually refers to the receiver of a property or, in case of classes,
+method call. But here we use it as a type expression, referring to the type of the `this`
+keyword. This is usually the class in which the method or constructor is defined. That is,
+in case of Task it will be `Task`. However, we have two subclasses of `Task`. We do not
+define a new constructor in these classes, instead we let these classes inherit `this`
+constructor. In case of `Todo`, the `this` type will become `Todo` and in case of `Appointment`,
+`Appointment`. Simply referring to the `this` type wouldn't make any sense in the constructor,
+since we would need a first instance in order to create another one - but how could we
+create the first one? The solution comes with the `pass:[~i~]` prefix.
+
+As discussed in the feature sheet, N4JS supports nominal and structural typing. Structural typing
+is activated in N4JS with the tilde `pass:[~]`. Two structural types are compatible, if they provide
+the same properties, or in case of classes, public members. In the constructor, we only need to
+set the fields. In N4JS, we can use `pass:[~~]` to refer to the so-called **field structural type**. Two
+field structural types are compatible, if they provide the same fields - methods are
+ignored in these cases. Actually, optional fields are also ignored. This explains why we marked
+some of the fields with the optional modifier. Note that fields with an initializer are also
+treated as optional (since the initializer provides a default value). Actually, N4JS can do even
+more. There are several modifiers to further filter the properties or members to be considered:
+`pass:[~r~]` only considers getters or data fields, `pass:[~w~]` only setters and data fields. `pass:[~i~]` is used
+for initializer parameters: For every setter or (non-optional) data field in the type, the
+`pass:[~i~]`-type needs to provide at least a getter (or a readable data field). Optional fields
+are also treated as optional in the field structural types.
+
+For the concrete class `Todo`, the `pass:[~i~]`-type is not required to contain any property since all
+its fields are either optional or have an initializer. It contains the optional fields `id`,
+`label`, `dueDate`, `priority` and `done`. `pass:[~i~]Appointment` contains the required properties `time` and
+`place`, and the optional fields `id` and `label`.
+
+In most cases, we need this information in the constructor to set the fields accordingly.
+For Task we would write:
+
+[source, n4js]
+----
+constructor(spec: ~i~this=undefined) {
+ this.id = spec.id;
+ this.label = spec.label;
+}
+----
+
+In order to simplify the code, the annotation `@Spec` tells the transpiler to add exactly this
+code automatically. Even better: Since `Appointment` and `Todo` inherit the constructor, the
+transpiler will add constructor code in these classes to set the additional fields also. That
+is, with this single constructor, the `@Spec` annotation and the `pass:[~i~]this` type expression,
+we have solved the problem of initialization for all our entity classes with a single stroke!
+
+Using this `@Spec` constructor would then look similar to this:
+
+[source, n4js]
+----
+let todo = new Todo({dueDate: new Date(), label: "Test TODO"});
+sim.storeTask(todo);
+----
+
+*Short summary*
+
+The main concepts demonstrated so far by our example are:
+
+* *Modules* with import and export
+* *Classes* with inheritance and constructors
+* *Interfaces* with default methods
+* *Enumeration*
+* Special strategies for structural types
+* *Manifest.n4mf* file and runtime library dependencies
+
+We can now proceed to implement a Task Manager.
+
+== Creating a Task Manager
+
+We will now create the controller tier. This tier uses the entity and storage classes to provide
+functionality that is actually useful for the user of the application.
+
+Since we eventually want to implement a REST API (and use a real database), we need to introduce
+asynchronous functions. So before we actually implement any controller class, we have to adjust our storage
+tier to support asynchronous functions.
+
+=== Make the Storage Asynchronous
+
+If we would like to use a real database, all calls to the database will be asynchronous. Asynchronous
+programming is a typical task in ECMAScript and there are several solutions to do this.
+
+ECMAScript 2015 introduced a new class Promise which is supposed to be used with in these cases. Its methods
+accept callback functions which are called once the asynchronous event has been triggered. Since these
+callback functions tend to call other asynchronous functions, ECMAScript programmers easily end up in the so
+called 'callback hell'. There is a proposal for upcoming ECMAScript versions to use special constructs in
+the language to get rid of this callback hell. The idea is to mark asynchronous functions as "async" and,
+when these functions are called, the program can "await" the result. This async/await feature is already
+supported by several JavaScript frameworks and it is also built-in to N4JS including validation.
+
+First we have to change the Storage interface and mark all methods which are supposed to be asynchronous as
+`async`:
+
+[source, n4js]
+.Storage.n4js (cntd.)
+------
+
+import { Task } from "model"
+
+export public interface Storage {
+
+ async size(): int // <1>
+ async clear()
+
+ async getTasks(): Array<Task>
+ async storeTask(task: Task): string
+
+ async isEmpty(): boolean {
+ return (await this.size()) === 0;
+ }
+}
+------
+
+<1> Adding "async" to the size method and without adding the "await" keyword, you will get a
+warning in method `isEmpty` similar to the following:
+
+image::images/awaitwarning.png[]
+
+You will also get a lot of other errors in other files:
+
+image::images/asyncerrors.png[]
+
+Without an async/await and type aware IDE you probably would have missed one or the other of these errors.
+We can easily fix that by simply adding `async` to all the indicated methods.
+
+If you still have the runner module, you probably will get a warning there as well. If you ignore that
+warning and run it again, you will get the following
+
+[source, n4js]
+----
+Promise { <pending> }
+----
+
+instead of the expected output. We are not going to fix this problem now as we will introduce a better way
+of testing the code after the next step.
+
+*Create TaskManager*
+
+[source, n4js]
+.TaskManager.n4js
+----
+import { Todo } from "model"
+import { Task } from "model"
+import { Storage } from "Storage"
+import { StorageInMemory } from "StorageInMemory"
+
+export public class TaskManager {
+
+ private storage: Storage = new StorageInMemory();
+
+ public async getTasks(): Array<Task> {
+ return await this.storage.getTasks();
+ }
+
+ public async createTodo(label: string): string {
+ let newTodo = new Todo({label: label});
+ let newId = await this.storage.storeTask(newTodo);
+ return newId;
+ }
+}
+----
+
+This class does not reveal any new concepts, but how do we test it? For that, we are going to use the N4JS
+test framework.
+
+By utilizing the built-in test suite, classes and modules will not become polluted with superfluous test-
+code. In addition, it is possible to overcome some access modifiers restrictions so there's no need to
+restructure or rewrite your code specifically to run tests.
+
+Since we use a tier architecture, it is quite easy to add a test: We simply replace one tier with
+appropriate tests:
+
+image::images/controllertest.svg[]
+
+
+=== Testing
+
+Since we do not want to mix up the application with the tests, we create a new project. We use the new
+project wizard
+
+image::images/createtestproject.png[]
+
+We adjust the `manifest.n4mf` accordingly:
+
+* Define which project we test in the *TestedProjects* section.
+* Change the *source* folder to *test* folder. This way the IDE knows where to look for tests later on.
+* Add project dependencies to the built-in test framework "Mangelhaft", which also provides a comprehensive
+collection of assert methods.
+
+After adding these changes, the manifest of the test project will look as follows:
+
+[source,n4mf]
+.manifest.n4mf (in project n4js.example.tasks.tests)
+----
+…
+TestedProjects {
+ n4js.example.tasks
+}
+Output: "src-gen"
+Sources {
+ test {
+ "src"
+ }
+}
+ProjectDependencies {
+ org.eclipse.n4js.mangelhaft,
+ org.eclipse.n4js.mangelhaft.assert
+}
+----
+
+We can now write our first test. Again, we use the class wizard to create a module "TaskManagerTest"
+containing a class with the same name. The first test should look like that:
+
+[source, n4js]
+.TaskManagerTest.n4js
+----
+import { TaskManager } from "TaskManager"
+import { Assert } from "n4/mangel/assert/Assert"
+
+export public class TaskManagerTest {
+
+ mgr: TaskManager = new TaskManager();
+
+ @Test
+ async testCreateTodo() {
+ await this.mgr.createTodo("test todo");
+ Assert.equal("test todo", (await this.mgr.getTasks())[0].label);
+ }
+}
+----
+
+Mangelhaft is an xUnit-like test framework. For the sake of simplicity, N4JS uses the same annotations as
+the popular Java test framework JUnit. In our case, we have a single test method which needs to be annotated
+with `@Test`.
+
+Since we are testing asynchronous code, the test method needs to be asynchronous as well and we need to
+"await" the results of the methods we call. Mangelhaft supports asynchronous code so we do not have to
+bother about that any further. This is the nice thing about using `async`/`await` and N4JS: asynchronous
+programming becomes as simple as synchronous programming!
+
+We can run the test via the IDE. This works similar to launching the code with Node.js by simply using the
+context menu. The IDE will detect a test and it will automatically add the correct menu entry to the context
+menu:
+
+image::images/testinnodejs.png[]
+
+This will run the test and the test view will show the result of the first test:
+
+image::images/firsttestresults.png[]
+
+
+== Storage using MongoDB
+
+Instead of "storing" the entities in memory, we want to use a real database. In this example, we are going
+to use https://www.mongodb.com/[MongoDB]. To follow along this section on your own computer,
+you must have MongoDB installed and start a data base server instance via the command line as follows:
+
+[source,bash]
+mongod --dbpath /db
+
+
+In order to use MongoDB from N4JS, we need the appropriate npm package which allows MongoDB access from
+ECMAScript. Adding this npm and making it available in N4JS is as simple as adding any project dependency.
+We have to open the manifest editor (of the tasks project) and add the following project dependency:
+
+[source, n4js]
+----
+ProjectDependencies {
+ mongodb
+}
+----
+
+image::images/quickfixnpminstall.png[]
+
+The quick-fix will automatically download all required npm packages, that is mongodb and all its
+dependencies. We can now use mongodb from our N4JS code.
+
+To let N4JS know about the types a particular npm package provides, an N4JS definition file with extension `.
+n4jsd` is required (the same applies if you use a plain JavaScript file from N4JS). For some npm packages,
+definition files are provided at https://github.com/NumberFour/n4jsd[github.com/NumberFour/n4jsd].
+
+Let's assume for the moment there are no `.n4jsd` file available for MongoDB; we import MongoDB using
+a *dynamic import* as follows:
+
+[source, n4js]
+----
+import * as mongodb+ from "mongodb"
+
+mongodb.MongoClient.connect('mongodb://localhost:27017/tasks', function (err: any+, db: any+) {
+ if (!err) {
+ // ... use data base ...
+ db.close();
+ }
+});
+----
+
+However, since we do have an `.n4jsd` file available, we can import types such as `MongoDB`, `Collection`,
+or `ObjectID` provided by MongoDB using an ordinary ECMAScript2015 named import, just as if we were
+importing from an N4JS module:
+
+[source, n4js]
+.StorageMongoDB.n4js
+----
+import { Storage } from "Storage";
+import { Task, Appointment, Todo } from "model";
+import { Collection, Db, MongoClient, ObjectID } from "mongodb";
+
+/**
+* Persistence for task lists using a mongodb instance.
+*/
+export class StorageMongoDB implements Storage {
+ cachedDb: Db = null;
+
+ private async getTasksCollection(): Collection {
+ if (!this.cachedDb) {
+ this.cachedDb = await MongoClient.connect('mongodb://localhost:27017/tasks');
+ }
+ return this.cachedDb.collection('tasks');
+ }
+
+ public async shutdown() {
+ this.cachedDb.close(true);
+ this.cachedDb = null;
+ }
+}
+----
+
+In the above code section, we are implementing StorageMongoDB from the Storage interface and then calling
+some of the standard MongoDB collection methods.
+
+The next step is to retrieve the information about our Tasks and to store them in our MongoDB database. In
+the storeTask method, we are then retrieving the inserted item id's from MongoDB and returning them as a
+`task.id`.
+
+[source, n4js]
+.StorageMongoDB.n4js (cntd.)
+----
+export class StorageMongoDB implements Storage {
+
+// ...
+
+ @Override
+ public async size(): int {
+ let coll = await this.getTasksCollection();
+ return await coll.count({});
+ }
+
+ @Override
+ public async clear() {
+ let coll = await this.getTasksCollection();
+ await coll.deleteMany({});
+ }
+
+ @Override
+ public async getTasks(): Array<Task> {
+ let coll = await this.getTasksCollection();
+ let resultRaw = await coll.find({}).toArray();
+ let result = resultRaw.map((data): Task => fromData(data)); // <1>
+ return result;
+ }
+
+ @Override
+ public async storeTask(task: Task): string {
+ let coll = await this.getTasksCollection();
+ let result = await coll.insertOne(toData(task));
+ if (result.insertedCount === 1) {
+ task.id = result.insertedId.toHexString();
+ return task.id;
+ }
+ throw new Error("insert document failed");
+ }
+}
+----
+
+<1> The use of the `=>` arrow function, derived from ES6. Arrow functions have implicit lexical
+binding and are less verbose than traditional function expressions.
+
+The above code uses two helper functions, `toData()` and `fromData()`. Those illustrate two techniques available
+in N4JS: reflection and so-called `@Spec` constructors, respectively. Reflection is known from many
+languages and allows for retrieving information of a type and its members at runtime. It is used in
+`fromData()` as follows:
+
+[source,n4js]
+.StorageMongoDB.n4js (cntd.)
+----
+function toData(task: Task): ~~Task {
+ let metaClass = N4Type.of(task),
+ data: any+ = {};
+ // note: would have to set data._id, here, if we
+ // wanted support for updating existing tasks
+ data._type = metaClass.name;
+ let taskAsObject: Object = task; // up-cast to object to allow index access
+ for (let field of metaClass.dataFields(true,true)) {
+ data[field.name] = taskAsObject[field.name];
+ }
+ return data;
+}
+----
+
+Conversely, `@Spec` constructors are special constructors that allow us to create a new instance of a class and
+initialize it with values provided by a plain data object in properties that correspond to the type's fields.
+
+[source,n4js]
+.StorageMongoDB.n4js (cntd.)
+----
+function fromData(data: any+): Task {
+ let ctor = typeToCtor.get(data._type as string);
+ if (!ctor) {
+ throw new Error('Unsupported type of data model entity: ' + data._type);
+ }
+ let task = new ctor(data);
+ task.id = (data._id as ObjectID).toHexString();
+ return task;
+}
+
+const typeToCtor = new Map<string,constructor{Task}>([
+ ['Todo', Todo] as Iterable2<string, constructor{Task}>,
+ ['Appointment', Appointment] as Iterable2<string, constructor{Task}>
+]);
+----
+
+Note that both functions `toData` and `fromData` should be declared outside of the `StorageMongoDB` class but in the same file `StorageMongoDB.n4js`.
+By using the above two helper functions, we avoid sending our data model instances directly to the MongoDB
+driver. Note that the entire implementation is intended for illustration purposes and in a real-world
+systems many details would be handled differently, depending on the actual requirements.
+
+[.language-n4js]
+== Dependency Injection
+
+We now have two implementations of the interface Storage. For testing, the in-memory solution is adequate,
+but for the application we want to use the MongoDB solution of course. Since we are using the Storage in our
+TaskManager class, we would need to change the TaskManager depending on the storage solution. This is
+inconvenient and error prone. It would be much better if we could configure which storage class to use from
+outside the TaskManager at some central location. This is possible with dependency injection.
+
+To learn more about how dependency injection works, we have written an
+<<../features/dependency-injection#dependency-injection, extended feature description>> that describes the benefits of this technique.
+In short, N4JS provides built-in support for dependency injection using the same annotations as known from JSR-330/
+Google Guice. Instead of using initializers calling the constructor for certain fields, we just mark them
+with `@Inject`. We will do that with the storage field in the TaskManager class:
+
+[source,n4js]
+.TaskManger.n4js (cntd.)
+----
+export public class TaskManager {
+
+ @Inject
+ private storage: Storage;
+
+ // ...
+}
+----
+
+NOTE: After removing the constructor, the IDE will create a warning that one of the imports is unused. You
+can easily fix that by using the "Organize Import" feature, either from the context menu (or via
+kbd:[{commandkey}+Shift+O] on Mac OS, kbd:[Ctrl+Shift+O] on Windows).
+
+How does N4JS now create the instance of storage? For that, we need an injector. An injector is responsible
+for creating all variables annotated with `@Inject`. The injector is configured with a so-called "binder".
+The binder is more or less a translation table telling the injector which type it should use to create a
+concrete instance when a certain type is given. In our case, we need to tell the injector whether we want an
+instance of StorageInMemory or StorageMongoDB. We are going to adjust the test accordingly.
+
+For that, we first add a binder to the test module "TaskManagerTest.n4js":
+
+[source,n4js]
+.TaskMangerTest.n4js (cntd.)
+----
+@Binder
+@Bind(Storage,StorageInMemory)
+class InMemoryBinder {}
+----
+
+
+The annotation `@Binder` marks the class InMemoryBinder to become a binder. For each mapping we need to add
+an annotation `@Bind`, which takes the requested type as the first argument and the actual type as the
+second one. We only actually need to define bindings for interfaces. If the requested type is a class and if
+no binding is defined for it, the injector will simply create an instance of that very type.
+
+The next step is to create an injector. Fortunately, we do not have to do that manually. The dependency
+injection framework of N4JS introduces the notion of dependency injection components (DIC). A DIC is
+associated with an injector; this is done by using the annotation `@GenerateInjector`. Additionally we need
+to tell the framework which configuration it should use for the injector, this is done via the annotation
+ `@UseBinder`, which expects the type name of a binder class.
+
+[source,n4js]
+.TaskMangerTest.n4js (cntd.)
+----
+@GenerateInjector @UseBinder(InMemoryBinder)
+export public class TaskManagerTest {
+ …
+}
+----
+
+The IDE helps us in finding problems: since the TaskManager class uses injection to get the storage field,
+it needs to be injected itself. The IDE warns us in the TaskManagerTest class:
+
+image::images/injectionwarning.png[]
+
+This is hard to find but easy to fix: We just have to replace the initalizer with an `@Inject` annotation.
+
+[source,n4js]
+.TaskMangerTest.n4js (cntd.)
+----
+…
+export public class TaskManagerTest {
+ @Inject
+ mgr: TaskManager;
+}
+----
+
+With these little changes, we can now configure the storage solution from outside the TaskManager class.
+Running this test will behave as before but we have removed the hard-coded dependency from TaskManager to
+StorageInMemory.
+
+== Web UI module
+
+The final step in building functionality into our model is to create a simple web user interface using
+http://expressjs.com/[Express] as a dependency to create a web server. We will then pass our tasks from MongoDB into a small
+ HTML page to display the results. We will create the web server using http://expressjs.com/[Express].
+
+In order to use Express, we need the appropriate npm module. Adding this npm and making it available in
+N4JS is as simple as adding any project dependency, as already shown for MongoDB, above. We have to open the
+manifest editor (of the tasks project) and add the following project dependency (along with the existing
+dependencies):
+
+[source,n4mf]
+.manifest.n4mf (cntd.)
+----
+ProjectDependencies {
+ mongodb,
+ express,
+ n4js.lang
+}
+----
+
+The dependency `n4js.lang` contains `N4Injector` which is needed later, so make sure it is declared as a dependency.
+
+The quickfix will automatically download all required npm packages, that is, Express and all its
+dependencies. We can now use Express in our N4JS code (for more details, esp. N4JS definition files, see
+above description on MongoDB).
+
+[source,n4js]
+.WebUI.n4js
+----
+//Creating a simple Web User Interface in HTML
+
+import { TaskManager } from "TaskManager"
+import {Application, Response } from "express";
+import express from "express";
+import { Todo } from "model"
+
+export class WebUI {
+
+ private app: Application;
+
+ @Inject
+ private manager: TaskManager;
+
+ public start() {
+
+ this.app = express();
+
+ this.app.get('/', async (req, res) => {
+ let page = await this.renderHomePage();
+ res.send(page);
+ });
+ }
+}
+----
+
+Express is a web framework that provides (among other things) HTTP helpers for web routing. In the above
+example, we are importing the classes `Application` and `Response` from Express and creating a home page
+that we can render some HTML to. Next we will add a method for creating new tasks:
+
+[source,n4js,subs=macros]
+.WebUI.n4js
+----
+public start() {
+
+// ... code shown above ...
+
+ this.app.get("/create", async (req, res) => {
+ let values = req.query as pass:[~]Object with {type: string, label: string};
+ if (values && values.type === 'Todo' && values.label && values.label.length > 0) {
+ await this.manager.createTodo(values.label);
+ }
+ redirect(res, '/');
+ });
+}
+----
+
+
+Have Express listen on port 4000 at localhost:
+
+[source,n4js]
+.WebUI.n4js
+----
+public start() {
+
+// ... code shown above ...
+
+ this.app.listen(4000, '0.0.0.0', 511, function() {
+ console.log("HTTP server listening on http://localhost:4000/");
+ });
+}
+----
+
+Finally, we add a helper method for rendering a simple HTML page so we can view our Todos and edit them:
+
+[source,n4js]
+.WebUI.n4js
+----
+export class WebUI {
+
+ // ... methods shown above ...
+
+ protected async renderHomePage(): string {
+ let tasks = await this.manager.getTasks();
+ let todos = tasks.filter((task) => task instanceof Todo);
+ return `
+ <html>
+ <body>
+ Your to-do's:
+ <ul>
+ ${
+ todos.length === 0 ? '<li><em>none</em></li>\n'
+ : todos.map((todo) =>
+ '<li>'+todo.label+' <small>(id: '+ todo.id +')</small></li>'
+ ).join('\n')
+ }
+ </ul>
+ <hr/>
+ <form action="/create" method="get">
+ <input type="hidden" name="type" value="Todo">
+ Label: <input type="text" name="label"><br>
+ <input type="submit" value="Create Todo">
+ </form>
+ <hr/>
+ <a href="/clear">[Clear All]</a>
+ </body>
+ </html>
+ `;
+ }
+}
+
+function redirect(res: Response, url: string) {
+ res.header('Cache-Control', 'no-cache');
+ res.redirect(301, url);
+}
+----
+//`
+
+At this point, we have to launch our web server. For this purpose, we create a small launch script that
+configures the dependency injection (as shown in the section on dependency injection, above), creates an
+instance of class `WebUI`, and invokes method `start()`:
+
+[source,n4js]
+.launch.n4js
+----
+import { Storage } from "Storage";
+import { StorageMongoDB } from "StorageMongoDB";
+import { WebUI } from "WebUI";
+import { N4Injector } from "n4js/lang/N4Injector";
+
+@Binder
+@Bind(Storage, StorageMongoDB)
+class Binding { }
+
+@GenerateInjector
+@UseBinder(Binding)
+class Root { }
+
+N4Injector.of(Root).create(WebUI).start();
+----
+
+You can now use the HTML page by going to http://localhost:4000/[http://localhost:4000/],
+allowing you to interact with all of the logic we have built so far in order to read Todos, create new Todos
+and clear the storage.
+
+All of the fundamental elements of our model are completed and we have a functioning Task Manager with a
+simple Web UI.
+
+//////////////////////////////////////////
+Testing Our Finished Model
+
+TODO - Revise this section
+
+We can use the annotation `@Before` to delegate the order in which certain tests take place. If we wanted to
+mark a method to be executed once before each test in a given test class, we use `@Before` test annotation.
+If we want a method to be executed once before all tests, such as clearing a database, we can use the
+keyword `@BeforeAll`.
+
+
+[source, n4js,subs=macros]
+----
+import { Priority, Appointment, Todo } from "model";
+import { Storage } from "Storage";
+import { Assert } from "n4/mangel/assert/Assert";
+
+/**
+* Contains the actual test cases for testing implementations of Storage.
+* Subclasses will choose which concrete implementation to test.
+*/
+export public abstract class AbstractStorageTest {
+
+ /** A storage intended for testing. Created in pass:[#]prepare() method. */
+ private storage: Storage;
+
+ protected abstract createStorage(): Storage;
+
+ @BeforeAll
+ async prepareStorage() {
+ this.storage = this.createStorage();
+ }
+
+ @Before
+ async clearStorage() {
+ // make sure test storage is empty before each test starts
+ await this.storage.clear();
+ }
+
+}
+----
+
+Using the test annotation `@BeforeAll`, we are creating the storage space a single time before running all
+of our tests. The next section with the annotation `@Before`, ensures that the storage we created is cleared
+before each test. After all tests are complete, we run a 'garbage collector' method telling MongoDB to
+`shutdown` which cleans up all database resources and terminates the process.
+
+[source, n4js]
+----
+@Test
+async testStoreAppointment() {
+ let s = this.storage;
+ let appointment = new Appointment();
+
+ Assert.equal(0, await s.size());
+ let id = await s.storeTask(appointment);
+ Assert.equal(1, await s.size());
+ Assert.equal(id, appointment.id);
+}
+
+@Test
+async testGetTasks() {
+ let s = this.storage;
+ let todo = new Todo({
+ label: 'test',
+ priority: Priority.HIGH,
+ dueDate: new Date(2016, 3, 13, 14, 30, 0)
+});
+
+await s.storeTask(todo);
+let restoredTasks = await s.getTasks();
+
+Assert.equal(1, restoredTasks.length);
+Assert.isTrue(restoredTasks[0] instanceof Todo);
+let restoredTodo = restoredTasks[0] as Todo;
+Assert.equal(todo.label, restoredTodo.label);
+Assert.equal(todo.priority, restoredTodo.priority);
+Assert.equal(todo.dueDate.getTime(), restoredTodo.dueDate.getTime());
+}
+----
+
+Now that our AbstractStorageTest module is completed, we can create further test modules for other sections
+of our project:
+
+[source, n4js]
+----
+// Creating StorageInMemoryTest to extend AbstractStorageTest
+
+import { AbstractStorageTest } from "AbstractStorageTest"
+import { Storage } from "Storage"
+import { StorageInMemory } from "StorageInMemory"
+
+
+export public class StorageInMemoryTest extends AbstractStorageTest {
+
+ @Override
+ protected createStorage(): Storage {
+ return new StorageInMemory();
+ }
+}
+----
+
+In this instance, we are importing AbstractStorageTest and overriding the `createStorage` method and
+adapting it for use in testing our StorageInMemory module.
+
+The same can be done to test our MongoDB module:
+
+[source, n4js]
+----
+//Creating StorageMongoDBTest to extend AbstractStorageTest
+
+import { AbstractStorageTest } from "AbstractStorageTest"
+import { Storage } from "Storage"
+import { StorageMongoDB } from "StorageMongoDB"
+
+
+export public class StorageMongoDBTest extends AbstractStorageTest {
+
+ @Override
+ protected createStorage(): Storage {
+ return new StorageMongoDB();
+ }
+}
+----
+
+By importing our test module and using method overriding, we can adapt and reuse the same test module for a
+number of practical purposes, saving time and building an efficient testing system.
+
+//////////////////////////////////////////
+
+[.language-n4js]
+== Export as npm
+
+Finally, we can export our project as an npm package to integrate it into other Node.js projects or to
+launch from command line.
+
+
+* You can export one or multiple projects by selecting them in the Project Explorer and opening the
+"Export ..." wizard by right-clicking on them. On the first page select "N4JS Exports / N4JS npm Export". For
+the purpose of this example, only export project `n4js.example.tasks`.
+
+* On the second page you have to choose a target folder to export to.
+
+IMPORTANT: Export to a folder outside your Eclipse workspace!
+
+* By default, the exporter exports as a directory. Optionally, you can export as a versioned tarball by
+checking the option "Compress the contents of the file".
+* The last page of the wizard shows a preview of the package.json file that will be created in the
+exported npm package, together with a comparison to an existing package.json file in your N4JS project, if
+present. You can place such a package.json file next to your `manifest.n4mf` file (optional), in case you
+need
+to define more https://docs.npmjs.com/files/package.json[specifics in the package.json], that
+are not covered by the N4JS export wizard.
+
+
+image::images/npmexport.png[]
+
+== Run from command line with Node.js
+
+Once you've exported your project, you can either publish it to
+https://www.npmjs.com/[npmjs.com] or install directly from your hard disk and call the launch
+module, for example
+
+[source,bash]
+----
+$ npm install -g n4js.example.tasks
+$ node -r n4js.example.tasks/launch
+HTTP server listening on http://localhost:4000/
+----
+
+In case you want to install dependencies and run it right away in the exported npm folder, you have to
+manually set up the `NODE_PATH` to the folder hosting the exported npms, otherwise node cannot resolve the
+project/npm IDs.
+
+[source,bash]
+----
+$ export NODE_PATH=`pwd`
+$ pushd n4js.example.tasks; npm install; popd
+n4js.example.tasks@0.0.1 /Users/me/prj/n4js.example.tasks
+├─┬ express@4.13.4
+...
+$ node n4js.example.tasks/launch.js
+HTML server listening on http://localhost:4000/
+----
+
+So far we've been loading all code via node's `require()` function.
+In case you want to load your modules via https://github.com/systemjs/systemjs[SystemJS],
+which has more support to resolve cyclic dependencies across modules, you could use a handy starter
+executable called `n4js`. The `n4js` starter is part of the `n4js-node` runtime environment npm (a default
+dependency of any exported npm) and is therefore already installed:
+
+[source,bash]
+----
+$ export NODE_PATH=`pwd`
+$ cd n4js.example.tasks; npm install
+n4js.example.tasks@0.0.1 /Users/me/prj/n4js.example.tasks
+├─┬ express@4.13.4
+...
+$ ./node_modules/.bin/n4js n4js.example.tasks/launch
+HTTP server listening on http://localhost:4000/
+----
+
+[bibliography]
+== Bibliography
+
+bibliography::[]
diff --git a/userguides/index.html b/userguides/index.html
index 9c27527..44dedf4 100644
--- a/userguides/index.html
+++ b/userguides/index.html
@@ -2,10 +2,10 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
-<title>Documentation</title>
+<meta name="generator" content="Asciidoctor 2.0.15">
+<title>FAQ</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
<meta charset="utf-8">
@@ -60,7 +60,7 @@
<div class="paragraph">
<p></p>
</div>
-<h1 id="_documentation" class="discrete">Documentation</h1>
+<h1 id="_n4js_userguides" class="discrete">N4JS Userguides</h1>
</div>
</div>
<div class="sect1">
@@ -214,9 +214,8 @@
</table>
</div>
</div>
-
<div class="sect2">
-<h3 id="_in_depth_tutorial"><a class="link" href="#_in_depth_tutorial">Node.js App with N4JS Tutorial</a></h3>
+<h3 id="_in_depth_tutorial"><a class="link" href="#_in_depth_tutorial">In-Depth Tutorial</a></h3>
<div class="paragraph">
<p>Using the built-in example projects as a reference, this in-depth tutorial covers the most important tools and features
of the N4JS IDE. The example project is explained as a domain model and built step-by-step.
@@ -227,7 +226,7 @@
<table>
<tr>
<td class="hdlist1">
-<a href="tutorial.html#tutorial">Node.js App with N4JS Tutorial</a>
+<a href="tutorial.html#tutorial">In-Depth Tutorial</a>
</td>
<td class="hdlist2">
<p>Begin using the more powerful features N4JS has to offer!</p>
@@ -235,45 +234,14 @@
</tr>
</table>
</div>
-
-</div>
-</div>
-</div>
-
-<div class="sect2">
-<h3 id="_chess_tutorial"><a class="link" href="#_chess_tutorial">Chess Game App with N4JS Tutorial</a></h3>
-<div class="paragraph">
-<p>In this tutorial, we will develop a simple and yet fun (!) web-based chess game with N4JS and React. The final result of the tutorial is a chess game that allows two humans to play against each other.</p>
-</div>
-<div class="hdlist">
-<table>
-<tr>
-<td class="hdlist1">
-<a href="n4js-tutorial-chess/n4js-tutorial-chess.html">Chess game tutorial (part 1)</a>
-</td>
-<td class="hdlist2">
-<p>Begin developing web apps with N4JS and React!</p>
-</td>
-</tr>
-<tr>
-<td class="hdlist1">
-<a href="n4js-tutorial-chess/n4js-tutorial-chess-redux.html">Chess game tutorial (part 2)</a>
-</td>
-<td class="hdlist2">
-<p>Use Redux to manage chess game state with Redux and test game logics with our test framework Mangelhaft</p>
-</td>
-</tr>
-</table>
-</div>
<hr>
</div>
</div>
</div>
-
<div class="sect1">
-<h2 id="_specifications"><a class="link" href="#_specification">Specifications</a></h2>
+<h2 id="_specification"><a class="link" href="#_specification">Specification</a></h2>
<div class="sectionbody">
-
+<div class="sect2">
<h3 id="_n4js_language_specification"><a class="link" href="#_n4js_language_specification">N4JS Language Specification</a></h3>
<div class="paragraph">
<p>For a complete reference of the N4JS Language, the Specification is available at the following location:</p>
@@ -281,13 +249,12 @@
<div class="ulist">
<ul>
<li>
-<p><a href="../spec/index.html">N4JS Language Specification</a></p>
+<p><a href="https://www.eclipse.org/n4js/spec/index.html">N4JS Language Specification</a></p>
</li>
</ul>
-This is an HTML version of the asciidoc based documentation <a href="https://github.com/eclipse/n4js/tree/master/docs/org.eclipse.n4js.spec">on Github</a>.
-The language specification is also available in the Eclipse help of the N4JS IDE itself.
</div>
-
+</div>
+<div class="sect2">
<h3 id="_n4js_ide_specification"><a class="link" href="#_n4js_ide_specification">N4JS IDE Specification</a></h3>
<div class="paragraph">
<p>For a reference of the N4JS IDE, i.e. the specific views and UI features of the Eclipse based IDE, the Specification is available at the following location:</p>
@@ -295,32 +262,26 @@
<div class="ulist">
<ul>
<li>
-<p><a href="../idespec/index.html">N4JS IDE Specification</a></p>
+<p><a href="https://www.eclipse.org/n4js/idespec/index.html">N4JS IDE Specification</a></p>
</li>
</ul>
-This is an HTML version of the asciidoc based documentation <a href="https://github.com/eclipse/n4js/tree/master/docs/org.eclipse.n4js.ide.spec">on GitHub</a>.
-The IDE specification is also available in the Eclipse help of the N4JS IDE itself.
</div>
-
-
-<h3 id="_n4js_design"><a class="link" href="#_n4js_design">N4JS Design Documentation</a></h3>
+</div>
+<div class="sect2">
+<h3 id="_n4js_design_documentation"><a class="link" href="#_n4js_design_documentation">N4JS Design Documentation</a></h3>
<div class="paragraph">
<p>The design and other internal information valuable for contributors to Eclipse N4JS can be found at the following location:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p><a href="../design/index.html">N4JS Design Documentation</a></p>
+<p><a href="https://www.eclipse.org/n4js/design/index.html">N4JS Design Documentation</a></p>
</li>
</ul>
-This is an HTML version of the asciidoc based documentation <a href="https://github.com/eclipse/n4js/tree/master/docs/org.eclipse.n4js.design">on GitHub</a>.
-</div>
-
-
</div>
</div>
-<hr>
-
+</div>
+</div>
<div class="sect1">
<h2 id="_release_notes"><a class="link" href="#_release_notes">Release Notes</a></h2>
<div class="sectionbody">
@@ -403,14 +364,14 @@
var amountScrolled = 300;
$(window).scroll(function() {
if ( $(window).scrollTop() > amountScrolled ) {
- $('a.back-to-top').fadeIn('slow');
+ $('a.back-to-top').fadeIn('slow');
} else {
- $('a.back-to-top').fadeOut('slow');
+ $('a.back-to-top').fadeOut('slow');
}
});
$('a.back-to-top, a.simple-back-to-top').click(function() {
$('html, body').animate({
- scrollTop: 0
+ scrollTop: 0
}, 700);
return false;
});
diff --git a/userguides/license.html b/userguides/license.html
index 78cfc0a..486e21d 100644
--- a/userguides/license.html
+++ b/userguides/license.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>N4JS License</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/userguides/n4js-ide-setup.html b/userguides/n4js-ide-setup.html
index ed6d7ff..ea88079 100644
--- a/userguides/n4js-ide-setup.html
+++ b/userguides/n4js-ide-setup.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>N4JS IDE Setup</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
@@ -106,10 +106,11 @@
<div class="sect2">
<h3 id="_requirements"><a class="link" href="#_requirements">Requirements</a></h3>
<div class="paragraph">
-<p><strong>Java 8</strong></p>
+<p><strong>Java 11</strong></p>
</div>
<div class="paragraph">
-<p>In order to run the N4JS IDE, Java 8 is required. Installer packages can be downloaded from
+<p>In order to run the N4JS IDE, Java 11 is required. Note that there exists a version of the IDE which
+includes an embedded JRE-11. Java installer packages can be downloaded from
<a href="http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html">Oracle’s Java pages</a>.
For Mac OS X users: Always install the <strong>JDK</strong> - the JRE is installed
and only used in web browsers, not applications.</p>
diff --git a/userguides/npm-export-guide.html b/userguides/npm-export-guide.html
index 19e3dc1..d4f7efc 100644
--- a/userguides/npm-export-guide.html
+++ b/userguides/npm-export-guide.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>N4JS npm Export Guide</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
diff --git a/userguides/tutorial.html b/userguides/tutorial.html
index a5d5e16..a91d092 100644
--- a/userguides/tutorial.html
+++ b/userguides/tutorial.html
@@ -2,9 +2,9 @@
<html lang="en">
<head>
<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.7.1">
+<meta name="generator" content="Asciidoctor 2.0.15">
<title>N4JS Tutorial</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
@@ -80,6 +80,9 @@
<li><a href="#_storage_using_mongodb">Storage using MongoDB</a></li>
<li><a href="#_dependency_injection">Dependency Injection</a></li>
<li><a href="#_web_ui_module">Web UI module</a></li>
+<li><a href="#_export_as_npm">Export as npm</a></li>
+<li><a href="#_run_from_command_line_with_node_js">Run from command line with Node.js</a></li>
+<li><a href="#_bibliography">Bibliography</a></li>
</ul>
</li>
</ul>
@@ -1477,6 +1480,119 @@
</div>
</div>
</div>
+<div class="sect1 language-n4js">
+<h2 id="_export_as_npm"><a class="link" href="#_export_as_npm">Export as npm</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Finally, we can export our project as an npm package to integrate it into other Node.js projects or to
+launch from command line.</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>You can export one or multiple projects by selecting them in the Project Explorer and opening the
+"Export …​" wizard by right-clicking on them. On the first page select "N4JS Exports / N4JS npm Export". For
+the purpose of this example, only export project <code>n4js.example.tasks</code>.</p>
+</li>
+<li>
+<p>On the second page you have to choose a target folder to export to.</p>
+</li>
+</ul>
+</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+Export to a folder outside your Eclipse workspace!
+</td>
+</tr>
+</table>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>By default, the exporter exports as a directory. Optionally, you can export as a versioned tarball by
+checking the option "Compress the contents of the file".</p>
+</li>
+<li>
+<p>The last page of the wizard shows a preview of the package.json file that will be created in the
+exported npm package, together with a comparison to an existing package.json file in your N4JS project, if
+present. You can place such a package.json file next to your <code>manifest.n4mf</code> file (optional), in case you
+need
+to define more <a href="https://docs.npmjs.com/files/package.json">specifics in the package.json</a>, that
+are not covered by the N4JS export wizard.</p>
+</li>
+</ul>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/npmexport.png" alt="npmexport">
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_run_from_command_line_with_node_js"><a class="link" href="#_run_from_command_line_with_node_js">Run from command line with Node.js</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Once you’ve exported your project, you can either publish it to
+<a href="https://www.npmjs.com/">npmjs.com</a> or install directly from your hard disk and call the launch
+module, for example</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-bash" data-lang="bash">$ npm install -g n4js.example.tasks
+$ node -r n4js.example.tasks/launch
+HTTP server listening on http://localhost:4000/</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>In case you want to install dependencies and run it right away in the exported npm folder, you have to
+manually set up the <code>NODE_PATH</code> to the folder hosting the exported npms, otherwise node cannot resolve the
+project/npm IDs.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-bash" data-lang="bash">$ export NODE_PATH=`pwd`
+$ pushd n4js.example.tasks; npm install; popd
+n4js.example.tasks@0.0.1 /Users/me/prj/n4js.example.tasks
+├─┬ express@4.13.4
+...
+$ node n4js.example.tasks/launch.js
+HTML server listening on http://localhost:4000/</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>So far we’ve been loading all code via node’s <code>require()</code> function.
+In case you want to load your modules via <a href="https://github.com/systemjs/systemjs">SystemJS</a>,
+which has more support to resolve cyclic dependencies across modules, you could use a handy starter
+executable called <code>n4js</code>. The <code>n4js</code> starter is part of the <code>n4js-node</code> runtime environment npm (a default
+dependency of any exported npm) and is therefore already installed:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-bash" data-lang="bash">$ export NODE_PATH=`pwd`
+$ cd n4js.example.tasks; npm install
+n4js.example.tasks@0.0.1 /Users/me/prj/n4js.example.tasks
+├─┬ express@4.13.4
+...
+$ ./node_modules/.bin/n4js n4js.example.tasks/launch
+HTTP server listening on http://localhost:4000/</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_bibliography"><a class="link" href="#_bibliography">Bibliography</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>bibliography::[]</p>
+</div>
+</div>
+</div>
</div>
<div id="footer">
<div id="footer-text">
