/[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 1478 by frank,
Thu Jul 24 17:00:25 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>
-     </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 47
+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>.
-         </para>
+         <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="../images/1_2_mainwindow.png" format="PNG"/> </imageobject>
+         <imageobject> <imagedata fileref="../images/1_2_mainwindow.png" format="PNG" scale="&imgscale;"/> </imageobject>
-         <imageobject> <imagedata fileref="./images/1_2_mainwindow.ps" format="EPS"/> </imageobject>
+         <imageobject> <imagedata fileref="./images/1_2_mainwindow.ps" format="EPS" scale="&imgscale;"/> </imageobject>
-         <textobject><phrase>The Main Window</phrase></textobject>
-         <caption><para>The Main Window</para></caption>
          </mediaobject>
-         </screenshot>
+         </figure>
          </para>
          <para>
-Line 100
+Line 285
          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 116
+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 131
+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 145
+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>
-Line 163
+Line 369
      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 use added to a map: shape layers
+         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
-         standard file format for storing geographic objects. Normally, these
+         widely used file format for storing geographic objects. These
          files have the extension ``.shp''. Associated with
-         the object information is a database file which stores attributes for
+         the shape file is a database file which stores attributes for
-         each shape in the Shapefile. This file, stored in DB2 format, usually
+         each shape in the Shape file. This file, in dBase format,
-         has the extension ``.dbf''. Both files should have the same base name.
+         has the extension ``.dbf''. Both files must have the same base name.
-         For example, if there is a Shapefile named roads.shp there should
+         For example, if there is a shape file named roads.shp there must
          also be a file roads.dbf.
          </para>
          <para>
-Line 182
+Line 407
          <guimenu>Map</guimenu>
          <guimenuitem>Add Layer</guimenuitem>
          </menuchoice>.
-         Thuban will load all files with the same base name, so it doesn't
+         Initially, only the ``.shp'' files are shown which is enough for the
-         matter if the Shapefile or database file is selected.
+                 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>
-Line 193
+Line 425
          <guimenuitem>Add Image Layer</guimenuitem>
          </menuchoice>.
          It is important to select a valid image file that has geographic
-         data associated with it. This can be embedded in the file itself,
+         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>
-Line 202
+Line 434
          <section><title>Navigation</title>
          <para>
          The map can be explored by using the navigation tools available on
-         the tool bar, or from the
+         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"/>
+         <imagedata fileref="../images/3_2_zoomin.png" format="PNG" scale="&imgscale;"/>
          </imageobject>
          <imageobject>
-         <imagedata fileref="./images/3_2_zoomin.eps" format="EPS"/>
+         <imagedata fileref="./images/3_2_zoomin.eps" format="EPS" scale="&imgscale;"/>
          </imageobject>
          <textobject> <phrase>ZoomIn Tool</phrase> </textobject>
          </inlinemediaobject>
-         can be used to enlarge a region of the map. Clicking once on the map
+         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 lets the user select a region
+         was clicked. Clicking and dragging selects a region that will be
-         to be enlarged to fit the window.
+         enlarged to fit the window.
          </para>
+         </listitem>
+         <listitem>
          <para>
          The ZoomOut tool
          <inlinemediaobject>
          <imageobject>
-         <imagedata fileref="../images/3_2_zoomout.png" format="PNG"/>
+         <imagedata fileref="../images/3_2_zoomout.png" format="PNG" scale="&imgscale;"/>
          </imageobject>
          <imageobject>
-         <imagedata fileref="./images/3_2_zoomout.eps" format="EPS"/>
+         <imagedata fileref="./images/3_2_zoomout.eps" format="EPS" scale="&imgscale;"/>
          </imageobject>
          <textobject> <phrase>ZoomOut Tool</phrase> </textobject>
          </inlinemediaobject>
-Line 237
+Line 473
          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"/>
+         <imagedata fileref="../images/3_2_pan.png" format="PNG" scale="&imgscale;"/>
          </imageobject>
          <imageobject>
-         <imagedata fileref="./images/3_2_pan.eps" format="EPS"/>
+         <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"/>
+         <imagedata fileref="../images/3_2_fullextent.png" format="PNG" scale="&imgscale;"/>
          </imageobject>
          <imageobject>
-         <imagedata fileref="./images/3_2_fullextent.eps" format="EPS"/>
+         <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"/>
+         <imagedata fileref="../images/3_2_fulllayerextent.png" format="PNG" scale="&imgscale;"/>
          </imageobject>
          <imageobject>
-         <imagedata fileref="./images/3_2_fulllayerextent.eps" format="EPS"/>
+         <imagedata fileref="./images/3_2_fulllayerextent.eps" format="EPS" scale="&imgscale;"/>
          </imageobject>
          <textobject> <phrase>Full Layer Extent Tool</phrase> </textobject>
          </inlinemediaobject>
-Line 278
+Line 520
          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"/>
+         <imagedata fileref="../images/3_2_fullshapeextent.png" format="PNG" scale="&imgscale;"/>
          </imageobject>
          <imageobject>
-         <imagedata fileref="./images/3_2_fullshapeextent.eps" format="EPS"/>
+         <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.
+         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>
-Line 301
+Line 550
          Objects on the map can be identified using the Identify tool
          <inlinemediaobject>
          <imageobject>
-         <imagedata fileref="../images/3_3_identify.png" format="PNG"/>
+         <imagedata fileref="../images/3_3_identify.png" format="PNG" scale="&imgscale;"/>
          </imageobject>
          <imageobject>
-         <imagedata fileref="./images/3_3_identify.eps" format="EPS"/>
+         <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.
+         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 labelled using the Label tool
+         Objects can be labeled using the Label tool
          <inlinemediaobject>
          <imageobject>
-         <imagedata fileref="../images/3_3_label.png" format="PNG"/>
+         <imagedata fileref="../images/3_3_label.png" format="PNG" scale="&imgscale;"/>
          </imageobject>
          <imageobject>
-         <imagedata fileref="./images/3_3_label.eps" format="EPS"/>
+         <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. Using this tool for an
+         be selected to be the label on the map. The label will be placed
-         object that already has a label will remove the label.
+         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.
-Line 346
+Line 608
          <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>.
+         <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>
-Line 359
+Line 749
          <menuchoice>
          <guimenu>Map</guimenu>
          <guimenuitem>Print</guimenuitem>
-         </menuchoice>. A standard printing dialog will open allowing the
+         </menuchoice>. The current map view, legend, and, if available,
-         user to configure the printer.
+         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 374
+Line 767
          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, and points. Image layers can be any image
+         shapes: polygons, lines (arc), and points. Image layers can be any image
-         file format supported by GDAL. The images must have geographic
+         file format supported by the Geo-spatial Data Abstraction Library
-         coordinate data either embedded within the file, or in a seperate
+         (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>Properties</title>
          <para>
-         Each shape in a shape layer can have various properties which control
+         To view the properties for a layer it must first be selected in the
-         how it is drawn on the map. Polygons and points can be drawn with an
+         legend. The menu option
-         outline color and a fill color, while lines have only a line color.
+         <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>
-Line 396
+Line 822
          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
-         each time the map is changed. Each layer can be independently
+         all the layers each time the map is changed. Each layer can be
-         turned on or off using the
+         independently turned on or off using the
          <menuchoice>
          <guimenu>Layer</guimenu>
          <guimenuitem>Show</guimenuitem>
-Line 410
+Line 836
          </para>
          </section>
-         <section><title>Sequence</title>
-         <para>
-         </para>
-         </section>
          <section><title>Duplication</title>
          <para>
          Layers and all their properties, including classifications, can
-Line 424
+Line 845
          <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
+         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
+         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
-Line 445
+Line 866
      cannot be classified.
      </para>
      <para>
-     A classification consists of a number of groups, with each group
+     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
-Line 458
+Line 879
      <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. Every shape in the layer, regardless of its
+     group cannot be removed but can be hidden (see below). Every shape in the
-     attributes, will match this group.
+     layer, regardless of its attributes, will match this group if no other
+     group matches.
      </para>
          <section><title>Editing Classifications</title>
-Line 476
+Line 898
          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
-         other than the DEFAULT group so that groups higher in the list will
+         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>
-         <para>
+             <section><title>Visible</title>
-         The Value column of the classification table is the value that will
+             <para>
-         be matched when the map is being drawn. The type of data that can
+             The Visible column has check-boxes that determine whether a
-         entered into this field depends on the type of data of the
+             classification group will be displayed in the legend. This is
-         classification field.
+             useful if the user knows that the groups completely cover
-         </para>
+             the data set and don't want the DEFAULT group to be displayed
-         <para>
+             in the legend and on a printout.
-         If the field is of type Text, anything entered
+             </para>
-         into the field is valid. The text will be compared literally to the
+         </section>
-         value of the shape attribute, including case sensitivity.
+             <section><title>Symbols</title>
-         If the type is Integer, then any valid integer may be entered. In
+             <para>
-         addition, with special syntax, a range of values can be entered.
+             Each type of shape has its own type of symbol. Thuban supports three
-         A range from <varname>start</varname> to <varname>end</varname>
+             types of shapes: polygons, lines, and points. Polygons and points
-         inclusive is specifed like this: <literal>[start;end]</literal>.
+             have outline and fill color, while lines have only line color. Each
-         The exclusive range is specified like this:
+             group has associated symbol properties. To edit the symbol
-         <literal>]start;end[</literal>. Ranges can include infinity like
+             properties for a group the user can double click on the Symbol
-         this: <literal>[-oo;oo]</literal>. Field types can also be of type
+             column or select a group and click the
-         Decimal. They represent any rational number and can be used in ranges
+             <guibutton>Edit Symbol</guibutton> button.
-         as well.
+             </para>
-         </para>
+             </section>
-         </section>
+         <section><title>Value</title>
+             <para>
-         <section><title>Symbols</title>
+             The Value column of the classification table is the value that will
-         <para>
+             be matched when the map is being drawn. The type of data that can
-         Each type of shape has its own type of symbol. Thuban supports three
+             entered into this field depends on the type of data of the
-         types of shapes: polygons, lines, and points. Polygons and points have
+             classification field.
-         outline and fill color, while lines have only line color. Each group
+             </para>
-         has associated symbol properties. To edit the symbol properties for a
+             <para>
-         group the user can double click on the Symbol column or select a
+             If the field is of type Text, anything entered
-         group and click the <guibutton>Edit Symbol</guibutton> button.
+             into the field is valid. The text will be compared literally to the
-         </para>
+             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>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>
+         <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> pulldown there are at most
+         Under the <varname>Generate</varname> pull down there are at most
          three different ways to generate classifications:
-         Unique Values, Unique Distribution, and Quantiles. Some options
+         Unique Values, Uniform Distribution, and Quantiles. Some options
-         may not be available if they data type for the field does not
+         may not be available if the data type for the field does not
-         support them. For instance, <varname>Unique Distribution</varname>
+         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
-Line 551
+Line 1033
          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 Unique Distribution option creates a user specified number of
+         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 items
+         The Quantiles option generates ranges based on the number of items
-         in the input set. For example, by specifying 5 groups Thuban will
+         in the table. For example, by specifying five groups Thuban will
-         generate groups with appropriate ranges such that 20% of the table
+         generate five groups with appropriate ranges such that 20% of the table
          data is in each group. If it is impossible to generate exact
-         grouping, Thuban will issue a warning but allow the user to continue.
+         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>
-Line 574
+Line 1077
      <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 tell Thuban
+     is in a different projection system, then the user must specify a
-     which projection each layer has. The user must also tell Thuban which
+     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
-Line 587
+Line 1090
      <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 to others.
+     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 be initially highlighted
+         or map already has a projection it will initially be highlighted
          and will end with <varname>(current)</varname>. Selecting
-         <varname>None</varname> will cause Thuban to use the data as
+         <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>
-Line 608
+Line 1118
          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
-         the <guibutton>Update</guibutton>. Only a projection that comes
+         <guibutton>Update</guibutton>. Only a projection that comes
          from a file can be updated, so if the current layer's projection
-         is selectd, <guibutton>Update</guibutton> will be disabled.
+         is selected, <guibutton>Update</guibutton> will be disabled.
-         The <guibutton>Add to List</guibutton> adds the projection to the
+         <guibutton>Add to List</guibutton> adds the projection to the
-         list of available projections as a new entry, and thus make it
+         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 permanantly remove a
+         <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 to store those projections.
+         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 session.
+         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
+     Thuban distinguishes two different types of tables: Attribute tables
-             (which belong to a layer) and usual data tables. Both provide in
+     (which belong to a layer) and normal data tables. Both provide
-         general the same functionality with the difference that actions on an
+         the same general functionality with the difference that actions on an
-             attribute table might also effect the map display.
+     attribute table might also effect the map display.
      </para>
      <section><title>Table View</title>
-       <para>
+         <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 falls into five sections: The title, selections,
+         Table View. The view has five sections: The title, selections,
-         the table grid, export functions and the status bar.
+         the table grid, export functions, and the status bar.
-       </para>
+         </para>
-       <para>
+         <para>
-         The title bar identifies the table with it's name.
+         The title bar identifies the table with its name.
-       </para>
+         </para>
-       <para>
+         <para>
-         The functions box let the user perform simple analysis on the data
+         The selections box let the user perform simple analysis on the data
-         based on comparisons: First choice must be a field identifier of the
+         based on comparisons: The first choice must be a field identifier of
-         table, the second choice determines the type of comparison. The third
+         the table, the second choice determines the type of comparison. The
-         choice can be either a specific value (interpreted as numerical
+         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 "population > 10000" or
+         records where <literal>population > 10000</literal> or
-         "cars_per_habitants <  bike_per_habitants" (note that the field names
+         <literal>cars_per_inhabitant < bikes_per_inhabitant</literal>
-         are only explanatory, the currently considered dbase files allow only
+         (note that the field names are only explanatory, the dBase files
-character field names).
+         allow only 11 character field names).
-         Selections can be combined, either by applying a selection only on
+         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>
-       <para>
+         <para>
-         The table grid shows the contents of the table (a record per column),
+         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>
-       <para>
+         <para>
-         The contents of a table can be exported into a file, either dbase
+         The contents of a table can be exported into a file, either dBase
-         format (DBF) or comma seperated values (CSV). The 'Export' button
+         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 'Export Selection' button works similar but exports only the
+         The <guibutton>Export Selection</guibutton> button works similarly
-         selected records.
+         but exports only the selected records.
-         The 'Close' button closes the table view. In difference to the
+         The <guibutton>Close</guibutton> button closes the table view window.
-         menu item 'Close' just the dialog is closed, the table is still loaded
+         This is different from the menu item
-         in Thuban.
+         <menuchoice>
-       </para>
+         <guimenu>Table</guimenu>
-       <para>
+         <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>
+         </para>
      </section>
      <section><title>General Functionality (Menu Table)</title>
-       <para>
+         <para>
          The general functions affect all tables open in Thuban. Attribute
-         tables are considered as here as usual data tables (with the exception
+         tables are considered here as normal data tables (with the exception
          that they cannot be closed).
-       </para>
-       <section><title>Open</title>
-         <para>
-           The 'Open' item raises a file dialog to let you select a
-           dbase file from the file system to be loaded into Thuban read-only.
-           On OK the selected file is loaded and a table view is opened.
          </para>
-       </section>
+         <section><title>Open</title>
+             <para>
-       <section><title>Close</title>
+             The
-         <para>
+             <menuchoice>
-           The 'Close' item raises a dialog listing the currently open
+             <guimenu>Table</guimenu>
-           data tables (loaded via the 'Open' functionality'). You can select
+             <guimenuitem>Open</guimenuitem>
-           tables which are dereferenced on confirmation. Since tables are
+             </menuchoice>
-           opened read-only the contents of the tables are not affected.
+             item raises a file dialog to let you select a
+             dBase file from the file system to be loaded into Thuban read-only.
-           A still open table view is closed as well.
+             On <guibutton>OK</guibutton> the selected file is loaded and a
+             table view is opened.
-           Tables used in a join can not be closed.
+             </para>
-         </para>
+         </section>
-       </section>
+         <section><title>Close</title>
-       <section><title>Rename</title>
+             <para>
-         <para>
+             The
-           Changes the table title.
+             <menuchoice>
-         </para>
+             <guimenu>Table</guimenu>
-       </section>
+             <guimenuitem>Close</guimenuitem>
+             </menuchoice>
-       <section><title>Show</title>
+             item raises a dialog listing the currently open
-         <para>
+             data tables
-           The 'Show' item raises a list of available tables (explicitly loaded,           attribute tables, results of a join). Selected tables are show in
+             (loaded via
-           tables views on 'OK'.
+             <menuchoice>
-         </para>
+             <guimenu>Table</guimenu>
-       </section>
+             <guimenuitem>Open</guimenuitem>
+             </menuchoice>). Selected tables are dereferenced on confirmation.
-       <section><title>Join</title>
+             Since tables are opened read-only the contents of the tables are
-         <para>
+             not affected.
-           The 'Join' item raises a dialog to specify the two tables to be
-           joined. The join results in a new table named 'Join of "left table"
+             Any open views of the tables are closed as well.
-           and "right table"'.
+             Tables used in a join cannot be closed.
-           The dialog let you select the two tables to be joined and the two
+             </para>
-           fields the join has to be performed on. By default the new
+         </section>
-           table contains only those records which are mathced by the join.
+         <section><title>Rename</title>
-           If you want to preserve the records of the left table you can perform
+             <para>
-           an outer join. The fields from the right table for records not
+             <menuchoice>
-           matched by the join are filled with <varname>None</varname> in this
+             <guimenu>Table</guimenu>
-           case.
+             <guimenuitem>Rename</guimenuitem>
-         </para>
+             </menuchoice> changes the table title.
-       </section>
+             </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, Thuban provides functionality
-             regarding the attribute tables under the Layer menu.
-     </para>
-       <section><title>Show Table</title>
-         <para>
-           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>
-            In difference to the join described above the join results not in a
+             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 join to this table. Results of the
+             left table and other tables are joined to this table. The results of
-             join in turn are available for classifications.
+             the join are available for classification.
-             As a consequence of the above the join cannot result in less
-             records than the source attribute table. You are warned if the
-             right table does not fulfill this constraint. Use an outer join
-             in such cases.
-         </para>
-       </section>
-       <section><title>Unjoin Table</title>
+             As a consequence, the join cannot result in fewer
-         <para>
+             records than the source attribute table. The user is warned if the
-             As said above, a usual table can not be closed while still used in
+             right table does not fulfill this constraint. An outer join must be
-             a join. While the join table resulting from a join of usual tables
+             used in such cases.
-             can be simply closed (and therewith dereferences the source tables)
+             </para>
-             this is not possible for attribute tables.
+         </section>
-             Hence joins on attribute tables must be solved explicitely. This is
+         <section><title>Unjoin Table</title>
-             what the 'Unjoin' item is used for: The last join for the currently
+             <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>
+             </para>
-       </section>
+         </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>
-Line 806
+Line 1654
      <variablelist>
      <varlistentry>
      <term>Shapefile</term>
-     <listitem><para></para></listitem>
+     <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>DB2 file</term>
+     <term>dBase file</term>
-     <listitem><para></para></listitem>
+     <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>
-Line 819
+Line 1701
    <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>
-     <variablelist>
-     <varlistentry>
-     <term>Geographic</term>
-     <listitem><para>Geographic</para></listitem>
-     </varlistentry>
-     <varlistentry>
-     <term>Lambert Conic Conformal</term>
-     <listitem><para>Lambert Conic Conformal</para></listitem>
-     </varlistentry>
-     <varlistentry>
-     <term>Transverse Mercator</term>
-     <listitem><para>Transverse Mercator</para></listitem>
-     </varlistentry>
-     <varlistentry>
-     <term>Universal Transverse Mercator</term>
-     <listitem><para>Universal Transverse Mercator</para></listitem>
-     </varlistentry>
-     </variablelist>
    </appendix>
  </book>

 Legend:



Removed from v.1478
 


changed lines


 
Added in v.1719
 Legend:



Removed from v.1478
 


changed lines


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

[email protected]	ViewVC Help
Powered by ViewVC 1.1.26