Bug 565833: [Help] Improve EASE help
add engine documentation
Change-Id: I01f5f868f4674611fd2f55150d0501c1cce2edc8
diff --git a/plugins/org.eclipse.ease.help/help/main.xml b/plugins/org.eclipse.ease.help/help/main.xml
index ee1f489..4a938b2 100644
--- a/plugins/org.eclipse.ease.help/help/main.xml
+++ b/plugins/org.eclipse.ease.help/help/main.xml
@@ -5,16 +5,19 @@
<topic label="Getting Started">
<anchor id="gettingstarted"/>
</topic>
- <topic label="Concepts">
- <anchor id="concepts"/>
+ <topic label="Script Engines">
+ <anchor id="engines"/>
</topic>
<topic label="Tasks">
<anchor id="tasks"/>
</topic>
- <topic label="Reference">
- <anchor id="reference"/>
- </topic>
<topic label="Tips and tricks">
<anchor id="tips"/>
</topic>
+ <topic label="Concepts">
+ <anchor id="concepts"/>
+ </topic>
+ <topic label="Reference">
+ <anchor id="reference"/>
+ </topic>
</toc>
diff --git a/plugins/org.eclipse.ease.lang.javascript.nashorn/META-INF/MANIFEST.MF b/plugins/org.eclipse.ease.lang.javascript.nashorn/META-INF/MANIFEST.MF
index cee22db..aeca1a1 100755
--- a/plugins/org.eclipse.ease.lang.javascript.nashorn/META-INF/MANIFEST.MF
+++ b/plugins/org.eclipse.ease.lang.javascript.nashorn/META-INF/MANIFEST.MF
@@ -7,6 +7,7 @@
Bundle-RequiredExecutionEnvironment: JavaSE-1.8
Require-Bundle: org.eclipse.ease,
org.eclipse.ease.lang.javascript,
- org.eclipse.debug.core
+ org.eclipse.debug.core,
+ org.eclipse.help
Export-Package: org.eclipse.ease.lang.javascript.nashorn
Automatic-Module-Name: org.eclipse.ease.lang.javascript.nashorn
diff --git a/plugins/org.eclipse.ease.lang.javascript.nashorn/build.properties b/plugins/org.eclipse.ease.lang.javascript.nashorn/build.properties
index 6f20375..f4f62af 100755
--- a/plugins/org.eclipse.ease.lang.javascript.nashorn/build.properties
+++ b/plugins/org.eclipse.ease.lang.javascript.nashorn/build.properties
@@ -1,5 +1,6 @@
-source.. = src/
-output.. = bin/
-bin.includes = META-INF/,\
- .,\
- plugin.xml
+source.. = src/
+output.. = bin/
+bin.includes = META-INF/,\
+ .,\
+ plugin.xml,\
+ help/
diff --git a/plugins/org.eclipse.ease.lang.javascript.nashorn/help/engines.xml b/plugins/org.eclipse.ease.lang.javascript.nashorn/help/engines.xml
new file mode 100644
index 0000000..8e8111e
--- /dev/null
+++ b/plugins/org.eclipse.ease.lang.javascript.nashorn/help/engines.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?NLS TYPE="org.eclipse.help.toc"?>
+
+<toc label="Script Engines" link_to="../org.eclipse.ease.help/help/main.xml#engines">
+ <topic href="help/html/nashorn_engine.html" label="JavaScript: Nashorn">
+ </topic>
+</toc>
diff --git a/plugins/org.eclipse.ease.lang.javascript.nashorn/help/html/nashorn_engine.html b/plugins/org.eclipse.ease.lang.javascript.nashorn/help/html/nashorn_engine.html
new file mode 100644
index 0000000..c945724
--- /dev/null
+++ b/plugins/org.eclipse.ease.lang.javascript.nashorn/help/html/nashorn_engine.html
@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>JavaScript: Nashorn</title>
+</head>
+<body>
+ <h2>JavaScript: Nashorn</h2>
+
+ <p><a href="https://docs.oracle.com/javase/10/nashorn/introduction.htm#JSNUG136">Nashorn</a> is a JavaScript interpreter that comes as part of your Java runtime. Its status is currently unclear as it is deprecated since Java 11.
+ However up to Java 14 it is still available. Nashorn does not provide a dedicated debug framework, therefore scripts can only be executed and not launched in debug mode using this engine.
+ Due to the nature of the Nashorn implementation in Java, a debugger implementation in EASE is impossible.
+ </p>
+
+ <h3>JavaScript Compatibility</h3>
+
+ <p>Nashorn claims to be fully compatible with ECMAScript 5.1 and includes some language features from ECMAScript 6.
+ </p>
+
+ <h3>Special language features</h3>
+
+ <h4>Built-in libraries</h4>
+
+ <p>Nashorn comes with some standard libraries:
+ <ul>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></li>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a></li>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math">Math</a></li>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date">Date</a></li>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></li>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp">RegExp</a></li>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON">JSON</a></li>
+ </ul>
+ </p>
+
+ <h4>Java class interaction</h4>
+
+ <p>Java classes on the classpath can directly be used when accessed with their full qualified name (eg. <i>java.io.File</i>). Typical top level package names will be detected automatically, eg com.*, org.*, java.*. In case your package is not detected as it may start with an unusual top level name, you may access it via the <i>Packages.<full qualified name></i> syntax.</p>
+ </p>
+</body>
+</html>
\ No newline at end of file
diff --git a/plugins/org.eclipse.ease.lang.javascript.nashorn/plugin.xml b/plugins/org.eclipse.ease.lang.javascript.nashorn/plugin.xml
index dbb5898..1c0cdf5 100755
--- a/plugins/org.eclipse.ease.lang.javascript.nashorn/plugin.xml
+++ b/plugins/org.eclipse.ease.lang.javascript.nashorn/plugin.xml
@@ -22,5 +22,12 @@
engineID="org.eclipse.ease.javascript.nashorn">
</completionAnalyzer>
</extension>
+ <extension
+ point="org.eclipse.help.toc">
+ <toc
+ file="help/engines.xml"
+ primary="false">
+ </toc>
+ </extension>
</plugin>
diff --git a/plugins/org.eclipse.ease.lang.javascript.rhino/META-INF/MANIFEST.MF b/plugins/org.eclipse.ease.lang.javascript.rhino/META-INF/MANIFEST.MF
index 79283f0..0ce4c43 100644
--- a/plugins/org.eclipse.ease.lang.javascript.rhino/META-INF/MANIFEST.MF
+++ b/plugins/org.eclipse.ease.lang.javascript.rhino/META-INF/MANIFEST.MF
@@ -18,7 +18,8 @@
org.eclipse.ui.editors;bundle-version="[3.7.0,4.0.0)",
org.eclipse.wst.jsdt.ui,
org.eclipse.jface.text,
- org.eclipse.wst.jsdt.debug.ui
+ org.eclipse.wst.jsdt.debug.ui,
+ org.eclipse.help
Export-Package: org.eclipse.ease.lang.javascript.rhino
Automatic-Module-Name: org.eclipse.ease.lang.javascript.rhino
Bundle-Activator: org.eclipse.ease.lang.javascript.rhino.Activator
diff --git a/plugins/org.eclipse.ease.lang.javascript.rhino/build.properties b/plugins/org.eclipse.ease.lang.javascript.rhino/build.properties
index 786b1df..23b8cbb 100644
--- a/plugins/org.eclipse.ease.lang.javascript.rhino/build.properties
+++ b/plugins/org.eclipse.ease.lang.javascript.rhino/build.properties
@@ -3,4 +3,5 @@
bin.includes = META-INF/,\
.,\
plugin.xml,\
- about.html
+ about.html,\
+ help/
diff --git a/plugins/org.eclipse.ease.lang.javascript.rhino/help/engines.xml b/plugins/org.eclipse.ease.lang.javascript.rhino/help/engines.xml
new file mode 100644
index 0000000..b51f9c9
--- /dev/null
+++ b/plugins/org.eclipse.ease.lang.javascript.rhino/help/engines.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?NLS TYPE="org.eclipse.help.toc"?>
+
+<toc label="Script Engines" link_to="../org.eclipse.ease.help/help/main.xml#engines">
+ <topic href="help/html/rhino_engine.html" label="JavaScript: Rhino">
+ </topic>
+</toc>
diff --git a/plugins/org.eclipse.ease.lang.javascript.rhino/help/html/rhino_engine.html b/plugins/org.eclipse.ease.lang.javascript.rhino/help/html/rhino_engine.html
new file mode 100644
index 0000000..3438187
--- /dev/null
+++ b/plugins/org.eclipse.ease.lang.javascript.rhino/help/html/rhino_engine.html
@@ -0,0 +1,65 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>JavaScript: Rhino</title>
+</head>
+<body>
+ <h2>JavaScript: Rhino</h2>
+
+ <p><a href="https://github.com/mozilla/rhino">Mozilla Rhino</a> is a JavaScript interpreter implemented in Java. The script code is translated into byte code for the JVM which allows for the same optimizations as native Java code.
+ </p>
+
+ <h3>JavaScript Compatibility</h3>
+
+ <p>The Rhino runtime is provided as a separate plug-in and loaded by EASE. Depending on the installed version of the Rhino runtime, different levels of JavaScript support are available.
+ By default we try to enable ECMAScript 6 support, which is not fully implemented in Rhino yet. Check out the <a href="http://mozilla.github.io/rhino/compat/engines.html">compatibility table</a> for details.<br />
+ If not available EASE will gracefully fall back to JavaScript 1.8 support and finally drop to 1.7.
+ </p>
+
+ <h3>Special language features</h3>
+
+ <h4>Built-in libraries</h4>
+
+ <p>Rhino comes with some standard libraries:
+ <ul>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></li>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a></li>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math">Math</a></li>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date">Date</a></li>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></li>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp">RegExp</a></li>
+ <li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON">JSON</a></li>
+ </ul>
+ </p>
+
+ <h4>String class ambiguity</h4>
+ <p>JavaScript provides a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String class</a> that differs from the <a href="https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/lang/String.html">Java String class</a>. As a script might have instances of both, this often leads to confusion. The variables drop-in in the <a href="script_shell.html">Script Shell</a> view shows the actual type by using different icons.
+ <code>var javaScriptString = "I am a javaScript string";
+var javaString = new java.lang.String("I am a Java string");</code>
+ </p>
+
+ <p>To convert any string type to JavaScript use:
+ <code>var javaScriptString = someString + "";</code>
+ </p>
+
+ <p>To convert any string to Java use:
+ <code>var javaString = new java.lang.String(someString);</code>
+ </p>
+
+ <h4>Java class interaction</h4>
+
+ <p>Java classes on the classpath can directly be used when accessed with their full qualified name (eg. <i>java.io.File</i>). Typical top level package names will be detected automatically, eg com.*, org.*, java.*. In case your package is not detected as it may start with an unusual top level name, you may access it via the <i>Packages.<full qualified name></i> syntax.</p>
+
+ <p>When accessing Java classes you always have to use full qualified class names. To simplify script code you may load classes or packages directly to the global namespace:
+ <code>importClass(java.io.File);
+new File(...)
+ </code>
+
+ <code>importPackage(java.net);
+new ServerSocket(...)
+ </code>
+ </p>
+
+</body>
+</html>
\ No newline at end of file
diff --git a/plugins/org.eclipse.ease.lang.javascript.rhino/plugin.xml b/plugins/org.eclipse.ease.lang.javascript.rhino/plugin.xml
index e25f7f2..0ea1aff 100644
--- a/plugins/org.eclipse.ease.lang.javascript.rhino/plugin.xml
+++ b/plugins/org.eclipse.ease.lang.javascript.rhino/plugin.xml
@@ -102,5 +102,12 @@
id="org.eclipse.ease.lang.javascript.rhino.debugger.hover">
</hover>
</extension>
+ <extension
+ point="org.eclipse.help.toc">
+ <toc
+ file="help/engines.xml"
+ primary="false">
+ </toc>
+ </extension>
</plugin>
diff --git a/plugins/org.eclipse.ease.lang.python.jython/META-INF/MANIFEST.MF b/plugins/org.eclipse.ease.lang.python.jython/META-INF/MANIFEST.MF
index d1b946c..bca9417 100644
--- a/plugins/org.eclipse.ease.lang.python.jython/META-INF/MANIFEST.MF
+++ b/plugins/org.eclipse.ease.lang.python.jython/META-INF/MANIFEST.MF
@@ -10,7 +10,8 @@
org.eclipse.ease,
org.eclipse.ease.lang.python,
org.eclipse.core.resources;bundle-version="[3.7.101,4.0.0)",
- org.eclipse.debug.core;bundle-version="[3.7.1,4.0.0)"
+ org.eclipse.debug.core;bundle-version="[3.7.1,4.0.0)",
+ org.eclipse.help
Bundle-RequiredExecutionEnvironment: JavaSE-1.8
Bundle-ActivationPolicy: lazy
Eclipse-BuddyPolicy: global
diff --git a/plugins/org.eclipse.ease.lang.python.jython/build.properties b/plugins/org.eclipse.ease.lang.python.jython/build.properties
index 6f20375..11511df 100644
--- a/plugins/org.eclipse.ease.lang.python.jython/build.properties
+++ b/plugins/org.eclipse.ease.lang.python.jython/build.properties
@@ -2,4 +2,5 @@
output.. = bin/
bin.includes = META-INF/,\
.,\
- plugin.xml
+ plugin.xml,\
+ help/
diff --git a/plugins/org.eclipse.ease.lang.python.jython/help/engines.xml b/plugins/org.eclipse.ease.lang.python.jython/help/engines.xml
new file mode 100644
index 0000000..139615d
--- /dev/null
+++ b/plugins/org.eclipse.ease.lang.python.jython/help/engines.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?NLS TYPE="org.eclipse.help.toc"?>
+
+<toc label="Script Engines" link_to="../org.eclipse.ease.help/help/main.xml#engines">
+ <topic href="help/html/jython_engine.html" label="Python: Jython">
+ </topic>
+</toc>
diff --git a/plugins/org.eclipse.ease.lang.python.jython/help/html/jython_engine.html b/plugins/org.eclipse.ease.lang.python.jython/help/html/jython_engine.html
new file mode 100644
index 0000000..de311e9
--- /dev/null
+++ b/plugins/org.eclipse.ease.lang.python.jython/help/html/jython_engine.html
@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Jython</title>
+</head>
+<body>
+ <h2>Jython</h2>
+
+ <p><a href="https://www.jython.org/">Jython</a> is a Python interpreter implemented in Java.
+ </p>
+
+ <h3>Python Compatibility</h3>
+
+ <p>Jython is based on <a href="https://docs.python.org/2.7/">Python 2.7</a>. As Python progressed to 3.x already long ago, the supported language features seem to be a bit old fashioned.
+ However the benefits of Jython are that it natively runs on the Java runtime and therefore mixing Java and Python code does not come with any performance penalties.
+ </p>
+
+ <h3>Special language features</h3>
+
+ <h4>Library support</h4>
+
+ <p>Jython <a href="https://wiki.python.org/jython/JythonFaq/JythonModules">claims to support almost all of the standard Python library</a>. Libraries using native code like NumPy/SciPy are not supported so far.</p>
+
+ <p>Detailed information on Jython can be found in the online <a href="https://jython.readthedocs.io/en/latest/">Jython book</a>.</p>
+
+</body>
+</html>
\ No newline at end of file
diff --git a/plugins/org.eclipse.ease.lang.python.jython/plugin.xml b/plugins/org.eclipse.ease.lang.python.jython/plugin.xml
index af66dc6..1e29e83 100644
--- a/plugins/org.eclipse.ease.lang.python.jython/plugin.xml
+++ b/plugins/org.eclipse.ease.lang.python.jython/plugin.xml
@@ -40,4 +40,11 @@
name="Jython external library">
</page>
</extension>
+ <extension
+ point="org.eclipse.help.toc">
+ <toc
+ file="help/engines.xml"
+ primary="false">
+ </toc>
+ </extension>
</plugin>
diff --git a/plugins/org.eclipse.ease.lang.python.py4j/META-INF/MANIFEST.MF b/plugins/org.eclipse.ease.lang.python.py4j/META-INF/MANIFEST.MF
index 9a86ace..ba4e76d 100644
--- a/plugins/org.eclipse.ease.lang.python.py4j/META-INF/MANIFEST.MF
+++ b/plugins/org.eclipse.ease.lang.python.py4j/META-INF/MANIFEST.MF
@@ -14,7 +14,8 @@
org.eclipse.ease,
org.eclipse.ease.lang.python,
org.eclipse.core.resources;bundle-version="[3.7.101,4.0.0)",
- org.eclipse.debug.core;bundle-version="[3.7.1,4.0.0)"
+ org.eclipse.debug.core;bundle-version="[3.7.1,4.0.0)",
+ org.eclipse.help
Export-Package: org.eclipse.ease.lang.python.py4j.internal;x-internal:=true,
org.eclipse.ease.lang.python.py4j.internal.ui;x-internal:=true
Bundle-Activator: org.eclipse.ease.lang.python.py4j.internal.Activator
diff --git a/plugins/org.eclipse.ease.lang.python.py4j/build.properties b/plugins/org.eclipse.ease.lang.python.py4j/build.properties
index f0b133b..e15e0c6 100644
--- a/plugins/org.eclipse.ease.lang.python.py4j/build.properties
+++ b/plugins/org.eclipse.ease.lang.python.py4j/build.properties
@@ -2,4 +2,5 @@
bin.includes = META-INF/,\
.,\
plugin.xml,\
- pysrc/
+ pysrc/,\
+ help/
diff --git a/plugins/org.eclipse.ease.lang.python.py4j/help/engines.xml b/plugins/org.eclipse.ease.lang.python.py4j/help/engines.xml
new file mode 100644
index 0000000..ff261a5
--- /dev/null
+++ b/plugins/org.eclipse.ease.lang.python.py4j/help/engines.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?NLS TYPE="org.eclipse.help.toc"?>
+
+<toc label="Script Engines" link_to="../org.eclipse.ease.help/help/main.xml#engines">
+ <topic href="help/html/py4j_engine.html" label="Python: Py4J">
+ </topic>
+</toc>
diff --git a/plugins/org.eclipse.ease.lang.python.py4j/help/html/py4j_engine.html b/plugins/org.eclipse.ease.lang.python.py4j/help/html/py4j_engine.html
new file mode 100644
index 0000000..d4eae1a
--- /dev/null
+++ b/plugins/org.eclipse.ease.lang.python.py4j/help/html/py4j_engine.html
@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Python via Py4J</title>
+</head>
+<body>
+ <h2>Python via Py4J</h2>
+
+ <p><a href="https://www.py4j.org/">Py4J</a> is a library that provides a bridge between a Java runtime and an external python interpreter.
+ </p>
+
+ <h3>Python Compatibility</h3>
+
+ <p>As Py4J connects to an external python interpreter, you may freely choose your engine and therefore can select your compatibility level on your own. Typically you will run Py4J on <a href="https://github.com/python/cpython">CPython</a>.
+ </p>
+
+ <h3>Special language features</h3>
+
+ <h4>Java / Python interaction</h4>
+
+ <p>As your python interpreter does not run as part of the Java runtime, both active processes need to serialize any data they share and communicate with each other. This causes a quite large overhead which you may see whenever you switch between the python and the Java world.
+ The general advice is to keep calls between the languages to a minimum to keep the performance penalty low.
+ </p>
+
+ <p>Memory management is also quite tricky as both processes cannot inform each other in all cases when shared objects are no longer needed. This will prevent the Java runtime to correctly garbage collect such objects.
+ The Java memory will only be cleaned up correctly when the Py4J script engine gets terminated.</p>
+
+ <p>Py4J is a good choice when you need to use libraries not supported by <a href="jython.html">Jython</a> or you need to execute Python 3.x code. It is not recommended to be used for <a href="../conceptes/user_scripts.html">UI extensions</a> or similar tasks with heavy interaction with your Eclipse application.</p>
+
+</body>
+</html>
\ No newline at end of file
diff --git a/plugins/org.eclipse.ease.lang.python.py4j/plugin.xml b/plugins/org.eclipse.ease.lang.python.py4j/plugin.xml
index d8ccd9c..636512c 100644
--- a/plugins/org.eclipse.ease.lang.python.py4j/plugin.xml
+++ b/plugins/org.eclipse.ease.lang.python.py4j/plugin.xml
@@ -54,5 +54,12 @@
class="org.eclipse.ease.lang.python.py4j.internal.ui.PreferenceInitializer">
</initializer>
</extension>
+ <extension
+ point="org.eclipse.help.toc">
+ <toc
+ file="help/engines.xml"
+ primary="false">
+ </toc>
+ </extension>
</plugin>
