/[thuban]/branches/WIP-pyshapelib-bramz/Doc/manual/thuban-manual.xml

Diff of /branches/WIP-pyshapelib-bramz/Doc/manual/thuban-manual.xml

Parent Directory | Revision Log | View Patch Patch

-revision 1446 by jonathan,
Thu Jul 17 14:59:17 2003 UTC
+revision 1719 by jan,
Fri Sep 19 09:17:10 2003 UTC
 Line 1
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <!DOCTYPE book
          PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+     [<!ENTITY imgscale "70">]>
  <!-- $Revision$ -->
  <book>
    <bookinfo>
-     <title>Thuban Manual</title>
+     <title>User's Manual for Thuban 1.0</title>
-     <author>
+         <authorgroup>
-       <firstname>Jonathan</firstname><surname>Coles</surname>
+       <author>
-     </author>
+         <firstname>Jonathan</firstname><surname>Coles</surname>
-     <author>
+       </author>
-       <firstname>Jan-Oliver</firstname><surname>Wagner</surname>
+       <author>
-     </author>
+         <firstname>Jan-Oliver</firstname><surname>Wagner</surname>
+       </author>
+       <author>
+         <firstname>Frank</firstname><surname>Koormann</surname>
+       </author>
+         </authorgroup>
      <copyright>
        <year>2003</year>
        <holder>Intevation GmbH</holder>
      </copyright>
+    <revhistory>
+ <!-- comment this first revision out when releasing a real version -->
+ <!--
+      <revision>
+         <revnumber>CVS version $Id$</revnumber>
+         <date></date>
+         <revremark>Under development.</revremark>
+      </revision>
+ -->
+      <revision>
+         <revnumber>1.0pre2</revnumber>
+         <date>29-Aug-2003</date>
+         <revremark>
+                         Corresponds to Thuban development release 0.8.1.
+                         New: chapter on extensions.
+                 </revremark>
+      </revision>
+      <revision>
+         <revnumber>1.0pre1</revnumber>
+         <date>08-Aug-2003</date>
+         <revremark>Corresponds to Thuban development release 0.8.1.</revremark>
+      </revision>
+   </revhistory>
    </bookinfo>
    <chapter><title>Introduction</title>
      <para>
-     Thuban is a Free Software Geographic Information Systems (GIS) viewer.
+     Thuban is an interactive geographic data viewer.
-     It is being developed because there is currently no simple interactive
+     It has been developed because there was no simple interactive
      viewer for geographic information available as Free Software. Thuban is
      written in Python and C++ and uses the wxWindows library allowing it to
      run on many different platforms, including GNU/Linux and Windows.
      </para>
      <para>
-     GIS viewers are a necessary tool as they allow one to get a visual
+     Geographic data viewers are a necessary tool as they allow one to
+         get a visual
      impression of the positional relationship of the information that may not
      be apparent from simple inspection of the data values themselves.
      Thuban allows the user to create a session that displays
-Line 44
+Line 75
          <section><title>Installation</title>
          <para>
          Thuban is actively supported under Debian Testing (sarge), RedHat 7.2,
-         and Windows 2000. All the necessary files can be found on the
+         and Windows 2000. Thuban depends on the following packages. These
+         packages can also be found on the
          <ulink url="http://thuban.intevation.org/download.html">
          Thuban Download site
          </ulink>.
