Permalink
Browse files

regenerated documentation

  • Loading branch information...
1 parent bf42b0d commit 8e8592461fdf3a816f575363460b914957482924 hbehrens committed Jun 22, 2009
Showing with 1,510 additions and 1,250 deletions.
  1. +4 −4 plugins/org.eclipse.xtext.doc/help/DSL.html
  2. +12 −17 plugins/org.eclipse.xtext.doc/help/Defaulttokens.html
  3. +3 −3 plugins/org.eclipse.xtext.doc/help/NewFeatures.html
  4. +7 −7 plugins/org.eclipse.xtext.doc/help/Overview.html
  5. +4 −7 plugins/org.eclipse.xtext.doc/help/RuntimeConcepts.html
  6. +11 −8 plugins/org.eclipse.xtext.doc/help/SetupwithinEclipseEquinoxOSGi.html
  7. +1 −1 plugins/org.eclipse.xtext.doc/help/Xtend_based_apis.html
  8. +12 −5 plugins/org.eclipse.xtext.doc/help/antlr_ip_issue.html
  9. +41 −46 plugins/org.eclipse.xtext.doc/help/configuration.html
  10. +36 −23 plugins/org.eclipse.xtext.doc/help/dependencyInjection.html
  11. +8 −42 plugins/org.eclipse.xtext.doc/help/differences.html
  12. +6 −4 plugins/org.eclipse.xtext.doc/help/emf_integration.html
  13. +1 −1 plugins/org.eclipse.xtext.doc/help/formatting.html
  14. +85 −45 plugins/org.eclipse.xtext.doc/help/getting-started.html
  15. +5 −5 plugins/org.eclipse.xtext.doc/help/grammarImport.html
  16. +27 −27 plugins/org.eclipse.xtext.doc/help/grammarLanguage.html
  17. +12 −16 plugins/org.eclipse.xtext.doc/help/grammarMixins.html
  18. +87 −0 plugins/org.eclipse.xtext.doc/help/hyperlinking.html
  19. BIN plugins/org.eclipse.xtext.doc/help/images/emf-integration.png
  20. BIN plugins/org.eclipse.xtext.doc/help/images/getting-started-editor.png
  21. BIN plugins/org.eclipse.xtext.doc/help/images/getting-started-grammar.png
  22. BIN plugins/org.eclipse.xtext.doc/help/images/logo/xtext-logo-dark-1600.png
  23. BIN plugins/org.eclipse.xtext.doc/help/images/preferences_templates.png
  24. BIN plugins/org.eclipse.xtext.doc/help/images/sample_outline.png
  25. BIN plugins/org.eclipse.xtext.doc/help/images/templates_crossref.png
  26. BIN plugins/org.eclipse.xtext.doc/help/images/templates_enum.png
  27. +57 −25 plugins/org.eclipse.xtext.doc/help/linking.html
  28. +33 −39 plugins/org.eclipse.xtext.doc/help/metamodelInference.html
  29. +3 −3 plugins/org.eclipse.xtext.doc/help/migration_overview.html
  30. +6 −11 plugins/org.eclipse.xtext.doc/help/outline.html
  31. +17 −19 plugins/org.eclipse.xtext.doc/help/scoping.html
  32. +35 −33 plugins/org.eclipse.xtext.doc/help/serialization.html
  33. +187 −194 plugins/org.eclipse.xtext.doc/help/syntax.html
  34. +4 −3 plugins/org.eclipse.xtext.doc/help/templates.html
  35. +23 −24 plugins/org.eclipse.xtext.doc/help/validation.html
  36. +25 −11 plugins/org.eclipse.xtext.doc/help/valueconverter.html
  37. BIN plugins/org.eclipse.xtext.doc/html/images/emf-integration.png
  38. BIN plugins/org.eclipse.xtext.doc/html/images/getting-started-editor.png
  39. BIN plugins/org.eclipse.xtext.doc/html/images/getting-started-grammar.png
  40. BIN plugins/org.eclipse.xtext.doc/html/images/logo/xtext-logo-dark-1600.png
  41. BIN plugins/org.eclipse.xtext.doc/html/images/preferences_templates.png
  42. BIN plugins/org.eclipse.xtext.doc/html/images/sample_outline.png
  43. BIN plugins/org.eclipse.xtext.doc/html/images/templates_crossref.png
  44. BIN plugins/org.eclipse.xtext.doc/html/images/templates_enum.png
  45. +745 −618 plugins/org.eclipse.xtext.doc/html/xtext.html
  46. BIN plugins/org.eclipse.xtext.doc/manual/xtext.pdf
  47. +13 −9 plugins/org.eclipse.xtext.doc/toc.xml
