msyds/gf-core
1
0
Fork 0
forked from GitHub/gf-core
Code Pull Requests Activity

GFEP: updated readme

Browse Source
This commit is contained in:
john.j.camilleri
2012-03-05 10:39:14 +00:00
parent 6f6371e1bf
commit 7c00e81fb5
1 changed files with 67 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

147
eclipse/index.html
View File

@@ -1,9 +1,9 @@
<h1>The GF Eclipse Plugin</h1>
<p>John J. Camilleri<br />
Updated: 8 Feb 2012</p>
Updated: 5 March 2012</p>
<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>
<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 no. FP7-ICT-247914.</em></p>
<p><em>This documentation is also available at the <a href="http://www.molto-project.eu/node/1395">MOLTO Project Wiki</a>.</em></p>
@@ -27,12 +27,10 @@ Updated: 8 Feb 2012</p>
<li>Software update site URL for installing through Eclipse: <a href="http://www.grammaticalframework.org/eclipse/release/">http://www.grammaticalframework.org/eclipse/release/</a></li>
</ul>
<hr />
<!----------------------------------------------------------------------------->
<h2>Features</h2>
<h3>Implemented</h3>
<ul>
<li>Syntax highlighting and error detection</li>
<li>Code folding, quick block-commenting, automatic code formatting</li>
@@ -42,34 +40,22 @@ Updated: 8 Feb 2012</p>
<li>Use GF Shell from within Eclipse</li>
<li>Auto-completion for declared identifiers</li>
<li>Background compilation (shallow) using project builder</li>
<li>Support for <em>Open Declaration</em> (F3)</li>
<li>Support for <em>Open Declaration</em> (F3), including qualified names</li>
<li>Code generation for new languages in application grammars</li>
</ul>
<h3>Near-term</h3>
<ul>
<li>Built-in library browser (in particular for GF resource grammar library)</li>
<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>Grouping of concrete syntaxes by language, fast switching and linked navigation</li>
<li>Proper cross-reference handling with qualified names</li>
<li>Treebank management and testing tool</li>
<li>External library browser</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>
<hr />
<!----------------------------------------------------------------------------->
<h2>Major release history</h2>
<dl>
<dt><strong>05/03/12</strong></dt>
<dd>(1.4.0.x) Treebank manager view. Updated launch configurations. UI improvements, new icons. Inline contextual documentation. Correct resolution of qualified identifiers. Bug fixes and some refactoring.</dd>
<dt><strong>07/02/12</strong></dt>
<dd>(1.3.0.x) Re-written underlying GF grammar.</dd>
@@ -95,22 +81,15 @@ Updated: 8 Feb 2012</p>
<dd>Initial BETA released.</dd>
</dl>
<hr />
<!----------------------------------------------------------------------------->
<h2>Installation &amp; updating</h2>
<h3>System requirements</h3>
<ol>
<li>The plugin makes use of the newest GF features, and <strong>requires the latest developer version of GF</strong> to be installed on your system (instructions <a href="http://www.grammaticalframework.org/download/index.html">here</a>).
<em>Specifically, you need a version of GF which supports the &#8220;&#8212;tags&#8221; flag, added in November 2011.</em></li>
<li>Paths to GF must be set within the plugin (see below). This means:
<ul>
<li>you don&#8217;t necessarily need to have GF in your <code>PATH</code> environment variable</li>
<li>you can use a separate GF installation for GFEP if you wish</li>
</ul></li>
<li>The plugin was developed using Eclipse 3.7. It has been successfully installed on Eclipse as low as 3.6.2.</li>
<li><a href="http://www.grammaticalframework.org/download/release-3.3.3.html">GF version 3.3.3</a> or above. The path to GF must be set within the plugin (see below).</li>
<li><a href="http://www.eclipse.org/downloads/">Eclipse</a> 3.6 or above.</li>
</ol>
<h3>Installing the plugin for the first time</h3>
@@ -153,8 +132,8 @@ Updated: 8 Feb 2012</p>
<h4>Deprecated stuff</h4>
<ul>
<li>If your project has a folder named <code>(External)</code> you can safely delete this <strong>via the Eclipse Project Explorer</strong>. It is no longer used in GFEP >= 1.2.3</li>
<li>If your workspace contains a log file <code>gfep.log</code> then you can safely delete it from your system. As of version 1.2.4, GFEP uses Eclipse&#8217;s standard log file at <code>.metadata/.log</code></li>
<li>If your project has a folder named <code>(External)</code> you can safely delete this <strong>via the Eclipse Project Explorer</strong>. It is no longer used in GFEP &ge; 1.2.3</li>
<li>If your workspace contains a log file <code>gfep.log</code> then you can safely delete it from your system. As of version 1.2.4, GFEP uses Eclipse&#8217;s standard log file at <code>&lt;workspace&gt;/.metadata/.log</code></li>
</ul>
<h3>Project settings</h3>
@@ -183,84 +162,101 @@ Updated: 8 Feb 2012</p>
&lt;/buildSpec&gt;
</code></pre>
<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>
<h3>Create a new GF Project</h3>
<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 &rarr; New &rarr; Other &rarr; GF Module</strong>:</li>
</ul>
<h3>Add some new modules</h3>
<p>Use the <strong>GF Module</strong> wizard from <strong>File &rarr; New &rarr; Other &rarr; GF Module</strong>:</p>
<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>
<p>You can find some small examples at <a href="http://www.grammaticalframework.org/eclipse/examples/">http://www.grammaticalframework.org/eclipse/examples/</a>. Download the
files and manually add them to your Eclipse workspace to experiment with some of the plugin features.</p>
<ul>
<li><p>You can find some small examples at <a href="http://www.grammaticalframework.org/eclipse/examples/">http://www.grammaticalframework.org/eclipse/examples/</a>. Download the
files and manually add them to your Eclipse workspace to experiment with some of the plugin features.</p></li>
<li><p>You can change your syntax colouring styles as you wish from <strong>Window &rarr; Preferences &rarr; Grammatical Framework &rarr; Syntax Coloring</strong></p></li>
</ul>
<h3>Syntax highlighting</h3>
<p>You can change your syntax colouring styles as you wish from <strong>Window &rarr; Preferences &rarr; Grammatical Framework &rarr; Syntax Coloring</strong></p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-syntaxcoloring.png" alt="Syntax highlighting styles" /></p>
<ul>
<li>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.</li>
</ul>
<h3>Workbench editor layout</h3>
<p>Use Eclipes&#8217; own features to drag and drop your editor tabs to suit your needs.</p>
<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>
<h4>Outline view</h4>
<p>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>
<h3>Cross-referencing errors and warnings</h3>
<p>Notice how changing a <code>cat</code> definition for example will produce warnings and/or errors in other the modules.</p>
<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>
<h3>Code formatting</h3>
<p>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>.</p>
<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>
<h3>Launch configurations</h3>
<p>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.</p>
<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>Run the launch config and you will see the output from the GF compiler in the console view within Eclipse.</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-compileroutput.png" alt="Output from the GF compiler" /></p>
<h3>Usage hints &amp; issues</h3>
<h4>Run As&#8230; launch shortcut</h4>
<h4>Consoles</h4>
<p>Using the <strong>Run &rarr; Run As &rarr; Compile with GF</strong> shortcut will take the current selection or active editor and do one of two things:</p>
<ol>
<li>If a launch configuration already exists which the current file in its <em>Source filenames</em> field, then that config will be launch directly.</li>
<li>Otherwise, a new a launch configuration window is displayed where you will need to review and confirm the default settings before continuing.</li>
</ol>
<h3>Consoles</h3>
<p>The plugin provides its own console view named <em>GFEP Log</em>, which shows log messages based on the <strong>Log Level</strong> preference (<strong>Window &rarr; Preferences &rarr; Grammatical Framework</strong>).</p>
<p>Additionally, everytime a grammar is <strong>Run</strong> a <em>new</em> console is opened to display the output. This console may also serve as the interactive GF Shell, depending on the <strong>Interactive Mode</strong> checkbox in your <strong>Run Configuration</strong>.</p>
<p>Additionally, every time a grammar is <strong>Run</strong> a <em>new</em> console is opened to display the output. This console may also serve as the interactive GF Shell, depending on the <strong>Interactive Mode</strong> checkbox in your <strong>Run Configuration</strong>.</p>
<p>Eclipse does not make it obvious when multiple console windows open; click on the <strong>Display Selected Console</strong> button to switch between open consoles:</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-console-icon.png" alt="Display Selected Console icon" /></p>
<p>If the process associated with a console window has terminated, it will be indicated in the upper-left corner as below. Such console windows can then be closed using the gray cross button:</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-console-terminated.png" alt="Close terminated console icon" /></p>
<p><em>The Eclipse console implementation does not support command history (up arrow) or auto-completion (tab).</em></p>
<h4>Logs</h4>
<h3>Logs</h3>
<p>The GFEP writes to the Eclipse platform log. This can be accessed in two ways:</p>
<ol>
<li>By opening the <strong>Error Log</strong> view in Eclipse</li>
<li>Accessing the file directly at <code>&lt;workspace&gt;/.metadata/.log</code></li>
</ol>
<p>You can set the log verbosity from <strong>Window &rarr; Preferences &rarr; Grammatical Framework</strong>.</p>
<h4>Validation</h4>
<h3>Validation</h3>
<p>For validation to work correctly, the project&#8217;s <strong>Build Automatically</strong> option should be turned on.</p>
@@ -268,7 +264,7 @@ files and manually add them to your Eclipse workspace to experiment with some of
<p>Sometimes you may get an entire file marked with errors, even though in fact there is only a single error which is causing the internal builder to fail. In such cases referring to the <strong>Problems</strong> view should help you locate the cause. This issue is particularly relevant when changes made to one module may induce errors in its descendants (e.g. renaming a parameter in a resource module). This behaviour will hopefully be improved in future versions.</p>
<hr />
<!----------------------------------------------------------------------------->
<h2>Evaluation &amp; feedback</h2>
@@ -290,12 +286,3 @@ files and manually add them to your Eclipse workspace to experiment with some of
<li>Feature wish-list</li>
<li>Compatibilities / conflicts with other Eclipse plugins</li>
</ol>
<h3>Logs</h3>
<p>The GFEP writes to the Eclipse platform log. This can be accessed in two ways:</p>
<ol>
<li>By opening the <strong>Error Log</strong> view in Eclipse</li>
<li>Accessing the file directly at <code>workspace/.metadata/.log</code></li>
</ol>