Permalink
Browse files

Documentation updated.

  • Loading branch information...
1 parent 450ad1a commit c3f0e4d6eb57988b67c98042c505bd1ee5c7494c @serras serras committed Aug 1, 2011
@@ -1,4 +1,11 @@
-<h2>A quick start guide to Haskell programming with Eclipse</h2>
+<html>
+<head>
+<link rel="stylesheet" href="../../PRODUCT_PLUGIN/book.css" type="text/css">
+</head>
+
+<body>
+
+<h1>A quick start guide to Haskell programming with Eclipse</h1>
<p>This document shows how you would create and run the 'Hello World'
application in Eclipse with Haskell support. It also explains some of the
@@ -159,4 +166,6 @@ <h3><a name="run">Run a module in the interpreter</a></h3>
<p>The launch configuration options for interpreter sessions let you configure some automation features, like automatically reloading modules that you've saved in the editor.</p>
+</body>
+</html>
@@ -1,4 +1,11 @@
-<h2>Installation steps</h2>
+<html>
+<head>
+<link rel="stylesheet" href="../../PRODUCT_PLUGIN/book.css" type="text/css">
+</head>
+
+<body>
+
+<h1>Installation steps</h1>
<p>If you see this, you have successfully installed the eclipseFP plugins.
However there may still be some configuration steps to be done before you can use the plugins fully.</p>
@@ -12,21 +19,39 @@ <h3>GHC configuration</h3>
<h3>Cabal configuration</h3>
<p>
EclipseFP also requires a working Cabal. <a href="http://www.haskell.org/haskellwiki/Cabal">Cabal</a> is a build management tool for Haskell. Similarly, the Haskell Platform contains a version of Cabal compatible with the GHC it ships with.
-You can configure Cabal in the Eclipse Preferences under <b>Haskell &gt; Scion and Cabal</b>. By default EclipseFP will have looked in your PATH and use any Cabal installation it can find there.
+You can configure Cabal in the Eclipse Preferences under <b>Haskell &gt; Scion, Browser and Cabal</b>. By default EclipseFP will have looked in your PATH and use any Cabal installation it can find there.
</p>
-<h3>Scion configuration</h3>
+<h3>Scion and Browser configuration</h3>
<p>
-Scion is a Haskell program that uses GHC and Cabal to give a consistent API to manage and build Haskell projects. EclipseFP uses Scion for a lot of operations.
-It comes with a version of Scion in source form, that should get built automatically once GHC and Cabal have been set up.
-The Eclipse Preferences page under <b>Haskell &gt; Scion and Cabal</b> allows you to change settings if required.
+Scion is a Haskell program that uses GHC and Cabal to give a consistent API to manage and build Haskell projects. EclipseFP uses Scion for a lot of operations.
+Scion-Browser is another small component that serves information about the installed packages in your system.
+Both come in source form, and they should get built automatically once GHC and Cabal have been set up.
+The Eclipse Preferences page under <b>Haskell &gt; Scion, Browser and Cabal</b> allows you to change settings if required.
We recommend to stick to default setting (built-in server through Standard Stream/Pipe) unless you feel adventurous!
</p>
-<h3>Problems building Scion</h3>
+<h4>Problems building Scion and Browser</h4>
<p>
-It may happen that Scion does not build successfully when you start EclipseFP.
+It may happen that Scion or Browser do not build successfully when you start EclipseFP.
The build process dumps its outputs and errors into a Console in the Console View of Eclipse. Please check this file for errors.
-Often, the build fails due to some libraries conflict. Please run <b>cabal update</b> before restarting EclipseFP.
+Often, the build fails due to some libraries conflict. Please run <code>cabal update</code> before restarting EclipseFP.
This will ensure your Cabal knows about the latest versions of libraries available on Hackage.
-</p>
+</p>
+
+<h3>Extra programs</h3>
+<p>
+You will get extra functionality if you install several Haskell programs. To be more concrete:
+<ul>
+<li>If you install <a href="http://www.haskell.org/hoogle/">Hoogle</a>, you will be able to search functions or types in your installed packages. To get it, run <code>cabal install hoogle</code>
+in a console. The next time EclipseFP starts, it will detect and configure it for use.</li>
+<li>If you install <a href="http://community.haskell.org/~ndm/hlint/">HLint</a>, suggestions for improving your code will appear in the Haskell editor. Install it running
+<code>cabal install hlint</code>.</li>
+<li>EclipseFP can run unit tests created with <a href="http://batterseapower.github.com/test-framework/">Test-framework</a>. You can install it running
+<code>cabal install test-framework test-framework-quickcheck2 test-framework-hunit</code> (to be able to use QuickCheck and HUnit tests).</li>
+<li>You can produce information about your modules using <a href="http://hackage.haskell.org/package/SourceGraph">SourceGraph</a>. Get it executing <code>cabal install SourceGraph</code>.</li>
+</ul>
+</p>
+
+</body>
+</html>
@@ -1,12 +1,19 @@
-<h2>Overview</h2>
+<html>
+<head>
+<link rel="stylesheet" href="../../PRODUCT_PLUGIN/book.css" type="text/css">
+</head>
+
+<body>
+
+<h1>Overview</h1>
<p>
This is the overview page for the functional programming tools features,
implemented by an open source project located at
<a href="http://eclipsefp.sourceforge.net">eclipsefp.sourceforge.net</a>.
</p>
-<h4>General</h4>
+<h3>General</h3>
<p>
<a href="http://eclipse.org">Eclipse</a> is an open source project that
@@ -21,7 +28,7 @@ <h4>General</h4>
programming language</a>.
</p>
-<h4>Contributors</h4>
+<h3>Contributors</h3>
<p>
<ul>
@@ -31,13 +38,14 @@ <h4>Contributors</h4>
<li>Andrei de A. Formiga</li>
<li>Leif Frenzel</li>
<li>Thiago Arrais</li>
+<li>Alejandro Serrano</li>
</ul>
</p>
<p>
... and of course all the people who try it and send feedback.
</p>
-<h4>Contact</h4>
+<h3>Contact</h3>
<p>Any feedback is most welcome. If you want to actively help visit
<a href="http://eclipsefp.sourceforge.net">eclipsefp.sourceforge.net</a> and
@@ -46,4 +54,7 @@ <h4>Contact</h4>
<p><ul><li>
Please select from the TOC at the left.
-</li></ul></p>
+</li></ul></p>
+
+</body>
+</html>
@@ -1,4 +1,11 @@
-<h2>Tips and Tricks</h2>
+<html>
+<head>
+<link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css">
+</head>
+
+<body>
+
+<h1>Tips and Tricks</h1>
<p>&nbsp;</p>
<table border="1" cellpadding="10" cellspacing="0" width="100%" style="border-collapse: collapse" bordercolor="#111111">
@@ -27,6 +34,6 @@ <h2>Tips and Tricks</h2>
</table>
<p>&nbsp;<br></p>
-</body>
+</body>
</html>
@@ -0,0 +1,50 @@
+<html>
+<head>
+<link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css">
+</head>
+
+<body>
+
+<h1>Haskell Browser</h1>
+
+<p>The Haskell Browser provides several ways to inspect the packages available in
+your system and read the documentation for their modules. To start using it, you must
+open the <i>Haskell Browser</i> perspective by either goint to
+<b>Window &gt; Open Perspective &gt; Other...</b> or clicking the <b>+</b> button
+in the upper right corner and selecting <b>Haskell Browser</b> from the list
+that will appear.</p>
+
+<p>You will see four views in the top part of Eclipse, named <i>Packages</i>,
+<i>Modules</i>, <i>Types</i> and <i>Functions</i>. In each of it, clicking an item
+will show its documentation in the bottom part of the corresponding view, and
+double-clicking it will open a window with Hackage documentation in HTML.
+Of course, it will also change the other views (selecting a new package changes the
+list of modules, selecting a new module the list of types and functions).</p>
+
+<p>Here are some tips for working with each view:
+<ul>
+<li>Apart from selecting a specific package, you can click on the <i>Local</i> item
+in the <i>Packages</i> view. This will make the <i>Modules</i> view show the information
+of <b>all</b> the modules available in your system.</li>
+<li>You can show the modules either in a flat style or hierarchicaly. Change between them
+using the <i>Style</i> submenu available in the upper right corner of the <i>Modules</i> view.</li>
+<li>In the <i>Types</i> view, we try to show the instances grouped. That means that if there is
+a instance using a class defined in the same module, the instance will be shown inside that class.
+And also that all the instances defined for a type within a module are shown inside that type.</li>
+</ul>
+</p>
+
+<h3>Hoogle</h3>
+
+<p>In the <i>Haskell</i> perspective, you may notice that a <i>Hoogle</i> view is available.
+This allows you to search your package database using the <a href="http://www.haskell.org/hoogle/">
+Hoogle</a> technology. Just write a query in the search box, and the results will be shown
+under it, along with documentation and information of where (package and module) to find
+the item.</p>
+
+<p><i>Tip</i>: you can search not only by name but also by type. To do that, write your query with
+a double colon in the front. For example, querying <code>:: (a -> b) -> [a] -> [b]</code> will return
+<code>map</code> among the results.</p>
+
+</body>
+</html>
@@ -1,12 +1,79 @@
-<h2>Cabal Package Description Editor</h2>
+<html>
+<head>
+<link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css">
+</head>
+
+<body>
+
+<h1>Cabal Package Description Editor</h1>
<p>Building projects in Eclipse relies on the
-Haskell <a href="http://haskell.org/cabal">Cabal</a>, and to allow you to easily view and modify your project's cabal file,
-there is an editor that supports Cabal's package description files.</p>
+Haskell <a href="http://haskell.org/cabal">Cabal</a>, and to allow you to easily view and
+modify your project's Cabal file, there is an editor that supports Cabal's package description files.</p>
+
+<p>Note that saving changes to the Cabal file will trigger a rebuild of the project.</p>
+
+<h3>Package</h3>
+
+<p>In the <b>Package</b> you can change the Cabal properties that affect the entire project.
+This includes descriptive properties such as project name, version, author, maintainer, license,
+description, homepage; and also properties that affect the build, such as minimal Cabal version.</p>
+
+<h4>Data files</h4>
+
+<p>Some packages need to access data files during its execution. The way Cabal has to deal with them
+can be configured in the Cabal editor:
+<ul>
+<li>Choose the files that will be available,</li>
+<li>This will create a new <code>Paths_&lt;package&gt</code> module which tells the paths to
+the files in the installed system,</li>
+<li>Remember to include this module in the <i>Other</i> section for each component that will
+need access to the data files.</li>
+</ul>
+</p>
+
+<h3>Components</h3>
-<p>That editor provides syntax coloring, code folding, a page for the Outline
-View, and makes also some templates available that let you easily create
-a new Cabal package description.</p>
+<p>Cabal deals with three kinds of components, that is, objects created from the source code.
+Those kinds are libraries, executables and test suites, and can be configured thorugh their
+respective tab in the Cabal editor.</p>
+
+<p>In general, there are four configuration sections for each component:
+<ul>
+<li>
+<i>Dependencies</i>: which include information of other packages needed to build the project.<br />
+You can add new dependencies clicking the <b>+</b> button. This will open a new window with
+the list of packages currently installed in your system.<br />
+If you want, you can add a version requirement using the <i>Version</i> column in the table.<br />
+</li>
+<li><i>Modules</i>: which tell the modules to gather to create the component. Each module can be
+in three different states: unselected; with the first column selected, that will expose the module
+(when editing a library) or will use it as entry point (when editing an executable or test suite);
+or with the second column selected, which will say that the module is a companion module.</li>
+<li><i>Source folders</i>: allow you to tell where the project files are located. When creating
+a new project, a <code>src</code> folder will be created, and it's recommended to place your
+files in that folder.</li>
+<li><i>Compiler options</i>: allow you to set flags or enable certain language extensions. Currently,
+this section only applies to GHC.</li>
+</ul>
+</p>
+
+<p>Each project can have at most one library. You can decide whether or not to build one in the
+<i>Library</i> tab.
+</p>
+
+<p>On the other hand, the <i>Executables</i> and <i>Test suites</i> tabs allow to have as many components
+as you want for that type. On the left of the window you will find the list of components that you
+already have in your project. You can add more clicking the <b>+</b> button above the list.</p>
+
+<p>For test suites, you can also select the type of test you are creating. Currently ony executable
+tests that use Test-framework can be run withing EclipseFP.</p>
+
+
+<h3>Source</h3>
+
+<p>The source tab provides and editor with syntax coloring, code folding, and makes also some
+ templates available that let you easily create a new Cabal package description.</p>
<p>The editor is by default registered for the file extension
<code>.cabal</code>. To trigger a template, hit <code>Control+SPACE</code>
@@ -15,5 +82,3 @@ <h2>Cabal Package Description Editor</h2>
key and point with the mouse on the value - the entry is then changed into
a link that takes you directly to the referenced file (if it exists) when
you click on it.</p>
-
-<p>Note that saving changes to the Cabal file will trigger a rebuild of the project.</p>
@@ -1,4 +1,11 @@
-<h2>Compilers and Interpreters</h2>
+<html>
+<head>
+<link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css">
+</head>
+
+<body>
+
+<h1>Compilers and Interpreters</h1>
<p>Please note that this IDE does not come with any Haskell language
implementations (compilers or interpreters). You need one of the supported
@@ -19,7 +26,7 @@ <h2>Compilers and Interpreters</h2>
<b>Run &gt; Run As</b> from the menu, then select the interpreter you want to
use.</p>
-<h4>Currently supported compilers</h4>
+<h3>Currently supported compilers</h3>
<p><ul>
<li>Glasgow Haskell Compiler (ghc):<br> <a href="http://haskell.org/ghc">
@@ -38,12 +45,15 @@ <h4>Currently supported interpreters</h4>
<!--
-<h4>Project specific compiler settings</h4>
+<h3>Project specific compiler settings</h3>
<p>Compiler settings in the preferences apply to every Haskell project in the
workspace. If you want specific settings for a project, you can override the
global settings for that project. Open the properties of the project (right-
click the project and select <b>Properties</b>), and then choose
<b>Compiler</b>. Here you can change the compiler settings for the selected
project only.</p>
--->
+-->
+
+</body>
+</html>
@@ -0,0 +1,41 @@
+<html>
+<head>
+<link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css">
+</head>
+
+<body>
+
+<h1>Debugging</h1>
+
+<p>This plug-in supports debugging of Haskell modules using GHCi. That means that the features
+in this section are available only if the module is run within a GHCi session. To do this,
+right-click the module, and select <b>Debug As &gt; GHCi session</b>.</p>
+
+<p>You can add breakpoints in your code double-clicking in the left margin of the source code
+editor. A small blue circle will appear in the selected line. You can delete the breakpoint
+double-clicking one of those circles. Note that currently EclipseFP does not allow to set
+breakpoints in particular expressions, only in entire lines.</p>
+
+<p>Once you start running functions in your module, it is recommended to change to the
+<i>Debug</i> perspective by going to the main menu and selecting
+<b>Window &gt; Open Perspective &gt; Debug</b>. This gives you access to the debugging tools.</p>
+
+<p>When a breakpoint is reached, the expression being evaluated is shown with a different
+background in the code editor. You can step or continue using the buttons available in
+the <i>Debug</i> view.</p>
+
+<p>You can also inspect the value of the variables in the <i>Variables</i> view. As withing GHCi,
+variables that aren't yet evaluated are shown as <code>_</code>.</p>
+
+<h3>Debugging an executable</h3>
+
+<p>EclipseFP does not support direct debugging of executables. However, you can simulate it
+following these steps:
+<li>Right-click your main module and select debugging within GHCi,</li>
+<li>If you havne't done it yet, add breakpoints to your code,</li>
+<li>In the GHCi console, write <code>main</code> and press the Enter key. This will
+execute the <code>main</code> function, which is the entry point of your application.</li>
+</p>
+
+</body>
+</html>
Oops, something went wrong.

0 comments on commit c3f0e4d

Please sign in to comment.