<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
]>

  <article id="visual-haskell">
  
    <articleinfo>

      <title>Visual Haskell User's Guide</title>
    <author>
      <firstname>Simon</firstname>
      <surname>Marlow</surname>
      <email>simonmar@microsoft.com</email>
    </author>
    <author>
      <firstname>Krasimir</firstname>
      <surname>Angelov</surname>
      <email>kr.angelov@gmail.com</email>
    </author>

<!--
    <abstract>
      <para></para>
    </abstract>
-->

    </articleinfo>

    <section id="sec-introduction">
      <title>Introduction</title>
      
      <para>Visual Haskell is a plugin for Microsoft's Visual Studio
	development environment to support development of Haskell software.
	Like the other Visual languages, Visual Haskell integrates with the
	Visual Studio editor to provide interactive features to aid Haskell
	development, and it enables the construction of projects consisting of
	multiple Haskell modules.</para>

      <section id="sec-obtaining">
	<title>Installing Visual Haskell</title>

	<para>In order to use Visual Haskell, you need <ulink url="http://msdn.microsoft.com/vstudio/productinfo/">Visual Studio .NET
	  2003</ulink>.  Right now, this is the only supported version of Visual
	  Studio - unfortunately we haven't yet added support for the 2005
	  Beta.  The Express languages (Visual C++ Express etc.) also will not
	  work, because they don't have support for plugins.</para>

	<para>You don't need to install GHC separately: Visual Haskell
	  is bundled with a complete GHC distribution, and various other tools
	  (Happy, Alex, Haddock).</para>

	<para>The latest Visual Haskell installer can be obtained from
	  here:</para>

	<para><ulink
	  url="http://www.haskell.org/visualhaskell/"><literal>http://www.haskell.org/visualhaskell/</literal></ulink></para>
      </section>

      <section id="release-notes">
	<title>Release Notes</title>

	<section>
	  <title>Version 0.0, first release</title>
	  
	  <para>This release is a technology preview, and should be considered
	    alpha quality.  It works for us, but you are fairly likely to
	    encounter problems.  If you're willing to try it out and report
	    bugs, we'd be grateful for the feedback.</para>

	  <itemizedlist>
	    <listitem>
	      <para>This release of Visual Haskell is bundled with a
		development snapshot of GHC, version 6.5 from around 14
		September 2005.  This version of GHC is used to provide the
		interactive editing features, and will be used to compile all
		code inside Visual Haskell.  It is possible that in future
		releases we may be able to relax this tight coupling between
		Visual Haskell and the bundled GHC.</para>

	      <para>Please note that future releases of Visual
		Haskell will update the compiler, and hence the
		packages, and so may break your code.  Also note that because
		the bundled GHC is not a released version, it may have bugs and
		quirks itself: please report them as usual to
		<email>glasgow-haskell-bugs@haskell.org</email>.</para>
	  </listitem>

	  <listitem>
	    <para>We're not making source code for the plugin generally
	      available at this time, due to licensing restrictions on the
	      Visual Studio APIs that the plugin uses (for more
	      information see <ulink
		url="http://msdn.microsoft.com/vstudio/extend/">Visual Studio
		Extensibility Center</ulink>).  If you're interested in
	      contributing to Visual Haskell, please get in touch with the
	      authors.</para>
	  </listitem>
	</itemizedlist>
      </section>
    </section>

      <section id="sec-bugs">
	<title>Getting support, reporting bugs</title>
	<para>Please report bugs to
	  <email>glasgow-haskell-bugs@haskell.org</email> (subscribe <ulink url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs">here</ulink>), clearly indicating
	  that your bug report relates to Visual Haskell, and giving as much
	  information as possible so that we can reproduce the bug.  Even if
	  you can't reproduce the bug reliably, it is still useful to report
	  what you've seen.</para>

	<para>For help and support, use the
	  <email>glasgow-haskell-users@haskell.org</email> (subscribe <ulink
	    url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users">here</ulink>) mailing list.</para>
      </section>

      <section id="sec-license">
	<title>License</title>

      <blockquote>
	<para>Copyright © Microsoft Corporation. All rights reserved.</para>
	<para>Copyright © The University of Glasgow. All rights reserved.</para>
	<para>Copyright © Krasimir Angelov. All rights reserved.</para>

	<para>Redistribution and use in source and binary forms, with or without
	  modification,  are permitted provided that the following conditions
	  are met:</para>

	<itemizedlist>
	  <listitem>
	    <para>Redistributions of source code must retain the above
	      copyright notice, this list of conditions and the following
	      disclaimer.</para>
	  </listitem>
 
	  <listitem>
	    <para>Redistributions in binary form must reproduce the above
	      copyright notice, this list of conditions and the following
	      disclaimer in the documentation and/or other materials provided
	      with the distribution.</para>
	  </listitem>

	  <listitem>
	    <para>The names of the copyright holders may not be used to endorse
	      or promote products derived from this software without specific
	      prior written permission.</para>
	  </listitem>
	</itemizedlist>

	<para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS
	  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
	  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
	  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
	  COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
	  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
	  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
	  AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
	  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	  POSSIBILITY OF SUCH DAMAGE.</para>
      </blockquote>
    </section>

    </section>

    <section id="sec-using">
      <title>Using Visual Haskell</title>

      <section>
	<title>Overview of features</title>

	<para>The following features are provided in the Visual Studio editor
	  when editing Haskell code:</para>

	<itemizedlist>
	  <listitem>
	    <para>Automatic checking of code as you type, and visual indication
	      of parse errors, scoping errors and type errors.</para>
	  </listitem>
	  
	  <listitem>
	  <para>Quick info: hovering the mouse over an identifier pops up
	    an information box, including the type of the identifier.</para>
	  </listitem>

	  <listitem>
	  <para>A drop-down bar at the top of the editing window lists the
	    top-level declarations in the module, and allows quick navigation
	    to a declaration.</para>
	  </listitem>

	  <listitem>
	  <para>Name completion for identifiers in scope: press Ctrl+Space
	    after a partial identifier to see the completions.</para>
	  </listitem>

	  <listitem>
	  <para>Go to declaration: right clicking on an identifier and
	    selecting "Go to declaration" will jump the cursor to the
	    declaration of the identifier.  This works for locally-defined
	    identifiers and those defined in another module of the project; it
	    does not work for library functions currently.</para>
	  </listitem>
	</itemizedlist>

      <para>The following features are provided by the project system for
	constructing Haskell projects:</para>

      <itemizedlist>
	<listitem>
	  <para>Multi-module Haskell projects are fully supported, based on the
	    <ulink url="http://www.haskell.org/cabal">Cabal</ulink>
	    infrastructure.  A project in Visual Haskell <emphasis>is</emphasis>
	    a Cabal package, and vice-versa.  A Visual Studio project can be
	    taken to a machine without Visual Haskell and built/installed as a
	    normal Cabal package, and an existing Cabal package can be edited
	    directly in Visual Haskell<footnote><para>This works as long as the
		Cabal package is using Cabal's simple build system; Cabal
		packages using their own build systems cannot be edited in Visual
		Haskell.</para>
	    </footnote>.</para>
	</listitem>

	<listitem>
	  <para>Editing of most of the package meta-data is supported through
	    the project property pages.</para>
	</listitem>

	<listitem>
	  <para>The interactive editing features work across multiple modules in
	    a project.  When one module is edited, changes are automatically
	    propagated to dependent modules, even if the edited module has not yet
	    been saved.</para>
	</listitem>

	<listitem>
	  <para>Building is supported through the Cabal build system, and build
	    errors are communicated back to the editor and placed in the task
	    list.  Use any of the Visual Studio build commands (e.g. Build
	    Project from the context menu on the project, or Ctrl-Shift-B to
	    build the whole solution).</para>
	</listitem>

      </itemizedlist>
    
    <para>Additionally, Visual Haskell is bundled with a large collection of
      documentation: the GHC manual, the hierarchical libraries reference, and
      other material all of which can be browsed within Visual Studio
      itself.</para>
    </section>

    <section>
      <title>Getting Started</title>
      
      <para>After installing Visual Haskell, start up Visual Studio as you
	would normally, and observe that on the splash screen where it lists
	the supported languages you should now see an icon for Visual
	Haskell (if you don't see this, something has gone wrong... please let
	us know).</para>
      
      <para>Firstly, take a look at the bundled documentation.  Go to
	Help-&gt;Contents, and you should see the &ldquo;Visual Haskell Help
	Collection&rdquo;, which contains a large collection of GHC and
	Haskell-related documentaiton, including this document.</para>

      <para>To start using Visual Haskell right away, create a new
	project (File-&gt;New-&gt;Project...).  Select one of the Haskell
	project types (Console Application or Library Package), and hit Ok.
	The project will be created for you, and an example module
	added: <literal>Main.hs</literal> for an application, or
	<literal>Module1.hs</literal> for a library.</para>
      
      <para>You can now start adding code to
	<literal>Main.hs</literal>, or adding new modules.  To add a new
	module, right-click on the <literal>src</literal> directory, and
	select Add-&gt;New Item.  Visual Haskell supports hierarchical
	modules too: you can add new folders using the same Add menu to
	create new nodes in the hierarchy.</para>
      
      <para>If you have any errors in your code, they will be underlined with
	a red squiggly line.  Select the Tasks window (usually a tab near the
	bottom of the Visual Studio window) to see the error messages, and
	click on an error message to jump to it in the editor.</para>
      
      <para>To build the program, hit Ctrl-Shift-B, or select one of the
	options from the Build menu.</para>
    </section>

    <section>
      <title>Editing Haskell code</title>

	<para>(ToDo: more detail here)</para>

	<para>Your module must be plain Haskell (<literal>.hs</literal>) for the interactive features to
	fully work.  If your module is pre-processed with CPP or Literate
	  Haskell, then Visual Haskell will only check the module when it is
	  saved; between saves the source will not be checked for errors and
	  the type information will not be updated.  If the source file is
	  pre-processed with Happy or another pre-processor, then you may have
	  to build the project before the type information will be updated
	  (because the pre-processor is only run as part of the build
	  process).  Pre-processed source files work fine in a multi-module
	  setting; you can have modules which depend on a pre-processed module
	  and full interactive checking will still be available in those
	  modules.</para>

	<para>Because Visual Haskell is using GHC as a backend for its
	  interactive editing features, it supports the full GHC language,
	  including all extensions.</para>
      </section>

      <section>
	<title>Using Projects</title>
	<para>(ToDo: more detail here)</para>
      </section>

    </section>
  </article>