+         <itemizedlist>
+             <listitem><para>Python 2.2.1 (<literal>http://www.python.org</literal>)</para></listitem>
+             <listitem><para>wxWindows 2.4 (<literal>http://www.wxwindows.org</literal>)</para></listitem>
+             <listitem><para>wxPython 2.4 (<literal>http://www.wxpython.org</literal>)</para></listitem>
+             <listitem><para>proj 4.4.5 Projection Library (<literal>http://www.remotesensing.org/proj/</literal>)</para></listitem>
+             <listitem><para>GDAL 1.1.8 (<literal>http://www.remotesensing.org/gdal/</literal>)</para></listitem>
+             <listitem><para>SQLite 2.8.3 (<literal>http://www.hwaci.com/sw/sqlite/</literal>)</para></listitem>
+             <listitem><para>PySQLite 0.4.3 (<literal>http://pysqlite.sourceforge.net</literal>)</para></listitem>
+             </itemizedlist>
          </para>
+                 <para>
+                 Along with the source codes, the download page also offers
+                 full installation packages for Debian, Windows and RPM-based systems
+                 (Mandrake, RedHat, SuSE, etc).
+                 </para>
+                 <section><title>RPM-based GNU/Linux Systems</title>
+                         <section><title>Installing Binary Packages</title>
+                                 <para>
+                                 The most wide-spread RPM-based GNU/Linux Systems are RedHat,
+                                 Mandrake and SuSE. The documentation of these distributions
+                                 should contain information about how to install third-party
+                                 RPM packages. Nonetheless, a short summary is provided here.
+                                 </para>
+                                 <para>
+                                 RPM packages can be installed applying several tools.
+                                 The most basic one is the command line program "rpm".
+                                 The hardware architecture is identified in the name
+                                 of RPM packages, eg. 'i386' for most Intel/AMD architectures.
+                                 If you have a different hardware architecture, where no
+                                 binary RPM packages are provided, you must rebuild binary
+                                 packages from the RPM source packages first (see below).
+                                 Typical rpm commands look like:
+                                 <programlisting>
+                                 rpm --install Thuban-0.9.0-1.i386.rpm
+                                 </programlisting>
+                                 Depending on what you already have installed on your
+                                 system, you are informed that some packages are
+                                 required, but not installed. You need to install them
+                                 first. Either they are provided by your GNU/Linux distributor
+                                 or available somewhere on the Internet.
+                                 The more essential and special ones are provided together
+                                 with the Thuban package.
+                                 </para>
+                                 <para>
+                                 For rpm exist some graphical user interfaces, notably
+                                 kpackage, GnoRPM and xrpm.
+                                 </para>
+                                 <para>
+                                 Make yourself familiar with one of the tools and apply it
+                                 to install the packages.
+                                 Note, that you need to be administrator (root) for the system
+                                 to do that.
+                                 </para>
+                         </section>
+                         <section><title>Build Binaries from Source Packages</title>
+                                 <para>
+                                 This section describes howto build RPM install-packages
+                                 from RPM source-packages.
+                                 This adapts and optimizes an install-package specifically
+                                 to your system.
+                                 This is especially helpful to resolve version conflicts of
+                                 dependent packages. Furthermore, install-packages for other
+                                 platforms (e.g. PowerPC) can be created.
+                                 </para>
+                                 <para>
+                                 Note: rpm must be at least version 4. Execute
+                                 <literal>rpm --version</literal> to find out about the version.
+                                 </para>
+                                 <para>
+                                 You need to do the following preparations to be able to
+                                 build the packages as a regular user. You should now
+                                 perform the package buling as root since this
+                                 might cause damage to your system.
+                         <itemizedlist>
+                         <listitem>
+                                                 <para>
+                                                 Create RPM directory structure:
+                                                 Choose a directory (e.g. $HOME/myrpm) and create the
+                                                 subdirectories BUILD, RPM, SOURCES, SPECS and SRPMS.
+                                                 A possible command sequence for this is:
+                                                 <programlisting>
+                                                 mkdir $HOME/freegisrpm
+                                                 cd $HOME/freegisrpm
+                                                 mkdir BUILD RPMS SOURCES SPECS SRPMS
+                                                 </programlisting>
+                                                 </para>
+                                         </listitem>
+                                         <listitem>
+                                                 <para>
+                                                 Set environment variable RPM_DIR:
+                                                 <programlisting>
+                                                 export RPM_DIR=$HOME/freegisrpm
+                                                 </programlisting>
+                                                 </para>
+                                         </listitem>
+                                         <listitem>
+                                                 <para>
+                                                 Create $HOME/.rpmmacros:
+                                                 This file sets general preferences and some
+                                                 specific settings for signing packages.
+                                                 If you don't have a GnuPG-key, you can skip
+                                                 the signature settings i.e. drop the last 4 lines.
+                                                 A signature becomes important when you want to
+                                                 give away packages to third parties.
+                                                 <programlisting>
+ <![CDATA[
+ %packager Name Lastname <[email protected]>
+ %_topdir /home/mylogin/myrpm
+ %_signature gpg
+ %_gpg_name Name Lastname
+ %_pgp_path ~/.gnupg
+ %_pgpbin /usr/bin/gpg
+ ]]>
+                                                 </programlisting>
+                                                 </para>
+                                         </listitem>
+                         </itemizedlist>
+                                 Now you can install any RPM source-package.
+                                 It's components are installed into the corresponding
+                                 subdirectories of your rpm-directory.
+                                 Essentially these are the sources (into directory SOURCES)
+                                 and the so-called spec-file which contains all build
+                                 instructions. The spec-file will go into the SPEC directory.
+                                 Example:
+                                 <literal>rpm --install Thuban-0.9.0-1.src.rpm</literal>
+                                 </para>
+                                 <para>
+                                 Create install-package:
+                                 Go to the directory with the spec-files and rebuild the
+                                 package:
+                                 <programlisting>
+ cd $HOME/mypm/SPECS
+ rpm -bb thuban.spec
+                                 </programlisting>
+                                 Next, you will find the newly created package in
+                                 $HOME/myrpm/RPMS/i386.
+                                 If you build the package for another architecture than
+                                 i386, then the name of the directory has a corresponding name.
+                                 </para>
+                                 <para>
+                                 For documentation of RPM, either type
+                                 <literal>man rpm</literal> or <literal>rpm --help</literal>.
+                                 This will provide you with information on the various command
+                                 line options of RPM.
+                                 For more information see the
+                         <ulink url="http://www.rpm.org/">homepage of RPM</ulink>.
+                                 </para>
+                         </section>
+                 </section>
          </section>
          <section><title>The Main Window</title>
          <para>
-         <screenshot>
+         <figure>
-         <screeninfo>The Main Window</screeninfo>
+         <title>The Main Window</title>
          <mediaobject>
-         <imageobject><imagedata fileref="../mainwindow.png" format="PNG"/></imageobject>
+         <imageobject> <imagedata fileref="../images/1_2_mainwindow.png" format="PNG" scale="&imgscale;"/> </imageobject>
-         <textobject><phrase>The Main Window</phrase></textobject>
+         <imageobject> <imagedata fileref="./images/1_2_mainwindow.ps" format="EPS" scale="&imgscale;"/> </imageobject>
-         <caption><para>The Main Window</para></caption>
          </mediaobject>
-         </screenshot>
+         </figure>
          </para>
          <para>
-         The map window (1) shows the current state of the map and is where
+         The map window shows the current state of the map and is where
          the user can interact with the map using the tools.
          </para>
          <para>
-         The legend on
+         The legend on the left displays a list of the current layers and
-         the left (2) displays a list of the current layers and any visible
+         any visible classification groups. In the example, each shape layer
-         classification groups. In the example, each shape layer has a default
+         has a default classification which specifies how the shapes in each
-         classification which specifies how the shapes in each layer are
+         layer are drawn. Layers that are higher in the list appear
-         drawn. Layers that are higher in the list appear ``closer'' to the
+         ``closer'' to the user. The legend can be closed by clicking on the
-         user. The legend can be closed by clicking on the small X in the
+         small X in the upper right-hand region of the legend.
-         upper right-hand region of the legend. To open it again, use
+         To open it again, use
          <menuchoice>
          <guimenu>Map</guimenu>
          <guimenuitem>Legend</guimenuitem>
          </menuchoice>.
          The legend is also dockable, which means that it can be detached
          from the main window by clicking on the small button next to the
-         close button. It can be attached again by clicking the same button
+         close button. It can be attached by clicking the same button
          again.
          </para>
          <para>
-         The status bar (3) displays different information depending on the
+         The status bar displays different information depending on the
          current context. If the user is selecting an item from the menu
          then the status bar will display a short help message indicating
          what each menu item is for. If the user has a tool selected then
          the position of the cursor on the map is displayed.
          </para>
          <para>
-         The tool bar (4) provides quick access to the commonly needed tools.
+         The tool bar provides quick access to the commonly needed tools.
          By hovering over each button the user can see a short messages
          describing what the tool does. The tools provided are Zoom In, Zoom
-         Out, Pan, Full Extent, Full Layer Extent, Full Shape Extent, Indentify,
+         Out, Pan, Full Extent, Full Layer Extent, Full Shape Extent, Identify,
          and Label. Each of the tools will be explained in further detail later
          in the manual.
          </para>
-Line 112
+Line 301
          <menuchoice>
          <guimenu>File</guimenu>
          <guimenuitem>New Session</guimenuitem>
          </menuchoice>.
          If a session is already loaded and has been modified without
          being saved a prompt will ask if the current session should
-         be saved.
+         be saved. A new session consists of an empty map with no
+         layers and no tables.
          </para>
          </section>
-Line 127
+Line 315
          <menuchoice>
          <guimenu>File</guimenu>
          <guimenuitem>Open Session</guimenuitem>
-         </menuchoice>.
+         </menuchoice>. A dialog box will open allowing the user to browse
+         for a Thuban Session file. Thuban session files end with
+         <varname>.thuban</varname>. Selecting a file a clicking
+         <guibutton>OK</guibutton> will load the session into Thuban.
          If a session is already loaded and has been modified without
          being saved a prompt will ask if the current session should
-Line 141
+Line 332
          <menuchoice>
          <guimenu>File</guimenu>
          <guimenuitem>Save Session</guimenuitem>
-         </menuchoice>.
+         </menuchoice>. A dialog box will open allowing the user to browse
+         the file system and select a place to save the session. Thuban
+         sessions should be saved under a name ending in
+         <varname>.thuban</varname>. If the file already exists the user
+         will be prompted to save under a different name or overwrite the
+         existing file.
          </para>
          </section>
          <section><title>The Session Info-Tree</title>
+         <para>
+         <figure>
+         <title>Session Info Tree</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/2_4_session_tree.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/2_4_session_tree.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
+         </para>
          <para>
-                 (primarily for developers)
+         The session info-tree is primarily intended for developers working
+         with Thuban. It displays many of the internal values for the session,
+         map, and layers. It can be opened from
+         <menuchoice>
+         <guimenu>File</guimenu>
+         <guimenuitem>Session Tree</guimenuitem>
+         </menuchoice>.
          </para>
          </section>
    </chapter>
    <chapter><title>Map Management</title>
      <para>
+     The map consists of a number of layers where each layer represents a
+     different type of data set. By interacting with the map the user can
+     visually explore the data.
+     </para>
+     <para>
+     The map can have a name that will appear in the Thuban title bar.
+     The map name can be changed using
+     <menuchoice>
+     <guimenu>Map</guimenu>
+     <guimenuitem>Rename</guimenuitem>
+     </menuchoice>.
+     </para>
+     <para>
+     <inlinemediaobject>
+     <imageobject>
+     <imagedata fileref="../images/3_rename_map.png" format="PNG" scale="&imgscale;"/>
+     </imageobject>
+     <imageobject>
+     <imagedata fileref="./images/3_rename_map.eps" format="EPS" scale="&imgscale;"/>
+     </imageobject>
+     <textobject> <phrase>Rename Map</phrase> </textobject>
+     </inlinemediaobject>
      </para>
          <section><title>Adding and Removing Layers</title>
          <para>
+         There are two types of layers that can be added to a map: Shape layers
+         and image layers. Shape layers are stored in Shapefile format, a
+         widely used file format for storing geographic objects. These
+         files have the extension ``.shp''. Associated with
+         the shape file is a database file which stores attributes for
+         each shape in the Shape file. This file, in dBase format,
+         has the extension ``.dbf''. Both files must have the same base name.
+         For example, if there is a shape file named roads.shp there must
+         also be a file roads.dbf.
+         </para>
+         <para>
+         Shape layers can be added to the map with
+         <menuchoice>
+         <guimenu>Map</guimenu>
+         <guimenuitem>Add Layer</guimenuitem>
+         </menuchoice>.
+         Initially, only the ``.shp'' files are shown which is enough for the
+                 selection. However, if you switch to display all files and select one
+                 of the associated files (e.g. ``.dbf''), Thuban will recognize the base
+                 name and load the corresponding Shape file.
+         </para>
+                 <para>
+                 The file dialog for Shape files allows to select multiple files.
+                 Use the shift-button together with the left mouse button to extend
+                 the selection.
+         </para>
+         <para>
+         Image layers can be added to the map with
+         <menuchoice>
+         <guimenu>Map</guimenu>
+         <guimenuitem>Add Image Layer</guimenuitem>
+         </menuchoice>.
+         It is important to select a valid image file that has geographic
+         data associated with it. The data can be embedded in the file itself,
+         or in another file. If geographic information cannot be found, Thuban
+         will report an error.
          </para>
          </section>
          <section><title>Navigation</title>
          <para>
+         The map can be explored by using the navigation tools available on
+         the tool bar or from the
+         <menuchoice><guimenu>Map</guimenu></menuchoice> menu.
+         </para>
+         <itemizedlist>
+         <listitem>
+         <para>
+         The ZoomIn tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_2_zoomin.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_2_zoomin.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>ZoomIn Tool</phrase> </textobject>
+         </inlinemediaobject>
+         enlarges a region of the map. Clicking once on the map
+         will double the magnification and center the map on the point that
+         was clicked. Clicking and dragging selects a region that will be
+         enlarged to fit the window.
+         </para>
+         </listitem>
+         <listitem>
+         <para>
+         The ZoomOut tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_2_zoomout.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_2_zoomout.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>ZoomOut Tool</phrase> </textobject>
+         </inlinemediaobject>
+         shrinks the map so that a larger region is visible. A single click
+         reduces the magnification by a factor of two. Clicking and dragging
+         selects a box such that the current contents of the window will be
+         scaled to fit into that box.
+         </para>
+         </listitem>
+         <listitem>
+         <para>
+         The Pan tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_2_pan.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_2_pan.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Pan Tool</phrase> </textobject>
+         </inlinemediaobject>
+         allows the user to move the map around by clicking and dragging.
+         </para>
+         </listitem>
+         <listitem>
+         <para>
+         The Full Extent tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_2_fullextent.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_2_fullextent.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Full Extent Tool</phrase> </textobject>
+         </inlinemediaobject>
+         rescales the viewable region so that the entire map is visible.
+         </para>
+         </listitem>
+         <listitem>
+         <para>
+         The Full Layer Extent tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_2_fulllayerextent.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_2_fulllayerextent.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Full Layer Extent Tool</phrase> </textobject>
+         </inlinemediaobject>
+         rescales the viewable region so that the currently selected
+         layer fits within the window. If no layer is selected this button
+         will be disabled.
+         </para>
+         </listitem>
+         <listitem>
+         <para>
+         The Full Shape Extent tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_2_fullshapeextent.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_2_fullshapeextent.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Full Shape Extent Tool</phrase> </textobject>
+         </inlinemediaobject>
+         rescales the viewable region so that the currently selected
+         shape fits within the window. If the shape is a point, it is
+         centered and the map is zoomed all the way in. If no shape is
+         selected this button will be disabled. This feature is especially
+         helpful when identifying an object related to a selected record
+         in a tableview (see below).
          </para>
+         </listitem>
+         </itemizedlist>
          </section>
          <section><title>Object Identification</title>
          <para>
+         Objects on the map can be identified using the Identify tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_3_identify.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_3_identify.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Identify Tool</phrase> </textobject>
+         </inlinemediaobject>.
+         Clicking on an object selects that object and opens a dialog which
+         shows all the table attributes for that object. Any current selection
+         is lost. Objects on the map are typically shapes and this document
+         will often refer to objects as shapes.
          </para>
          </section>
-         <section><title>Object Labelling</title>
+         <section><title>Object Labeling</title>
          <para>
+         Objects can be labeled using the Label tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_3_label.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_3_label.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Label Tool</phrase> </textobject>
+         </inlinemediaobject>.
+         Clicking on an object selects that object and opens a dialog which
+         displays the table attributes for that object. An attribute can
+         be selected to be the label on the map. The label will be placed
+         at the center of the shape. Clicking on an object that already has
+         a label will remove the label.
          </para>
          </section>
          <section><title>The Legend</title>
+         <para>
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_5_legend.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_5_legend.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Legend</phrase> </textobject>
+         </inlinemediaobject>
+         </para>
          <para>
+         The Legend provides an overview of the layers in the map. Layers
+         that appear higher in the legend will appear ``closer'' to the user.
+         If a layer supports classification (currently, only shape layers
+         have this feature) then the classification groups will be shown
+         below each layer. The properties for each group are also displayed
+         with a small graphic. Polygon layers appear as rectangles, lines
+         appear as curved lines, and points appear as circles.
+         </para>
+         <para>
+         Along the top of the legend is a toolbar which allows quick access
+         to some of the layer manipulation options under
+         <menuchoice><guimenu>Map</guimenu></menuchoice>.
+         </para>
+         <itemizedlist>
+         <listitem>
+         <para>
+         The Move Layer to Top tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_5_totop.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_5_totop.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Move Layer to Top</phrase> </textobject>
+         </inlinemediaobject> raises the selected layer to the top of the map.
+         </para>
+         </listitem>
+         <listitem>
+         <para>
+         The Move Layer Up tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_5_moveup.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_5_moveup.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Move Layer Up</phrase> </textobject>
+         </inlinemediaobject> raises the selected layer one level.
+         </para>
+         </listitem>
+         <listitem>
+         <para>
+         The Move Layer Down tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_5_movedown.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_5_movedown.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Move Layer Down</phrase> </textobject>
+         </inlinemediaobject> lowers the selected layer one level.
+         </para>
+         </listitem>
+         <listitem>
+         <para>
+         The Move Layer to Bottom tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_5_tobottom.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_5_tobottom.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Move Layer to Bottom</phrase> </textobject>
+         </inlinemediaobject> lowers the selected layer to the bottom of the map.
+         </para>
+         </listitem>
+         <listitem>
+         <para>
+         The Visible tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_5_visible.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_5_visible.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Visible</phrase> </textobject>
+         </inlinemediaobject> shows the selected layer in the map if it was
+         hidden.
+         </para>
+         </listitem>
+         <listitem>
+         <para>
+         The Invisible tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_5_invisible.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_5_invisible.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Invisible</phrase> </textobject>
+         </inlinemediaobject> hides the selected layer in the map.
+         </para>
+         </listitem>
+         <listitem>
+         <para>
+         The Properties tool
+         <inlinemediaobject>
+         <imageobject>
+         <imagedata fileref="../images/3_5_props.png" format="PNG" scale="&imgscale;"/>
+         </imageobject>
+         <imageobject>
+         <imagedata fileref="./images/3_5_props.eps" format="EPS" scale="&imgscale;"/>
+         </imageobject>
+         <textobject> <phrase>Properties</phrase> </textobject>
+         </inlinemediaobject> opens the layer's properties dialog box.
+         Double-clicking on a layer or a group of a layer will open the
+         properties dialog for that layer.
          </para>
+         </listitem>
+         </itemizedlist>
+         <para>
+         Along the bottom of the legend is the scalebar. The scalebar
+         will be available if there are any layers and the  map has a
+         projection set.
+         </para>
+         </section>
+         <section><title>Exporting</title>
+         <para>
+         Under Windows, maps can be exported in Enhanced Metafile format
+         (<varname>.wmf</varname>)
+         from
+         <menuchoice>
+         <guimenu>Map</guimenu>
+         <guimenuitem>Export</guimenuitem>
+         </menuchoice> for use in reports, presentations, or further
+         modification. The current map view, legend, and, if available,
+         scalebar are exported. Under other platforms this option is not
+         available. Clicking this menu item open a file selection dialog
+         that lets the user select a location to export the map.
+         </para>
          </section>
          <section><title>Printing</title>
          <para>
+         The map can be printed using
+         <menuchoice>
+         <guimenu>Map</guimenu>
+         <guimenuitem>Print</guimenuitem>
+         </menuchoice>. The current map view, legend, and, if available,
+         scalebar are printed. A standard printing dialog will open allowing
+         the user to configure the printer. This dialog will differ depending
+         on which platform Thuban is running.
          </para>
          </section>
    </chapter>
    <chapter><title>Layer Management</title>
-Line 194
+Line 764
          <section><title>Types of Layers</title>
          <para>
+         There are two types of layers supported by Thuban: shape layers and
+         image layers. Shape layers consist of vector based shapes with
+         geo-referenced coordinates. There are three types of supported
+         shapes: polygons, lines (arc), and points. Image layers can be any image
+         file format supported by the Geo-spatial Data Abstraction Library
+         (GDAL). The images must have geographic
+         coordinate data either embedded within the file or in a separate
+         file that is in the same directory as the image file. GeoTIFF files
+         work very well with Thuban and were designed specifically to be image
+         layers in GIS programs.
          </para>
+         <para>
+         All actions in the
+         <menuchoice>
+         <guimenu>Layer</guimenu>
+         </menuchoice> menu act on the currently selected layer in the legend.
+         </para>
          </section>
-         <section><title>Visibility</title>
+         <section><title>Properties</title>
          <para>
+         To view the properties for a layer it must first be selected in the
+         legend. The menu option
+         <menuchoice>
+         <guimenu>Layer</guimenu>
+         <guimenuitem>Properties</guimenuitem>
+         </menuchoice> opens a dialog that displays a layer's properties.
+         All layers have a title which can be modified in the text field
+         provided. The type of layer is also shows. If the type is a type
+         of shape (polygon, arc, point) the classification table will be
+         shown. Image layers have no other properties other than title
+         and type.
+         </para>
+         <para>
+         <figure>
+         <title>Properties Window</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/4_2_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/4_2_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
+         </para>
+         <para>
+         <figure>
+         <title>Properties Window</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/4_2_raster_layer_properties.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/4_2_raster_layer_properties.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
          </para>
          </section>
-         <section><title>Sequence</title>
+         <section><title>Visibility</title>
          <para>
+         Sometimes it is not desirable to view all layers at the same time.
+         Some layers may take a long time to draw and so while navigating
+         around the map the user may not want to wait for the map to redraw
+         all the layers each time the map is changed. Each layer can be
+         independently turned on or off using the
+         <menuchoice>
+         <guimenu>Layer</guimenu>
+         <guimenuitem>Show</guimenuitem>
+         </menuchoice>
+         or
+         <menuchoice>
+         <guimenu>Layer</guimenu>
+         <guimenuitem>Hide</guimenuitem>
+         </menuchoice> options respectively.
          </para>
          </section>
          <section><title>Duplication</title>
          <para>
+         Layers and all their properties, including classifications, can
+         be duplicated using
+         <menuchoice>
+         <guimenu>Layer</guimenu>
+         <guimenuitem>Duplicate</guimenuitem>
+         </menuchoice>. Duplicating a layer is useful if the user wishes
+         to model a layer in several different ways. Even though the layers
+         overlap, by carefully selecting the shape properties it is possible
+         to display several pieces of information at once. For example, one
+         copy of a roads layer may be classified on a length property and
+         another copy may be classified on a type property. If the length
+         property was expressed with color and the type property expressed
+         with line thickness then it would be possible to view both
+         classifications by placing the type property copy over the
+         length property copy.
          </para>
          </section>
-         <section><title>Properties</title>
-         <para>
-         </para>
-         </section>
    </chapter>
    <chapter><title>Layer Classifications</title>
      <para>
+     A layer classification is a way of assigning drawing properties to
+     groups of shapes based on attributes stored in the layer's table.
+     Only layer's with shapes can have a classification; image layers
+     cannot be classified.
+     </para>
+     <para>
+     A classification consists of a number of groups, each group
+     having a value or range of values to match against, and symbol
+     properties which control how a shape is drawn on the map. The user
+     selects which field in the table is used by the classification and
+     when the map is drawn the value for that field for each shape is
+     compared with each group's value. The properties of the first group
+     to match are used to draw the shape. This allows the user to get a
+     visual impression of not only how the data is laid out but also what
+     kind of data lies where.
+     </para>
+     <para>
+     A layer always has a classification. When a new layer is added to the
+     map, a default classification is created with the DEFAULT group. This
+     group cannot be removed but can be hidden (see below). Every shape in the
+     layer, regardless of its attributes, will match this group if no other
+     group matches.
      </para>
-         <section><title>Adding and Removing Classes</title>
+         <section><title>Editing Classifications</title>
          <para>
+         A layer's classification can be modified under the properties dialog
+         (<menuchoice>
+         <guimenu>Layer</guimenu>
+         <guimenuitem>Properties</guimenuitem>
+         </menuchoice>). The layer's classification field can be set to None,
+         which simply assigns a DEFAULT group to the classification. No new
+         groups can be added to the classification if the field is None.
+         The user must first select a field to classify on. New groups can
+         be added to the classification with the <guibutton>Add</guibutton>
+         button.
+         </para>
+         <para>
+         To apply the changes to the map the user can click
+         either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
+         <guibutton>Try</guibutton> will not close the dialog box, allowing
+         the user to see how the classification changes the map.
+         <guibutton>Revert</guibutton> will undo the last classification applied
+         to the map. <guibutton>OK</guibutton> will commit the changes and
+         close the dialog. The user will be unable to undo the changes.
+         <guibutton>Close</guibutton> simply closes the dialog box. If any
+         changes have not been applied with <guibutton>Try</guibutton> the
+         changes will not be applied to the map.
+         </para>
+         <para>
+         <figure>
+         <title>Properties Window</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/5_classification.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/5_classification.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
+         </para>
+         <para>
+         The order of the groups in the classification is significant
+         except for the DEFAULT group, which remains at the top. When shapes
+         are matched against groups the matching begins at the first group
+         after the DEFAULT group so that groups higher in the list will
+         be checked first. Matching for a
+         given shape will stop at the first group that matches. The user can
+         use <guibutton>Move Up</guibutton> and <guibutton>Move Down</guibutton>
+         to change the order of the groups. The DEFAULT group will always
+         match a shape that hasn't matched another group.
          </para>
+             <section><title>Visible</title>
+             <para>
+             The Visible column has check-boxes that determine whether a
+             classification group will be displayed in the legend. This is
+             useful if the user knows that the groups completely cover
+             the data set and don't want the DEFAULT group to be displayed
+             in the legend and on a printout.
+             </para>
+         </section>
+             <section><title>Symbols</title>
+             <para>
+             Each type of shape has its own type of symbol. Thuban supports three
+             types of shapes: polygons, lines, and points. Polygons and points
+             have outline and fill color, while lines have only line color. Each
+             group has associated symbol properties. To edit the symbol
+             properties for a group the user can double click on the Symbol
+             column or select a group and click the
+             <guibutton>Edit Symbol</guibutton> button.
+             </para>
+             </section>
+         <section><title>Value</title>
+             <para>
+             The Value column of the classification table is the value that will
+             be matched when the map is being drawn. The type of data that can
+             entered into this field depends on the type of data of the
+             classification field.
+             </para>
+             <para>
+             If the field is of type Text, anything entered
+             into the field is valid. The text will be compared literally to the
+             value of the shape attribute, including case sensitivity.
+             If the type is Integer, then any valid integer may be entered. In
+             addition, with special syntax, a range of values can be entered.
+             A range from <varname>start</varname> to <varname>end</varname>
+             inclusive is specified like this: <literal>[start;end]</literal>.
+             The exclusive range is specified like this:
+             <literal>]start;end[</literal>. Ranges can include infinity like
+             this: <literal>[-oo;oo]</literal>. Field types can also be of type
+             Decimal. They represent any rational number and can be used in
+             ranges as well.
+             </para>
+             </section>
+             <section><title>Label</title>
+             <para>
+             By default, the text that is displayed for a group in the legend
+             is the value for that group. The label can substitute a more
+             descriptive term in the legend.
+             </para>
+         </section>
          </section>
-         <section><title>Symbols</title>
+         <section><title>Generating Classes</title>
          <para>
+         <figure>
+         <title>Generate Class</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/5_3_genclass.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/5_3_genclass.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
          </para>
-         </section>
-         <section><title>Generating Classes</title>
          <para>
+         Creating a classification by hand can be tedious.
+         Thuban, therefore, provides a means of generating an entire
+         classification at once while still giving the user control over
+         how it appears. Clicking <guibutton>Generate Class</guibutton>
+         opens the <varname>Generate Classification</varname> dialog.
+         Under the <varname>Generate</varname> pull down there are at most
+         three different ways to generate classifications:
+         Unique Values, Uniform Distribution, and Quantiles. Some options
+         may not be available if the data type for the field does not
+         support them. For instance, <varname>Uniform Distribution</varname>
+         doesn't make sense for a Text field.
          </para>
+         <para>
+         For every way of generating a classification, a color scheme must
+         be selected. Thuban provides several different color schemes that
+         affect how the group properties change over the classification.
+         It may be desirable that only certain properties change over the
+         classification. If the shape type is a polygon or a point then
+         the <guibutton>Fix Border Color</guibutton> option will be available.
+         This allows the user to select a border color for all classification
+         groups.
+         It is also possible to create a custom color scheme. Selecting
+         this option will display two symbols: the one of the left has the
+         properties of the first group and the one on the right has the
+         properties of the last group. Thuban will interpolate between these
+         two properties to generate the other groups.
+         <figure>
+         <title>Custom Color Scheme</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/5_2_custom_ramp.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/5_2_custom_ramp.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
+         </para>
+         <para>
+         The Unique Values option lets the user select specific values that
+         appear in the table. Clicking <guibutton>Retrieve From Table</guibutton>
+         searches the table for all unique values and displays them in the
+         list on the left. Items can be selected and moved to the list on the
+         right. Each list can be sorted or reversed for easier searching.
+         The classification that is generated will be in the same order as
+         the list on the right.
+         <figure>
+         <title>Unique Values</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/5_2_unique_values.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/5_2_unique_values.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
+         </para>
+         <para>
+         The Uniform Distribution option creates a user specified number of
+         groups of ranges such that each range covers equal intervals. The
+         minimum and maximum values can automatically be retrieved from the
+         table by clicking <guibutton>Retrieve From Table</guibutton>. The
+         stepping is how large each interval is. Adjusting this value will
+         automatically recalculate how many groups is appropriate.
+         <figure>
+         <title>Uniform Distribution</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/5_2_uniform_dist.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/5_2_uniform_dist.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
+         </para>
+         <para>
+         The Quantiles option generates ranges based on the number of items
+         in the table. For example, by specifying five groups Thuban will
+         generate five groups with appropriate ranges such that 20% of the table
+         data is in each group. If it is impossible to generate exact
+         groupings, Thuban will issue a warning but allow the user to continue.
+         <figure>
+         <title>Quantiles</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/5_2_quantiles.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/5_2_quantiles.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
+         </para>
          </section>
    </chapter>
    <chapter><title>Projection Management</title>
      <para>
+     Projections control how the geographic data is displayed on the screen.
+     If multiple layers are loaded into Thuban where the geographic data
+     is in a different projection system, then the user must specify a
+     projection for each layer. The user must also tell Thuban which
+     projection the map is in. This can be the same as the layers or a different
+     projection in which case the layers are reprojected into that space.
+     The map projection can be set using
+     <menuchoice>
+     <guimenu>Map</guimenu>
+     <guimenuitem>Projection</guimenuitem>
+     </menuchoice> and the layer projection can be set using
+     <menuchoice>
+     <guimenu>Layer</guimenu>
+     <guimenuitem>Projection</guimenuitem>
+     </menuchoice>.
+     <figure>
+     <title>Projection Window</title>
+     <mediaobject>
+     <imageobject><imagedata fileref="../images/6_projection.png" format="PNG" scale="&imgscale;"/></imageobject>
+     <imageobject><imagedata fileref="./images/6_projection.eps" format="EPS" scale="&imgscale;"/></imageobject>
+     </mediaobject>
+     </figure>
+     </para>
+     <para>
+     Thuban is distributed with a sample collection of projections. The
+     user can create new projections and make them available to all
+     future Thuban sessions. They may also be exported and imported so
+     that custom projections can be distributed.
      </para>
+         <section><title>Selecting a Projection</title>
+         <para>
+         The available projections are listed on the left. If the layer
+         or map already has a projection it will initially be highlighted
+         and will end with <varname>(current)</varname>. Selecting
+         <varname>&lt;None&gt;</varname> will cause Thuban to use the data as
+         it appears in the source file and will not use a projection.
+         </para>
+     </section>
+         <section><title>Editing a Projection</title>
+         <para>
+         Whenever a projection is selected from the list its properties
+         are displayed on the right. These properties can be changed
+         and the changes saved to the selected projection using
+         <guibutton>Update</guibutton>. Only a projection that comes
+         from a file can be updated, so if the current layer's projection
+         is selected, <guibutton>Update</guibutton> will be disabled.
+         <guibutton>Add to List</guibutton> adds the projection to the
+         list of available projections as a new entry, and thus makes it
+         available to future Thuban sessions. Clicking <guibutton>New</guibutton>
+         will create an entirely new, empty projection. The
+         <guibutton>Remove</guibutton> button will permanently remove a
+         projection from the list of available projections.
+         </para>
+         <para>
+         To apply the selected projection to the map the user can click
+         either <guibutton>Try</guibutton> or <guibutton>OK</guibutton>.
+         <guibutton>Try</guibutton> will not close the dialog box, allowing
+         the user to see how the projeciton changes the map.
+         <guibutton>Revert</guibutton> will undo the last projection applied
+         to the map. <guibutton>OK</guibutton> will commit the changes and
+         close the dialog. The user will be unable to undo the changes.
+         <guibutton>Close</guibutton> simply closes the dialog box. If no
+         selection has been applied with <guibutton>Try</guibutton> the
+         selection will not be applied to the map.
+         </para>
+     </section>
+         <section><title>Importing/Exporting Projections</title>
+         <para>
+         The projections that appear in the list of available projections
+         can be exported to another file that the user chooses. By selecting
+         one or more projections and clicking <guibutton>Export</guibutton>
+         the user will be able to select a file in which to store those
+         projections.
+         The file can then be distributed to other Thuban users. To import
+         a projection file the user can click <guibutton>Import</guibutton>.
+         The imported projections are added to the list and are then available
+         to the current session and any future Thuban sessions.
+         </para>
+     </section>
    </chapter>
    <chapter><title>Table Management</title>
      <para>
+     Thuban distinguishes two different types of tables: Attribute tables
+     (which belong to a layer) and normal data tables. Both provide
+         the same general functionality with the difference that actions on an
+     attribute table might also effect the map display.
      </para>
+     <section><title>Table View</title>
+         <para>
+         <figure>
+         <title>Table View</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/7_1_table_view.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/7_1_table_view.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
+         </para>
+         <para>
+         Thuban provides a standard dialog to display table contents, the
+         Table View. The view has five sections: The title, selections,
+         the table grid, export functions, and the status bar.
+         </para>
+         <para>
+         The title bar identifies the table with its name.
+         </para>
+         <para>
+         The selections box let the user perform simple analysis on the data
+         based on comparisons: The first choice must be a field identifier of
+         the table, the second choice determines the type of comparison. The
+         third choice can be either a specific value (interpreted as numerical
+         or string depending on the type of the first field) or a second field
+         identifier. Thus you can perform analysis like selecting all
+         records where <literal>population > 10000</literal> or
+         <literal>cars_per_inhabitant < bikes_per_inhabitant</literal>
+         (note that the field names are only explanatory, the dBase files
+         allow only 11 character field names).
+         Selections can be combined either by applying a selection only on
+         a previously selected set of records or by adding the results of a
+         selection to a previous set. The default is that a selection replaces
+         earlier results.
+         </para>
+         <para>
+         The table grid shows the contents of the table (one record per row),
+         with highlighted selection results. Columns and rows can be resized.
+         </para>
+         <para>
+         The contents of a table can be exported into a file, either dBase
+         format (DBF) or comma separated values (CSV). The
+         <guibutton>Export</guibutton> button
+         raises a file dialog to specify a path and file name, the export type
+         is determined by the file extension (either .dbf or .csv).
+         The <guibutton>Export Selection</guibutton> button works similarly
+         but exports only the selected records.
+         The <guibutton>Close</guibutton> button closes the table view window.
+         This is different from the menu item
+         <menuchoice>
+         <guimenu>Table</guimenu>
+         <guimenuitem>Close</guimenuitem>
+         </menuchoice> which unloads the table from Thuban.
+         </para>
+         <para>
+         The status bar displays some statistics about the table and optional
+         selection results.
+         </para>
+     </section>
+     <section><title>General Functionality (Menu Table)</title>
+         <para>
+         The general functions affect all tables open in Thuban. Attribute
+         tables are considered here as normal data tables (with the exception
+         that they cannot be closed).
+         </para>
+         <section><title>Open</title>
+             <para>
+             The
+             <menuchoice>
+             <guimenu>Table</guimenu>
+             <guimenuitem>Open</guimenuitem>
+             </menuchoice>
+             item raises a file dialog to let you select a
+             dBase file from the file system to be loaded into Thuban read-only.
+             On <guibutton>OK</guibutton> the selected file is loaded and a
+             table view is opened.
+             </para>
+         </section>
+         <section><title>Close</title>
+             <para>
+             The
+             <menuchoice>
+             <guimenu>Table</guimenu>
+             <guimenuitem>Close</guimenuitem>
+             </menuchoice>
+             item raises a dialog listing the currently open
+             data tables
+             (loaded via
+             <menuchoice>
+             <guimenu>Table</guimenu>
+             <guimenuitem>Open</guimenuitem>
+             </menuchoice>). Selected tables are dereferenced on confirmation.
+             Since tables are opened read-only the contents of the tables are
+             not affected.
+             Any open views of the tables are closed as well.
+             Tables used in a join cannot be closed.
+             </para>
+         </section>
+         <section><title>Rename</title>
+             <para>
+             <menuchoice>
+             <guimenu>Table</guimenu>
+             <guimenuitem>Rename</guimenuitem>
+             </menuchoice> changes the table title.
+             </para>
+         </section>
+         <section><title>Show</title>
+             <para>
+             The
+             <menuchoice>
+             <guimenu>Table</guimenu>
+             <guimenuitem>Show</guimenuitem>
+             </menuchoice>
+             item raises a list of available tables (explicitly
+             loaded, attribute tables, results of a join). Selected tables are
+             show in tables views on <guibutton>OK</guibutton>.
+             </para>
+         </section>
+         <section><title>Join</title>
+             <para>
+             <figure>
+             <title>Join Tables</title>
+             <mediaobject>
+             <imageobject><imagedata fileref="../images/7_2_5_join.png" format="PNG" scale="&imgscale;"/></imageobject>
+             <imageobject><imagedata fileref="./images/7_2_5_join.eps" format="EPS" scale="&imgscale;"/></imageobject>
+             </mediaobject>
+             </figure>
+             </para>
+             <para>
+             The
+             <menuchoice>
+             <guimenu>Table</guimenu>
+             <guimenuitem>Join</guimenuitem>
+             </menuchoice>
+             item raises a dialog to specify the two tables to be
+             joined. The join results in a new table named 'Join of "left table"
+             and "right table"'.
+             The dialog lets you select the two tables to be joined and the two
+             fields the join has to be performed on. By default, the new
+             table contains only those records which are matched by the join.
+             If you want to preserve the records of the left table you can
+             perform an outer join. The fields from the right table for records
+             not matched by the join are filled with <varname>None</varname> in
+             this case.
+             </para>
+         </section>
+     </section>
+     <section><title>Attribute Tables</title>
+         <para>
+             To clearly separate between both types of tables (data and
+         attribute), Thuban provides functionality regarding the attribute
+         tables under the <menuchoice><guimenu>Layer</guimenu></menuchoice> menu.
+         </para>
+         <section><title>Show Table</title>
+             <para>
+             <menuchoice>
+             <guimenu>Layer</guimenu>
+             <guimenuitem>Show Table</guimenuitem>
+             </menuchoice>
+             opens the attribute table of the currently active layer in a table
+             view.
+             In addition to the functionality described above selections
+             affect also the map display: objects related to selected records
+             are highlighted.
+             </para>
+         </section>
+         <section><title>Join Table</title>
+             <para>
+             Unlike the join described above, the join does not result in a
+             new table. The attribute table of the currently active layer is the
+             left table and other tables are joined to this table. The results of
+             the join are available for classification.
+             As a consequence, the join cannot result in fewer
+             records than the source attribute table. The user is warned if the
+             right table does not fulfill this constraint. An outer join must be
+             used in such cases.
+             </para>
+         </section>
+         <section><title>Unjoin Table</title>
+             <para>
+             As said above, a normal table cannot be closed while it is still
+             used in a join. While the joined table resulting from a join of
+             normal tables can be simply closed (and thereby dereferencing
+             the source tables), this is not possible for attribute tables.
+             Hence joins on attribute tables must be solved explicitly. This is
+             what the
+             <menuchoice>
+             <guimenu>Layer</guimenu>
+             <guimenuitem>Unjoin Table</guimenuitem>
+             </menuchoice>
+             item is used for: The last join for the currently
+             active layer is solved.
+             </para>
+         </section>
+     </section>
+   </chapter>
+   <chapter><title>Extensions</title>
+         <para>
+         Thuban is designed to be extensible. The term Extension is used as a
+         general term for anything that extends Thuban.
+         This chapter introduces into some oppportunities how to add and
+         handle extra functionality developed by your own or third parties.
+         </para>
+         <section><title>Add personal extensions via thubanstart.py</title>
+                 <para>
+                 After Thuban has been started for the first time, a directory
+                 .thuban is created within your home directory.
+                 There you can add a file thubanstart.py  which will be imported
+                 by Thuban at start-up. It is recommended to add only import-statements
+                 to this file to keep the actual code of extensions separate.
+                 </para>
+                 <para>
+                 The modules to import must either be found through the environment
+                 variable PYTHONPATH or directly be placed into the .thuban-directory.
+                 </para>
+                 <para>
+                 As an example, copy the file examples/simple_extensions/hello_world.py
+                 of the Thuban source code into the .thuban-directory of your home
+                 directory. Now add add the statement import hello_world to the
+                 file thubanstart.py and run Thuban. You will notice an additional
+                 menu <menuchoice><guimenu>Extensions</guimenu></menuchoice> where
+                 the new item for the Hello-World extension is placed - select it
+                 to see the Hello-World message.
+                 </para>
+         </section>
+         <section><title>Writing simple extensions</title>
+                 <para>
+                 Writing an extension for Thuban basically means to
+                 implement the extra functionality in Python with all of the
+                 Thuban classes, methods and variables available.
+                 </para>
+                 <para>
+                 All classes and their methods are documented in the source code
+                 (see their doc-strings). Here is an example from
+                 Thuban/Model/layer.py that describes some of the methods
+                 of a Layer object:
+                 </para>
+                 <programlisting>
+                 <![CDATA[
+ class BaseLayer(TitledObject, Modifiable):
+     """Base class for the layers."""
+     def __init__(self, title, visible = True, projection = None):
+         """Initialize the layer.
+         title -- the title
+         visible -- boolean. If true the layer is visible.
+         """
+         TitledObject.__init__(self, title)
+         Modifiable.__init__(self)
+         self.visible = visible
+         self.projection = projection
+     def Visible(self):
+         """Return true if layer is visible"""
+         return self.visible
+     def SetVisible(self, visible):
+         """Set the layer's visibility."""
+         self.visible = visible
+         self.issue(LAYER_VISIBILITY_CHANGED, self)
+     def HasClassification(self):
+         """Determine if this layer support classifications."""
+ ...
+                 ]]>
+                 </programlisting>
+                 <para>
+                 This example intends to give you an impression of the
+                 source-code-level documentation.
+                 You have to make yourself familiar with
+                 the Python programming language to understand some special
+                 code elements.
+                 </para>
+                 <section><title>hello_world.py</title>
+                   <para>
+                   Traditionally, the first example should welcome the world.
+                   Most of the code handles the frame for integrating a menu
+                   item into Thuban while the actual raising of a message
+                   is done in a single line.
+                   </para>
+                         <programlisting>
+                         <![CDATA[
+ # Copyright (C) 2003 by Intevation GmbH
+ # Authors:
+ # Jan-Oliver Wagner <[email protected]>
+ #
+ # This program is free software under the GPL (>=v2)
+ # Read the file COPYING coming with Thuban for details.
+ """
+ Extend Thuban with a sample Hello World to demonstrate simple
+ extensions.
+ """
+ __version__ = '$Revision$'
+ # use _() already now for all strings that may later be translated
+ from Thuban import _
+ # Thuban has named commands which can be registered in the central
+ # instance registry.
+ from Thuban.UI.command import registry, Command
+ # The instance of the main menu of the Thuban application
+ # See Thuban/UI/menu.py for the API of the Menu class
+ from Thuban.UI.mainwindow import main_menu
+ def hello_world_dialog(context):
+     """Just raise a simple dialog to greet the world.
+     context -- The Thuban context.
+     """
+     context.mainwindow.RunMessageBox(_('Hello World'), _('Hello World!'))
+ # create a new command and register it
+ registry.Add(Command('hello_world', _('Hello World'), hello_world_dialog,
+                      helptext = _('Welcome everyone on this planet')))
+ # find the extensions menu (create it anew if not found)
+ extensions_menu = main_menu.find_menu('extensions')
+ if extensions_menu is None:
+     extensions_menu = main_menu.InsertMenu('extensions', _('E&xtensions'))
+ # finally bind the new command with an entry in the extensions menu
+ extensions_menu.InsertItem('hello_world')
+                         ]]>
+                         </programlisting>
+                 </section>
+                 <section><title>Registering a Command</title>
+                   <para>
+                   Mainly, our new function has to be registered to the Thuban
+                   framework in order to connect it to the menu. A registered
+                   command can also be connected to e.g. a toolbar button.
+                   </para>
+                   <para>
+                   The instances and classes for this are imported at the beginning.
+                   Any code not inside a method or class is directly executed when
+                   the source-code module is imported. Therefore, the second
+                   part of this example consist of the plain statements to create a new
+                   Command and to add it to the menu.
+                   </para>
+                   <para>
+                   By convention, it looks for a menu registered as ``extensions'' to
+                   insert the new command. If it does not exist yet, it gets created.
+                   It is advisable to copy this code for any of your extensions.
+                   </para>
+                 </section>
+                 <section><title>The Thuban context</title>
+                         <para>
+                         A registered command that is called, always receives the
+                         Thuban context. This instance provides our method with
+                         hook references to all important components of the Thuban
+                         application.
+                         </para>
+                         <para>
+                 In the example hello_world.py, our function uses the
+                         mainwindow component which offers a method to raise a
+                         message dialog. In total there are three hooks:
+                         <itemizedlist>
+                         <listitem>
+                         <para>application:
+                         This object is the instance of the Thuban Application class.
+                         Except maybe for loading or savinf sessions, you will not
+                         need this object for a simple extension.
+                         See Thuban/UI/application.py for the API.
+                         </para>
+                         </listitem>
+                         <listitem>
+                         <para>session:
+                         The instance of the current session. It manages the sessions'
+                         map and tables. You can set and remove the map or tables.
+                         In may also get the map object. However, you should know that
+                         internally it is already prepared to handle many maps.
+                         Therfore, currently you would always receive a list with exactlty
+                         one element. In the future, if there are more than one map,
+                         you will not know which one is the currently display one and
+                         therefore you should use the mainwindow as hook to find
+                         the currently displayed map.
+                         See Thuban/Model/session.py for the API.
+                         </para>
+                         </listitem>
+                         <listitem>
+                         <para>
+                         mainwindow: The mainwindow object is central to manage various
+                         GUI things such as the Legend sub-window. Most notably,
+                         you get access to the canvas which is the window part where
+                         the map is drawn. The canvas knows, which map it currently
+                         draws and therefore you get the current map via
+                         context.mainwindow.canvas.Map().
+                         See Thuban/UI/mainwindow.py for the API.
+                         </para>
+                         </listitem>
+                         </itemizedlist>
+             </para>
+                 </section>
+         </section>
    </chapter>
    <chapter><title>Trouble Shooting</title>
      <para>
+     Here are a few problems that users have encountered when first using Thuban.
+     </para>
+     <para>
+     <itemizedlist>
+     <listitem>
+     <para>After adding two or more layers nothing is drawn in the map window.
+     </para>
+     <para>
+     This is probably because the layers have different projections. Projections
+     must be set on all layers and on the map itself if the layers' projections
+     are different.
+     </para>
+     </listitem>
+     <listitem>
+     <para>Thuban crashes on startup with the error
+         <literal>NameError: global name 'False' is not defined</literal>.
+     </para>
+     <para>
+     <varname>True</varname> and <varname>False</varname> were only introduced
+     in Python 2.2.1. Thuban depends on at least Python 2.2.1.
+     </para>
+     </listitem>
+     <listitem>
+     <para>After compiling Thuban, Thuban crashes with an error similar to
+         <literal>
+         ImportError: /usr/local//lib/thuban/Thuban/../Lib/wxproj.so: undefined symbol: __gxx_personality_v0
+         </literal>
      </para>
+     <para>
+     Thuban depends on the wxWindows library. If Thuban is compiled with an
+     incompatible version of the compiler than wxWindows was compiled with
+     this error may occur. Try compiling with a different version of the
+     compiler.
+     </para>
+     </listitem>
+     </itemizedlist>
+     </para>
+     <para>
+     If an error occurs Thuban will display a dialog indicating the error
+     before closing. The text should be copied and reported to the
+     <ulink url="http://thuban.intevation.org/bugtracker.html">
+     Intevation bugtracker
+     </ulink>.
+     More information about the system is available from
+     <menuchoice><guimenu>Help</guimenu><guimenuitem>About</guimenuitem></menuchoice> box.
+     This should also be included in the bug report.
+     <figure>
+     <title>Error Dialog</title>
+     <mediaobject>
+     <imageobject><imagedata fileref="../images/8_int_error.png" format="PNG" scale="&imgscale;"/></imageobject>
+     <imageobject><imagedata fileref="./images/8_int_error.eps" format="EPS" scale="&imgscale;"/></imageobject>
+     </mediaobject>
+     </figure>
+     </para>
    </chapter>
    <appendix><title>Supported Data Sources</title>
      <para>
      </para>
+     <variablelist>
+     <varlistentry>
+     <term>Shapefile</term>
+     <listitem>
+         <para>
+         The Shapefile format has become a standard format for saving
+         geographic vector information. It supports polygons, lines, and
+         points.
+         <ulink url="http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf">
+         Technical Specification.
+         </ulink>
+         </para>
+     </listitem>
+     </varlistentry>
+     <varlistentry>
+     <term>dBase file</term>
+     <listitem>
+         <para>
+         dBase files are used to store the attributes for each layer. This
+         is closely associated with the Shapefile format. For detailed
+         specifications on the correct format of a dBase file used with
+         Thuban please see the Technical Specification for the Shapefile
+         format above.
+         </para>
+     </listitem>
+     </varlistentry>
+     <varlistentry>
+     <term>Raster files</term>
+     <listitem>
+         <para>
+         Binding the GDAL library Thuban supports numerous raster file formats,
+         see <ulink url="http://www.remotesensing.org/gdal/formats_list.html">
+         GDAL format list</ulink> for details.</para>
+         <para>Most commonly used is the <emphasis>TIFF/GeoTIFF</emphasis>
+         format: Raster maps are provided as TIFF images, with an additional
+         "world file" storing the geographic reference (usually with an
+         extension ".tfw").
+         </para>
+     </listitem>
+     </varlistentry>
+     </variablelist>
    </appendix>
    <appendix><title>Supported Projections</title>
      <para>
+     The following types of projections are directly support by
+     Thuban. The specific values for each are provided by the user
+     to create custom projections. Thuban comes with predefined
+     projections which are available through the Projections dialog.
+     </para>
+     <itemizedlist>
+     <listitem>
+         <para>Geographic</para>
+         <itemizedlist>
+         <listitem><para><literal>Ellipsoid</literal></para></listitem>
+         <listitem><para>
+                 <literal>Source Data</literal>: either Degrees or Radians
+                 </para></listitem>
+         </itemizedlist>
+     </listitem>
+     <listitem>
+         <para>Lambert Conic Conformal</para>
+     <itemizedlist>
+         <listitem><para><literal>Ellipsoid</literal></para></listitem>
+         <listitem><para><literal>Latitude of 1st standard parallel</literal></para></listitem>
+         <listitem><para><literal>Latitude of 2nd standard parallel</literal></para></listitem>
+         <listitem><para><literal>Central Meridian</literal></para></listitem>
+         <listitem><para><literal>Latitude of Origin</literal></para></listitem>
+         <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
+         <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
+     </itemizedlist>
+     </listitem>
+     <listitem>
+         <para>Transverse Mercator</para>
+     <itemizedlist>
+         <listitem><para><literal>Ellipsoid</literal></para></listitem>
+         <listitem><para><literal>Latitude</literal>of origin</para></listitem>
+         <listitem><para><literal>Longitude</literal>at central meridian</para></listitem>
+         <listitem><para><literal>Scale Factor</literal>at central meridian</para></listitem>
+         <listitem><para><literal>False Easting</literal> (meters)</para></listitem>
+         <listitem><para><literal>False Northing</literal> (meters)</para></listitem>
+     </itemizedlist>
+     </listitem>
+     <listitem>
+         <para>Universal Transverse Mercator</para>
+     <itemizedlist>
+         <listitem><para><literal>Ellipsoid</literal></para></listitem>
+         <listitem><para><literal>Zone</literal>
+                 (can be guessed appling the Propose button)</para></listitem>
+         <listitem><para><literal>Southern Hemisphere</literal> flag</para></listitem>
+     </itemizedlist>
+     </listitem>
+     </itemizedlist>
+     <para>
+     Thuban comes with a sample set of map projections for various
+     European countries. Apart from the basic projection they differ
+     especially in their parameterization:
+     </para>
+     <itemizedlist>
+     <listitem><para>Belgium Datum 1972 (Lambert Conic Conformal)</para>
+     </listitem>
+     <listitem><para>Gauss-Boaga Zone 1 (Italy, Transverse Mercartor)</para>
+     </listitem>
+     <listitem><para>Gauss-Krueger Zone 2 (Germany, Transverse Mercartor)
+     </para>
+     </listitem>
+     <listitem><para>Reseau Geodesique Francaise
+     (France, Lambert Conic Conformal)</para>
+     </listitem>
+     <listitem><para>UK National Grid (United Kingdom, Transverse Mercartor)
+     </para>
+     </listitem>
+     </itemizedlist>
+     <para>
+     Thuban uses the comprehensive PROJ library for projections. PROJ provides
+     more than the four commonly used projections described above. If needed
+     Thuban can be easily extended to a new projection covered by PROJ.
      </para>
    </appendix>
  </book>

 Legend:



Removed from v.1446
 


changed lines


 
Added in v.1719
 Legend:



Removed from v.1446
 


changed lines


 
Added in v.1719
-Removed from v.1446
+Added in v.1719

[email protected]	ViewVC Help
Powered by ViewVC 1.1.26