@@ -1,7 +1,7 @@
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>What is a domain-specific language (DSL)</title>
+<title>What is a domain-specific language</title>
<link href="book.css" rel="stylesheet" type="text/css">
<meta content="DocBook XSL Stylesheets V1.75.1" name="generator">
<link rel="home" href="index.html" title="Xtext User Guide">
@@ -10,14 +10,14 @@
<link rel="next" href="getting-started.html" title="Getting Started">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
-<h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">What is a domain-specific language (DSL)</h1>
-<p>A DSL is a small programming language, which focuses on a particular domain.
+<h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">What is a domain-specific language</h1>
+<p>A domain-specific language (DSL) is a small programming language, which focuses on a particular domain.
Such a domain can be more or less anything. The idea is that its concepts and notation is as close as possible to
what you have in mind when you think about a solution in that domain. Of course we are talking about problems which can
be solved or processed by computers somehow.</p>
<p>The opposite of a DSL is a so called GPL, a General Purpose Language such as Java or any other common programming language.
With a GPL you can solve every computer problem, but it might not always be the best way to solve it.</p>
-<p>Imagine you want to remove the core from an apple. You could of course use a swiss army knife to cut it out, and this is reasonable if you have to do it just once or twice. But if you need to do that on a regular basis it might be more efficient to use an apple corer.</p>
+<p>Imagine you want to remove the core from an apple. You could of course use a Swiss army knife to cut it out, and this is reasonable if you have to do it just once or twice. But if you need to do that on a regular basis it might be more efficient to use an apple corer.</p>
<p>There are a couple of well-known examples of DSLs. For instance SQL is actually a DSL which focuses on querying relational databases. Other DSLs are regular expressions or even languages provided by tools like MathLab. Also most XML languages are actually domain-specific languages. The whole purpose of XML is to allow for easy creation of new languages. Unfortunately with XML you are not able to change the concrete syntax, which is the major problem with it. The concrete syntax of XML is way too verbose. Also a generic syntax for everything is a compromise.</p>
<p>Xtext is a sophisticated framework that helps to implement your very own DSL with appropriate IDE support. There is no such limitation as with XML, you are free to define your concrete syntax as you like. It may be as concise and suggestive as possible being a best match for your particular domain. The hard task of reading your model, working with it and writing it back to your syntax is greatly simplified by Xtext.</p>
</body>
@@ -15,27 +15,22 @@ <h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">Default tokens</h1>
<div class="literallayout">
<p>
<code class="code">grammar&nbsp;org.eclipse.xtext.common.Terminals&nbsp;<br>
-&nbsp;&nbsp;&nbsp;hidden(WS,&nbsp;ML_COMMENT,&nbsp;SL_COMMENT)<br>
+&nbsp;&nbsp;hidden(WS,&nbsp;ML_COMMENT,&nbsp;SL_COMMENT)<br>
<br>
-&nbsp;import&nbsp;"http://www.eclipse.org/emf/2002/Ecore"&nbsp;as&nbsp;ecore<br>
+import&nbsp;"http://www.eclipse.org/emf/2002/Ecore"&nbsp;as&nbsp;ecore<br>
<br>
-&nbsp;terminal&nbsp;ID&nbsp;:&nbsp;<br>
-&nbsp;&nbsp;&nbsp;'^'?('a'..'z'|'A'..'Z'|'_')&nbsp;('a'..'z'|'A'..'Z'|'_'|'0'..'9')*&nbsp;;<br>
-&nbsp;terminal&nbsp;INT&nbsp;returns&nbsp;ecore::EInt:&nbsp;('0'..'9')+&nbsp;;<br>
-&nbsp;terminal&nbsp;STRING :&nbsp;<br>
-&nbsp;&nbsp;&nbsp;'"'&nbsp;(&nbsp;'\\'&nbsp;('b'|'t'|'n'|'f'|'r'|'"'|"'"|'\\')&nbsp;|&nbsp;!('\\'|'"')&nbsp;)*&nbsp;'"'&nbsp;|<br>
-&nbsp;&nbsp;&nbsp;"'"&nbsp;(&nbsp;'\\'&nbsp;('b'|'t'|'n'|'f'|'r'|'"'|"'"|'\\')&nbsp;|&nbsp;!('\\'|"'")&nbsp;)*&nbsp;"'"<br>
-&nbsp;&nbsp;&nbsp;;&nbsp;<br>
-&nbsp;terminal&nbsp;ML_COMMENT :&nbsp;'/*'&nbsp;-&gt;&nbsp;'*/'&nbsp;;<br>
-&nbsp;terminal&nbsp;SL_COMMENT&nbsp; :&nbsp;'//'&nbsp;!('\n'|'\r')*&nbsp;('\r'?&nbsp;'\n')?&nbsp;;<br>
-
-<br>
-&nbsp;terminal&nbsp;WS :&nbsp;('&nbsp;'|'\t'|'\r'|'\n')+&nbsp;;<br>
-
-<br>
-&nbsp;terminal&nbsp;ANY_OTHER: .&nbsp;;<br>
+terminal&nbsp;ID&nbsp;:&nbsp;<br>
+&nbsp;&nbsp;'^'?('a'..'z'|'A'..'Z'|'_')&nbsp;('a'..'z'|'A'..'Z'|'_'|'0'..'9')*&nbsp;;<br>
+terminal&nbsp;INT&nbsp;returns&nbsp;ecore::EInt:&nbsp;('0'..'9')+&nbsp;;<br>
+terminal&nbsp;STRING :&nbsp;<br>
+&nbsp;&nbsp;'"'&nbsp;(&nbsp;'\\'&nbsp;('b'|'t'|'n'|'f'|'r'|'"'|"'"|'\\')&nbsp;|&nbsp;!('\\'|'"')&nbsp;)*&nbsp;'"'&nbsp;|<br>
+&nbsp;&nbsp;"'"&nbsp;(&nbsp;'\\'&nbsp;('b'|'t'|'n'|'f'|'r'|'"'|"'"|'\\')&nbsp;|&nbsp;!('\\'|"'")&nbsp;)*&nbsp;"'";&nbsp;<br>
+terminal&nbsp;ML_COMMENT :&nbsp;'/*'&nbsp;-&gt;&nbsp;'*/'&nbsp;;<br>
+terminal&nbsp;SL_COMMENT&nbsp; :&nbsp;'//'&nbsp;!('\n'|'\r')*&nbsp;('\r'?&nbsp;'\n')?&nbsp;;<br>
+terminal&nbsp;WS :&nbsp;('&nbsp;'|'\t'|'\r'|'\n')+&nbsp;;<br>
+terminal&nbsp;ANY_OTHER: .&nbsp;;<br>
</code>
</p>
@@ -41,12 +41,12 @@ <h3 class="title">
<a class="link" href="grammarMixins.html" title="Grammar Mixins">Grammar mixins</a> allow you to extend existing languages and change their concrete and abstract syntax. However the abstract syntax (i.e. the Ecore model) can only be extended. This allows you to reuse existing validations, code generators, interpreters or other code which has been written against those types.
</p>
-<p>In oAW Xtext common terminals like ID, INT, STRING, ML_COMMENT, SL_SOMMENT and WS (whitespace) were hard coded into the grammar language and couldn&rsquo;t be removed and hardly overridden. In TMF Xtext these terminals are imported through the newly introduced grammar mixin mechanism from the shipped grammar
+<p>In oAW Xtext common terminals like ID, INT, STRING, ML_COMMENT, SL_COMMENT and WS (whitespace) were hard coded into the grammar language and couldn&rsquo;t be removed and hardly overridden. In TMF Xtext these terminals are imported through the newly introduced grammar mixin mechanism from the shipped grammar
<code class="code">org.eclipse.xtext.common.Terminals</code> per default. This means that they are still there but reside in a libraries now. You don&rsquo;t have to use them and you can come up with your own set of reusable rules.
</p>
<p>
-<a class="link" href="grammarImport.html" title="Importing existing Meta Models">Reusing existing Ecore models</a> in oAW Xtext didn&rsquo;t work well and we communicated this by flagging this feature as &lsquo;experimental&rsquo;. In TMF Xtext importing existing Ecore models is fully supported. Moreover, it is possible to import a couple of different EPackages and generate some at the same time, so that the generated Ecore models extend or refer to the existing Ecore models.
+<a class="link" href="grammarImport.html" title="Importing existing Ecore models">Reusing existing Ecore models</a> in oAW Xtext didn&rsquo;t work well and we communicated this by flagging this feature as &lsquo;experimental&rsquo;. In TMF Xtext importing existing Ecore models is fully supported. Moreover, it is possible to import a couple of different EPackages and generate some at the same time, so that the generated Ecore models extend or refer to the existing Ecore models.
</p>
<p>The grammar language gained one new concept that is of great value when writing left-factored grammars (e.g. expressions). With actions one can do minor AST rewritings within a rule to overcome degenerated ASTs. You will find an
<a class="link" href="syntax.html#grammarActions" title="Assigned Actions">in-depth explanation of actions</a> in the dedicated chapter in the reference documentation.
@@ -57,7 +57,7 @@ <h3 class="title">
<div>
<div>
<h3 class="title">
-<a name="Finegrainedcontrolforvalidation"></a>Fine-grained control for validation</h3>
+<a name="differences_validation"></a>Fine-grained control for validation</h3>
</div>
</div>
</div>
@@ -7,7 +7,7 @@
<link rel="home" href="index.html" title="Xtext User Guide">
<link rel="up" href="index.html" title="Xtext User Guide">
<link rel="prev" href="index.html" title="Xtext User Guide">
-<link rel="next" href="DSL.html" title="What is a domain-specific language (DSL)">
+<link rel="next" href="DSL.html" title="What is a domain-specific language">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">Overview</h1>
@@ -21,8 +21,8 @@ <h2 class="title" style="clear: both">
</div>
</div>
<p>Xtext is a framework for the development of
- <a class="link" href="DSL.html" title="What is a domain-specific language (DSL)">domain-specific languages</a> and other textual programming languages. It is tightly integrated with the
- <a class="ulink" href="http://www.eclipse.org/EMF" target="_new">Eclipse Modeling Framework (EMF)</a> and leverages the Eclipse Platform in order to provide a language-specific integrated development environment (IDE).
+ <a class="link" href="DSL.html" title="What is a domain-specific language">domain-specific languages</a> and other textual programming languages. It is tightly integrated with the
+ <a class="ulink" href="http://www.eclipse.org/emf" target="_new">Eclipse Modeling Framework (EMF)</a> and leverages the Eclipse Platform in order to provide a language-specific integrated development environment (IDE).
</p>
<p>In contrast to common parser generators (like e.g. JavaCC or ANTLR), Xtext derives much more than just a parser and lexical analyzer (lexer) from an input grammar.
The grammar language is used to describe and generate:</p>
@@ -32,7 +32,7 @@ <h2 class="title" style="clear: both">
<p>an incremental, ANTLR 3 based parser and lexer to read your models from text,</p>
</li>
<li class="listitem">
-<p>Ecore models (optional)</p>
+<p>Ecore models (optional),</p>
</li>
<li class="listitem">
<p>a serializer to write your models back to text,</p>
@@ -41,7 +41,7 @@ <h2 class="title" style="clear: both">
<p>a linker, to establish cross links between model elements,</p>
</li>
<li class="listitem">
-<p>an implementation of the EMF Resource interface with full support for loading and saving EMF models,</p>
+<p>an implementation of the EMF Resource interface with full support for loading and saving EMF models, and</p>
</li>
<li class="listitem">
<p>an integration of the language into your Eclipse IDE.</p>
@@ -60,7 +60,7 @@ <h2 class="title" style="clear: both">
<li class="listitem">
<p>
-<a class="link" href="">model navigation (F3, etc.)</a>,
+<a class="link" href="hyperlinking.html" title="Hyperlinking">model navigation (F3, etc.)</a>,
</p>
</li>
<li class="listitem">
@@ -72,7 +72,7 @@ <h2 class="title" style="clear: both">
<li class="listitem">
<p>
-<a class="link" href="outline.html" title="Outline View">outline view</a> and
+<a class="link" href="outline.html" title="Outline View">outline view</a>, and
</p>
</li>
<li class="listitem">
@@ -12,8 +12,8 @@
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">Runtime Concepts</h1>
<p>TMF Xtext itself and every language infrastructure developed with Xtext is configured and wired-up using
- <a class="link" href="dependencyInjection.html" title="Dependency Injection in Xtext with Google Guice">dependency injection</a>. Xtext may be used in different environments which introduce different constraints. Especially important is the difference between OSGi managed containers and plain vanilla java programs. To honor these differences Xtext uses the concept of
- <code class="code">ISetup</code>-implementations in normal mode and uses Eclipse&rsquo;s extension mechanism when it should be configured by a container.
+ <a class="link" href="dependencyInjection.html" title="Dependency Injection in Xtext with Google Guice">dependency injection</a>. Xtext may be used in different environments which introduce different constraints. Especially important is the difference between OSGi managed containers and plain vanilla Java programs. To honor these differences Xtext uses the concept of
+ <code class="code">ISetup</code>-implementations in normal mode and uses Eclipse&rsquo;s extension mechanism when it should be configured in an OSGi environment.
</p>
<div class="section" title="Runtime setup (ISetup)">
<div class="titlepage">
@@ -26,14 +26,11 @@ <h2 class="title" style="clear: both">
</div>
<p>For each language there is an implementation of
<code class="code">ISetup</code> generated. It implements a method called
- <code class="code">doSetup()</code>, which can be called to do the initialization of the language infrastructure.
+ <code class="code">doSetup()</code>, which can be called to do the initialization of the language infrastructure. This class is intended to be used for runtime and unit testing, only.
</p>
-<p>This class is intended to be used for runtime and unit testing, only.</p>
<p>The setup method returns an
- <code class="code">Injector</code>, which can further be used to obtain a parser, etc.
+ <code class="code">Injector</code>, which can further be used to obtain a parser, etc. It also registers the ResourceFactory and generated EPackages at the respective global registries provided by EMF. So basically you can just run the setup and start using EMF API to load and store models of your language.
</p>
-<p>The setup method also registers the ResourceFactory and generated EPackages at the respective global registries provided by EMF.</p>
-<p>So basically you can just run the setup and start using EMF API to load and store models of your language.</p>
</div>
</body>
</html>
@@ -11,20 +11,23 @@
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">Setup within Eclipse-Equinox (OSGi)</h1>
-<p>Within Eclipse we have a generated Activator, which creates a guice injector using the modules.
- In addition an IExecutableExtensionFactory is generated for each language, which is used to create ExecutableExtensions.
- This means that everything which is created via extension points is managed by guice as well, i.e. you can declare dependencies and get them injected upon creation. </p>
+<p>Within Eclipse we have a generated
+ <code class="code">Activator</code>, which creates a Guice injector using the
+ <a class="ulink" href="guicemodules" target="_new">modules</a>.
+ In addition an
+ <code class="code">IExecutableExtensionFactory</code> is generated for each language, which is used to create
+ <code class="code">ExecutableExtensions</code>.
+ This means that everything which is created via extension points is managed by Guice as well, i.e. you can declare dependencies and get them injected upon creation.
+ </p>
<p>The only thing you have to do in order to use this factory is to prefix the class with the factory
- <code class="code">ExecutableExtensionFactory</code> name followed by a colon.
+ <code class="code">&lt;MyLanguageName&gt;ExecutableExtensionFactory</code> name followed by a colon.
</p>
<div class="literallayout">
<p>
-<code class="code">
-<br>
-&lt;extension<br>
+<code class="code">&lt;extension<br>
&nbsp;&nbsp;point="org.eclipse.ui.editors"&gt;<br>
&nbsp;&nbsp;&lt;editor<br>
-&nbsp;&nbsp;&nbsp;&nbsp;class="[MyLanguageName]ExecutableExtensionFactory:<br>
+&nbsp;&nbsp;&nbsp;&nbsp;class="&lt;MyLanguageName&gt;ExecutableExtensionFactory:<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;org.eclipse.xtext.ui.core.editor.XtextEditor"<br>
&nbsp;&nbsp;&nbsp;&nbsp;contributorClass=<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"org.eclipse.ui.editors.text.TextEditorActionContributor"<br>
@@ -14,7 +14,7 @@ <h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">Where are the Xtend-
<p>One of the nice things with oAW Xtext was the use of Xtend to allow customizing different aspects of the generated language infrastructure.
Xtend is a part of the template language Xpand, which is shipped with oAW (and now is included in M2T Xpand). It provides a nicer expression syntax than Java.
Especially the existence of higher-order functions for collections is extremely handy when working with models.
- In addition to the nice syntax, it provides dynamic polymorphic dispatch, which means that declaring e.g. label computation for a meta model is very convenient and type safe at the same time.
+ In addition to the nice syntax, it provides dynamic polymorphic dispatch, which means that declaring e.g. label computation for an Ecore model is very convenient and type safe at the same time.
In Java one usually has to write instanceof and cast orgies. </p>
<div class="section" title="Xtend is hard to debug">
<div class="titlepage">
@@ -28,15 +28,22 @@ <h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">The ANTLR IP issue (
</p>
<p>Unfortunately as the generator of ANTLR V3 needs ANTLR V2 it is as well not yet IP approved.
That is why we are not allowed to ship Xtext with the ANTLR generator (the runtime is IP approved), but have to provide it separately via update-site at:</p>
-<p>*
- <a class="ulink" href="http://download.itemis.com/updates/" target="_new">http://download.itemis.com/updates/</a>
-
+<div class="itemizedlist">
+<ul class="itemizedlist" type="disc">
+<li class="listitem">
+<p>
+
+<a class="ulink" href="http://download.itemis.com/updates/" target="_new">http://download.itemis.com/updates/</a>
+
</p>
+</li>
+</ul>
+</div>
<p>
-<span class="bold"><strong>IMPORTANT</strong></span>
+<span class="bold"><strong>IMPORTANT</strong></span> :
- <span class="italic">Although If you use the non-IP approved ANTLR generator, you can still ship any languages and the IDEs you&rsquo;ve developed with Xtext without any worrying, because the
+ <span class="italic">Although if you use the non-IP approved ANTLR generator, you can still ship any languages and the IDEs you&rsquo;ve developed with Xtext without any worrying, because the
<span class="bold"><strong>ANTLR runtime is IP approved</strong></span>
</span>
Oops, something went wrong.

0 comments on commit 8e85924

Please sign in to comment.