From 5afaa04bc8ccdc60930ec47e650aea3277cb5ed0 Mon Sep 17 00:00:00 2001
From: "john.j.camilleri" <john.j.camilleri@chalmers.se>
Date: Mon, 14 Nov 2011 10:46:46 +0000
Subject: [PATCH] Updated GFEP index page

---
 eclipse/index.html | 224 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 204 insertions(+), 20 deletions(-)
diff --git a/eclipse/index.html b/eclipse/index.html
index 7095df94f..9b049ad06 100644
--- a/eclipse/index.html
+++ b/eclipse/index.html
@@ -1,21 +1,205 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<HTML>
-<HEAD>
-<TITLE>GF Eclipse Plugin</TITLE>
-</HEAD>
-<BODY>
-<h1 style="text-align:center">GF Eclipse Plugin</h1>
-<p style="text-align:center">
-	<em>
-		Maintained by John J. Camilleri<br/>
-		04/11/11
-	</em>
-</p>
-<ul style="max-width:400px;margin:0 auto;line-height:1.75;">
-	<li>Documentation has moved to the <a href="http://www.molto-project.eu/node/1395" title="GF Eclipse Plugin at the MOLTO Project website Wiki">MOLTO Project Wiki</a>.</li>
-	<li>Source code repository is at <a href="https://github.com/GrammaticalFramework/gf-eclipse-plugin" title="GF Eclipse Plugin on GitHub">GitHub</a>.</li>
-	<li><a href="http://www.grammaticalframework.org/eclipse/examples/" title="Example GF projects">Example GF projects</a> for testing out the plugin.</li>
-	<li>Software update site URL for <a href="http://www.molto-project.eu/node/1396" title="Instructions for installing the GF Eclipse Plugin">installing</a> through Eclipse: <code><a href="http://www.grammaticalframework.org/eclipse/release/" title="Software Site URL for GFEP">http://www.grammaticalframework.org/eclipse/release/</a></code></li>
+<h1>The GF Eclipse Plugin</h1>
+
+<p><em>The research leading to these results has received funding from the European Union&#8217;s Seventh Framework Programme (FP7/2007-2013) under grant agreement n° FP7-ICT-247914.</em></p>
+
+<h2>Introduction</h2>
+
+<p>The aim behind developing a desktop IDE for GF is to provide more powerful tools than may be possible and/or practical in a web-based environment (the GF Web IDE). In particular, the ability to resolve identifier cross-references and browse external libraries quickly during development time is one of the primary motivations for the project.</p>
+
+<p>The choice was made to develop this desktop IDE as a plugin for the Eclipse Platform as it emerged as the most popular choice among the GF developer community. Support for the platform is vast and many tools for adapting Eclipse to domain-specific languages already exist. Unlike the zero-click Web IDE approach, using the GF Eclipse plugin (GFEP) will require some manual installation and configuration on the development machine. Thus the GFEP is aimed more at seasoned developers rather than the curious GF newbie.</p>
+
+<p>The starting point for the GFEP is using the <a href="http://www.eclipse.org/Xtext/">Xtext DSL Framework</a> for Eclipse. By converting the GF grammar into the appropriate Extended-BNF form required by the LL(*) ANTLR parser, the framework provides a good starting point for future plugin development, already including a variery of syntax checking tools and some cross-reference resolution support. The specific requirements of the GF language, particularly in the way of its special module hierarchy, mean that significant customisations to this generated base plugin are needed.</p>
+
+<h3>Who</h3>
+
+<p>The GFEP is being developed as part of Work Package 2 of the <a href="http://www.molto-project.eu/">MOLTO Project</a>.</p>
+
+<p>Primary developer is <strong>John J. Camilleri</strong>, who should be contacted for all queries and feedback related to the plugin on <code>john.j.camilleri</code> at domain <code>chalmers.se</code>.</p>
+
+<h3>Links</h3>
+
+<ul>
+<li>This document shall contain the most up-to-date information about the plugin. The most up-to-date version of this file can always be found in the source-code repository at <a href="https://github.com/GrammaticalFramework/gf-eclipse-plugin/blob/master/README.markdown">https://github.com/GrammaticalFramework/gf-eclipse-plugin/blob/master/README.markdown</a></li>
+<li>This documentation is also available at the <a href="http://www.molto-project.eu/node/1395">MOLTO Project Wiki</a>.</li>
+<li>Source code repository is at <a href="https://github.com/GrammaticalFramework/gf-eclipse-plugin">https://github.com/GrammaticalFramework/gf-eclipse-plugin</a> (do not try to run the plugin from source; please only use the packaged releases).</li>
+<li>Here are some <a href="http://www.grammaticalframework.org/eclipse/examples/">example GF projects</a> for testing out the plugin features.</li>
+<li>Software update site URL for installing through Eclipse:
+<code>http://www.grammaticalframework.org/eclipse/release/</code></li>
 </ul>
-</BODY>
-</HTML>
+
+<h3>Update history</h3>
+
+<dl>
+<dt><strong>16/11/11</strong></dt>
+<dd>Third BETA released, using new tag-based scoping for better performance.</dd>
+
+<dt><strong>11/10/11</strong></dt>
+<dd>Second BETA released, with improved support for qualified names, local variable bindings, selective inheritance, module outlining, and launch configurations. Also new GF Project type.</dd>
+
+<dt><strong>01/10/11</strong></dt>
+<dd>Initial BETA released.</dd>
+
+<dt><strong>20/09/11</strong></dt>
+<dd>Refactoring of grammar to provide neater syntax trees, and handle cross-referencing contraints. Major work on name resolution across modules, implementing custom <code>Scoping</code>, <code>Naming</code>, <code>ResourceDescription</code> implementations.</dd>
+
+<dt><strong>08/09/11</strong></dt>
+<dd>Successfully converted GF language grammar into ANTLR-compaticble format. Refactoring to avoid left-recursion took up the majority of this time so far.</dd>
+
+<dt><strong>Late August 2011</strong></dt>
+<dd>Started investigation the use of Xtext as a basis for building the Eclipse plugin. Xtext requires a EBNF-style language grammar in order to generate development tools as a plugin for the Eclipse IDE.</dd>
+</dl>
+
+<hr />
+
+<h2>Features</h2>
+
+<h3>Implemented (or partially implemented)</h3>
+
+<ul>
+<li>Syntax highlighting and error detection</li>
+<li>Code folding, quick block-commenting, automatic code formatting</li>
+<li>Definition outlining, jump to declaration, find usage</li>
+<li>Warnings for problems in module dependancy hierarchy</li>
+<li>Launch configurations, i.e. compilation directly from IDE</li>
+<li>Auto-completion for declared identifiers</li>
+</ul>
+
+<h3>Near-term</h3>
+
+<ul>
+<li>Inline documentation for function calls, overloads</li>
+<li>Quick-fix suggestions for syntax and naming errors</li>
+<li>Code generation for concrete/instance modules</li>
+<li>Code generation for new languages in application grammars</li>
+<li>Grouping of concrete syntaxes by language, fast switching and linked navigation</li>
+<li>Built-in library browser (in particular for GF resource grammar library)</li>
+</ul>
+
+<h3>Long-term goals</h3>
+
+<ul>
+<li>Test-suite functionality</li>
+<li>Treebank management and testing</li>
+<li>Provide a single platform for developing and using embedded grammars</li>
+<li>Integration with ontology engineering tools</li>
+</ul>
+
+<h3>Known issues</h3>
+
+<ol>
+<li>The in-editor validation often needs to be triggered by a keystroke.</li>
+</ol>
+
+<h3>Other remarks</h3>
+
+<ol>
+<li>Interface decisions such as icons were made reltively hastily and may not be entirely suitable or intuitive.
+This will get better as the plugin gets used by more users (and provide feedback).</li>
+<li>A wiki or bug tracker may be set up if there is enough usage feedback to justify it.</li>
+</ol>
+
+<hr />
+
+<h2>Installation &amp; updating</h2>
+
+<h3>System requirements</h3>
+
+<ol>
+<li>The plugin was developed using Eclipse 3.7, and has <strong>not</strong> been tested with older versions of Eclipse.</li>
+<li>GFEP makes use of the newest GF features, and requires that the latest developer version of GF is already installed on your system. Paths to GF must be set within the Eclipse plugin (meaning you don&#8217;t necessarily need to have GF in your <code>PATH</code> environment variable).</li>
+</ol>
+
+<h3>Installing the plugin for the first time</h3>
+
+<ol>
+<li>Inside Eclipse, go to <strong>Help &rarr; Install New Software</strong>.</li>
+<li>Add new software site using the URL: <code>http://www.grammaticalframework.org/eclipse/release/</code></li>
+<li>Select the <strong>GF Eclipse Plugin</strong>, click Next, accept the license agreement and install.</li>
+<li>Accept the prompt warning that the software is unsigned.</li>
+<li>Restart Eclipse when prompted.</li>
+</ol>
+
+<h4>Settings</h4>
+
+<ol>
+<li>Add the GF perspective by clicking <strong>Open Perspective &rarr; Other</strong> and choosing <strong>GF</strong>.</li>
+<li>Set your paths to the GF executable and libraries by going to <strong>Window &rarr; Preferences &rarr; Grammatical Framework</strong>.<br />
+<em>The runtime path is assumed to be <code>~/.cabal/bin/gf</code>, which may be wrong depending on your
+system and how you installed GF.</em><br />
+<em>The library path should get automatically set from your environment&#8217;s <code>GF_LIB_PATH</code> variable.</em></li>
+</ol>
+
+<h3>Updating the plugin</h3>
+
+<ol>
+<li>In Eclipse, go to <strong>Help &rarr; Check for updates</strong>.</li>
+<li>Any available updates will appear in the dialog. Select them and follow the usual steps.</li>
+</ol>
+
+<hr />
+
+<h2>Getting started</h2>
+
+<p>Some steps you can follow to get a feel of of the plugin&#8217;s features.</p>
+
+<ul>
+<li>Create a new <strong>GF Project</strong>.</li>
+</ul>
+
+<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-projectwizard-1.png" alt="New project wizard" />
+<img src="http://www.grammaticalframework.org/eclipse/images/eclipse-projectwizard-2.png" alt="New project wizard" /></p>
+
+<ul>
+<li>Create some new modules using the <strong>GF Module</strong> wizard from <strong>File > New > Other > GF Module</strong>:</li>
+</ul>
+
+<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-modulewizard-1.png" alt="New module wizard" /></p>
+
+<p><em>If asked whether you want to add the <strong>Xtext nature</strong> to your project, you can safely say <strong>No</strong> (this prompt has been removed in newer versions).</em></p>
+
+<ul>
+<li><p>You can find some small examples at http://www.grammaticalframework.org/eclipse/examples/. Download the 
+files and manually add them to your Eclipse workspace. To experiment with some of the plugin features.</p></li>
+<li><p>Use Eclipes&#8217; own features to drag and drop your editor tabs to suit your needs. Notice the <strong>Outline</strong> view in the bottom-right offers a quite overview of your module structure. Clicking any of the terms will make your cursor jump to that point in the file.</p></li>
+</ul>
+
+<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-editor-general.png" alt="The editor and outline view" /></p>
+
+<ul>
+<li>Note how changing a <code>cat</code> definition for example will produce warnings and/or errors in other the modules.</li>
+</ul>
+
+<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-editor-cat.png" alt="Warnings and errors in the editor" /></p>
+
+<ul>
+<li>Use the built-in code formatter to tidy your code automatically. Right-click in the editor and choose <strong>Format</strong> or use the keyboard shortcut <strong>Ctrl+Shift+F</strong>.</li>
+</ul>
+
+<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-before-format.png" alt="Before auto-formatting" /> <img src="http://www.grammaticalframework.org/eclipse/images/eclipse-after-format.png" alt="After auto-formatting" /></p>
+
+<ul>
+<li>Set up a launch configuration from <strong>Run &rarr; Run Configurations&#8230; &rarr; Grammatical Framework</strong>. You will see the dialog below with some fields automatically filled in for you. </li>
+</ul>
+
+<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-launchconfig.png" alt="Launch configuration dialog" /></p>
+
+<ul>
+<li>Run the launch config and you will see the output from the GF compiler in the console view within Eclipse.</li>
+</ul>
+
+<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-compileroutput.png" alt="Output from the GF compiler" /></p>
+
+<hr />
+
+<h2>Feedback</h2>
+
+<p>As part of the evaluation of the GF Eclipse Plugin, feedback (both negative and positive) on the following would be appreciated:</p>
+
+<ol>
+<li>Issues encountered with installation</li>
+<li>Incorrect support of GF syntactic constructs, module hierarchy system</li>
+<li>Performance issues (speed, resources footprint)</li>
+<li>General intuitiveness of the UI</li>
+<li>Feature wish-list</li>
+<li>Compatibilities / conflicts with other Eclipse plugins</li>
+</ol>
